11 |
29 |
30 |
52 |
53 |
54 |
--------------------------------------------------------------------------------
/jest.config.ts:
--------------------------------------------------------------------------------
1 | /*
2 | * For a detailed explanation regarding each configuration property and type check, visit:
3 | * https://jestjs.io/docs/configuration
4 | */
5 |
6 | export default {
7 | // All imported modules in your tests should be mocked automatically
8 | // automock: false,
9 |
10 | // Stop running tests after `n` failures
11 | // bail: 0,
12 |
13 | // The directory where Jest should store its cached dependency information
14 | // cacheDirectory: "/private/var/folders/62/f7brm_9n2p75sc79zx9718_w0000gp/T/jest_dy",
15 |
16 | // Automatically clear mock calls, instances, contexts and results before every test
17 | clearMocks: true,
18 |
19 | // Indicates whether the coverage information should be collected while executing the test
20 | // collectCoverage: false,
21 |
22 | // An array of glob patterns indicating a set of files for which coverage information should be collected
23 | collectCoverageFrom: ['Rudder Json Template Engine
12 |
13 |
18 | Template:
14 | 17 |
19 |
24 | Data:
20 | 23 |
25 |
28 | Output:
26 | 27 |
2 |
3 | 
4 |
5 |
The Customer Data Platform for Developers
8 | 9 |10 | 11 | Website 12 | · 13 | Documentation 14 | · 15 | Community Slack 16 | 17 |
18 | 19 | --- 20 | 21 | # JSON Template Engine 22 | 23 | ## Overview 24 | 25 | Welcome to our JSON Template Engine! This powerful tool simplifies transforming JSON data from one format to another, making managing and maintaining complex integrations easier. 26 | 27 | ### Why JSON Template Engine? 28 | 29 | As an integration platform supporting over 200 integrations, we understand the challenges of maintaining and optimizing these connections. Traditionally, we used native JavaScript code for data transformation, which required significant effort and maintenance. While JSONata offered a more efficient way to manipulate JSON data, we still encountered performance bottlenecks due to its parsing and interpretation overhead. 30 | 31 | ### Our Solution 32 | 33 | To address these challenges, we've developed our own JSON Transformation Engine. This engine generates optimized JavaScript code from transformation templates, reducing runtime overhead and significantly improving performance. 34 | 35 | ## Key Features 36 | 37 | - **Efficiency**: Our engine generates JavaScript code that minimizes parsing and interpretation overhead, ensuring faster execution. 38 | 39 | - **Extensibility**: Easily add new transformation templates to meet your specific integration needs. 40 | 41 | - **Simplicity**: Write concise transformation templates that are easy to understand and maintain. 42 | 43 | ## Implementation 44 | 45 | This library generates a javascript function code from the template and then uses the function to evaluate the JSON data. It outputs the javascript code in the following stages: 46 | 47 | 1. [Lexing](src/lexer.ts) (Tokenization) 48 | 1. [Parsing](src/parser.ts) (AST Creation) 49 | 1. [Translation](src/translator.ts) (Code generation) 50 | 51 | ```mermaid 52 | flowchart TD; 53 | A[Code] --> B[Convert code to tokens]; 54 | B --> C[Parse tokens to create Expressions]; 55 | C --> D[Combine expressions to create statements]; 56 | D --> E[Combine statements to create AST]; 57 | E --> F[Translate AST to JS code] 58 | ``` 59 | 60 | [Engine](src/engine.ts) class abstracts the above steps and provides a convenient way to use the json templates to evaluate the inputs. 61 | 62 | ## Getting started 63 | 64 | ### Use npm package 65 | 66 | `npm install @rudderstack/json-template-engine` 67 | 68 | ```ts 69 | const { JsonTemplateEngine } = require('@rudderstack/json-template-engine'); 70 | const engine = JsonTemplateEngine.create(`'Hello ' + .name`); 71 | engine.evaluate({ name: 'World' }); // => 'Hello World' 72 | ``` 73 | 74 | ### Use CDN URL directly in the browser 75 | Latest URL: https://cdn.jsdelivr.net/npm/@rudderstack/json-template-engine/build/json-template.min.js 76 | 77 | Versioned URL: https://cdn.jsdelivr.net/npm/@rudderstack/json-template-engine@0.19.5/build/json-template.min.js 78 | 79 | ```html 80 | 85 | ``` 86 | 87 | 88 | Refer this [example](/index.html) for more details. 89 | 90 | [Demo](https://rudderlabs.github.io/rudder-json-template-engine/) 91 | 92 | ### Playground 93 | Give the JSON template engine a try in our [playground](https://transformers-workflow-engine.rudderstack.com/#/json-template) without needing to install anything. 94 | 95 | ## Features 96 | 97 | The template consists of multiple statements, with the output being the result of the final statement. 98 | 99 | 100 | ### Variables 101 | 102 | ```js 103 | const a = 1; 104 | let b = a + 2; 105 | a + b; 106 | ``` 107 | 108 | Refer this [example](test/scenarios/assignments/template.jt) for more details. 109 | 110 | #### Template Strings 111 | 112 | ```js 113 | let a = `Input a=${.a}`; 114 | let b = `Input b=${.b}`; 115 | `${a}, ${b}`; 116 | ``` 117 | Refer this [example](test/scenarios/template_strings/template.jt) for more details. 118 | 119 | ### Basic Expressions 120 | 121 | #### Conditions 122 | 123 | ```js 124 | a > b ? a : c; 125 | ``` 126 | 127 | Refer this [example](test/scenarios/conditions/template.jt) for more details. 128 | 129 | #### Comparisons 130 | 131 | ```js 132 | a === b || c > d; 133 | ``` 134 | 135 | Refer this [example](test/scenarios/comparisons/template.jt) for more details. 136 | 137 | #### Math Operations 138 | 139 | ```js 140 | 10 - 2 + 2 * 10; 141 | ``` 142 | 143 | Refer this [example](test/scenarios/math/template.jt) for more details. 144 | 145 | #### Logical operations 146 | 147 | ```js 148 | false || true; 149 | ``` 150 | 151 | Refer this [example](test/scenarios/logics/template.jt) for more details. 152 | 153 | ### Input and Bindings 154 | 155 | Input refers to the JSON document we would like to process using a template. Bindings refer to additional data or functions we would provide to process the data efficiently. 156 | 157 | Example: 158 | 159 | - Template: `"Hello " + (.name ?? $.defaultName)` 160 | - Evaluation: `engine.evaluate({name: 'World'}, {defaultName: 'World'});` 161 | - `{name: 'World'}` is input. 162 | - `^.name` refers to "name" property of the input. We can also use `.name` to refer the same. `^` always refers to the root of the input and `.` refers to current context. Refer this [example](test/scenarios/selectors/context_variables.jt) for more details. 163 | - `{defaultName: 'World'}` is bindings. 164 | - `$.defaultName` refers to "defaultName" property of the bindings. Refer this [example](test/scenarios/bindings/template.jt) for more details. 165 | 166 | ### Arrays 167 | 168 | ```js 169 | let arr = [1, 2, 3, 4] 170 | let a = arr[1, 2] // [2, 3] 171 | let b = arr[0:2] // [1, 2] 172 | let c = arr[-2:] // [3, 4] 173 | ``` 174 | 175 | Refer this [example](test/scenarios/arrays/template.jt) for more details. 176 | 177 | ### Objects 178 | 179 | ```js 180 | let key = "some key" 181 | // { "a": 1, "b": 2, "c": 3, "some key": 4 } 182 | let obj = {a: 1, b: 2, c: 3, [key]: 4 } 183 | let a = obj["a"] // 1 184 | let b = obj.a // 1 185 | let c = obj{["a", "b"]} // { "a": 1, "b": 2} 186 | let d = obj{~["a", "b"]} // { "c": 3, "some key": 4} 187 | ``` 188 | 189 | Refer this [example](test/scenarios/objects/template.jt) for more details. 190 | 191 | #### Object Context Props 192 | ```js 193 | let obj = {a: 1, b: 2, c: 3 }; 194 | obj.({ 195 | @e [e.key]: e.value * e.value, // @e refers to each key, value pairs, 196 | d: 16 // we can have other props also 197 | }) // { a: 1, b: 4, c: 9, d: 16} 198 | ``` 199 | Refer this [example](test/scenarios/objects/context_props.jt) for more details. 200 | 201 | ### Functions 202 | 203 | #### Normal functions 204 | 205 | ```js 206 | let fn = function (arg1, arg2) { 207 | arg1 + arg2; 208 | }; 209 | ``` 210 | 211 | The result of the last statement of function will be returned as result of the function. We can also use rest params (`...args`). 212 | 213 | #### Lambda/Short functions 214 | 215 | ```js 216 | let fn = array.map(lambda 2 * ?0); 217 | ``` 218 | 219 | This function gets converted to: 220 | 221 | ```js 222 | let fn = array.map(function (args) { 223 | 2 * args[0]; 224 | }); 225 | ``` 226 | 227 | Lambda functions are short to express the intention and it is convenient sometimes. 228 | 229 | #### Async functions 230 | 231 | ```js 232 | let fn = async function (arg1, arg2) { 233 | const result = await doSomethingAsync(arg1, arg2); 234 | doSomethingSync(result); 235 | }; 236 | ``` 237 | 238 | **Note:** When we want to use async functions then we need to create template engine using `JsonTemplateEngine.create`. If you create a template this way then it will be created as an async function so we can `await` anywhere in the template. 239 | 240 | ```js 241 | let result = await doSomething(.a, .b) 242 | ``` 243 | 244 | Refer this [example](test/scenarios/functions/template.jt) for more details. 245 | 246 | ### Paths 247 | 248 | Paths are used to access properties in `input`, `bindings` and `variables`. 249 | 250 | #### Simple Paths 251 | 252 | Simple paths support limited path features and get translated as direct property access statements in the generate javascript code. 253 | `a.b.c` gets translated to `a?.b?.c` so they are very fast compared to [Rich paths](#rich-paths). Simple paths are ideal when we know the object structure. 254 | 255 | **Supported features:** 256 | 257 | - [Simple Selectors](#simple-selectors) 258 | - [Single Index Filters](#single-index-or-property-filters) 259 | Refer this [example](test/scenarios/paths/simple_path.jt) for more details. 260 | 261 | #### Rich Paths 262 | 263 | Rich paths gets converted complex code to support different variations in the data. 264 | 265 | If we use this rich path`~r a.b.c` then it automatically handles following variations. 266 | 267 | - `[{"a": { "b": [{"c": 2}]}}]` 268 | - `{"a": { "b": [{"c": 2}]}}` 269 | - `{"a": [{ "b": [{"c": 2}]}]}` 270 | Refer this [example](test/scenarios/paths/rich_path.jt) for more details. 271 | 272 | #### Json Paths 273 | We support some features of [JSON Path](https://goessner.net/articles/JsonPath/index.html#) syntax using path option (`~j`). 274 | Note: This is an experimental feature and may not support all the features of JSON Paths. 275 | 276 | Refer this [example](test/scenarios/paths/json_path.jt) for more details. 277 | 278 | #### Simple selectors 279 | 280 | ```js 281 | let x = a.b.c; 282 | let y = a."some key".c 283 | ``` 284 | 285 | Refer this [example](test/scenarios/selectors/template.jt) for more details. 286 | 287 | #### Wildcard selectors 288 | 289 | ```js 290 | a.*.c // selects c from any direct property of a 291 | ``` 292 | 293 | Refer this [example](test/scenarios/selectors/wild_cards.jt) for more details. 294 | 295 | #### Descendent selectors 296 | 297 | ```js 298 | // selects c from any child property of a 299 | // a.b.c, a.b1.b2.c or a.b1.b2.b3.c 300 | let x = a..c; 301 | let y = a.."some key"; 302 | ``` 303 | 304 | Refer this [example](test/scenarios/selectors/template.jt) for more details. 305 | 306 | #### Single Index or Property Filters 307 | 308 | ```js 309 | let x = a[0].c; 310 | let y = a[-1].c; // selects last element from array 311 | let z = a['some key'].c; 312 | ``` 313 | 314 | Refer this [example](test/scenarios/filters/array_filters.jt) for more details. 315 | 316 | #### Multi Indexes or Properties Filters 317 | 318 | ```js 319 | let x = a[(0, 2, 5)].c; 320 | let y = a[('some key1', 'some key2')].c; 321 | ``` 322 | 323 | Refer this [example](test/scenarios/filters/array_filters.jt) for more details. 324 | 325 | #### Range filters 326 | 327 | ```js 328 | let x = a[2:5].c; 329 | let y = a[:-2].c; 330 | let z = a[2:].c; 331 | ``` 332 | 333 | #### Object Property Filters 334 | 335 | ```js 336 | let x = obj{["a", "b"]}; // selects a and b 337 | let y = obj{~["a", "b"]}; // selects all properties except a and b 338 | ``` 339 | 340 | Refer this [example](test/scenarios/filters/object_indexes.jt) for more details. 341 | 342 | #### Conditional or Object Filters 343 | 344 | ```js 345 | let x = obj{.a > 1}; 346 | ``` 347 | 348 | Refer this [example](test/scenarios/filters/object_filters.jt) for more details. 349 | 350 | #### Block expressions 351 | 352 | ```js 353 | let x = obj.({ 354 | a: .a + 1, 355 | b: .b + 2 356 | }); 357 | let x = obj.([.a+1, .b+2]); 358 | ``` 359 | 360 | Refer this [example](test/scenarios/paths/block.jt) for more details. 361 | 362 | #### Context Variables 363 | 364 | ```js 365 | .orders@order#idx.products.({ 366 | name: .name, 367 | price: .price, 368 | orderNum: idx, 369 | orderId: order.id 370 | }) 371 | ``` 372 | 373 | Use context variables: `@order` and `#idx`, we can combine properties of orders and products together. Refer this [example](test/scenarios/context_variables/template.jt) for more details. 374 | 375 | #### Path Options 376 | 377 | We can mention defaultPathType while creating engine instance. 378 | 379 | ```js 380 | // For using simple path as default path type 381 | // a.b.c will be treated as simple path 382 | JsonTemplateEngine.create(`a.b.c`, { defaultPathType: PathType.SIMPLE }); 383 | // For using rich path as default path type 384 | // a.b.c will be treated as rich path 385 | JsonTemplateEngine.create(`a.b.c`, { defaultPathType: PathType.RICH }); 386 | ``` 387 | 388 | We can override the default path option using tags. 389 | 390 | ```js 391 | // Use ~s to treat a.b.c as simple path 392 | ~s a.b.c 393 | // Use ~r to treat a.b.c as rich path 394 | ~r a.b.c 395 | // Use ~j for using json paths 396 | ~j items[?(@.a>1)] 397 | ``` 398 | 399 | **Note:** Rich paths are slower compare to the simple paths. 400 | Refer this [example](test/scenarios/paths/options.jt) for more details. 401 | 402 | ### Compile time expressions 403 | 404 | Compile time expressions are evaluated during compilation phase using compileTimeBindings option. 405 | 406 | ```js 407 | // {{$.a.b.c}} gets translated to 1 and 408 | // final translated code will be "let a = 1;" 409 | JsonTemplateEngine.create(`let a = {{$.a.b.c}};`, { 410 | compileTimeBindings: { 411 | a: { 412 | b: { 413 | c: 1, 414 | }, 415 | }, 416 | }, 417 | }); 418 | ``` 419 | 420 | We can use compile time expressions to generate a template and then recompile it as expression. Refer these examples [simple compilation](test/scenarios/compile_time_expressions/template.jt) and [complex compilation](test/scenarios/compile_time_expressions/two_level_path_processing.jt) for more details. 421 | 422 | ### Mappings 423 | If you are familiar with [JSON Paths](https://goessner.net/articles/JsonPath/index.html#), you can easily begin working with JSON templates by leveraging your existing knowledge through the mappings feature. 424 | 425 | **Example:** 426 | * Let's say we want to transform the following data. 427 | * Input: 428 | ```json 429 | { 430 | "a": { 431 | "foo": 1, 432 | "bar": 2 433 | }, 434 | "b": [ 435 | { 436 | "firstName": "foo", 437 | "lastName": "bar" 438 | }, 439 | { 440 | "firstName": "fizz", 441 | "lastName": "buzz" 442 | } 443 | ] 444 | } 445 | ``` 446 | * Output: 447 | ```json 448 | { 449 | "foo": 1, 450 | "bar": 2, 451 | "items":[ 452 | { 453 | "name": "foo bar" 454 | }, 455 | { 456 | "name": "fizz buzz" 457 | } 458 | ] 459 | } 460 | ``` 461 | * Mappings: 462 | ```json 463 | [ 464 | { 465 | "description": "Copies properties of a to root level in the output", 466 | "input": "$.a", 467 | "output": "$" 468 | }, 469 | { 470 | "description": "Combines first and last name in the output", 471 | "input": "$.b[*].(@.firstName + ' ' + @.lastName)", 472 | "output": "$.items[*].name" 473 | } 474 | ] 475 | ``` 476 | * Try this example in our [playground](https://transformers-workflow-engine.rudderstack.com/#/mappings?gist=e25a6ac769ee5719e928720f5c439169). 477 | 478 | For more examples, refer [Mappings](test/scenarios/mappings/) 479 | 480 | ### Comments 481 | 482 | Supports both c style single line (`//`) and block comments (`/* .. */`). 483 | Refer this [example](test/scenarios/comments/template.jt) for more details. 484 | 485 | For more examples, refer [Scenarios](test/scenarios) 486 | 487 | ## Testing 488 | 489 | `npm test` 490 | 491 | ## Contribute 492 | 493 | We would love to see you contribute to RudderStack. Get more information on how to contribute [**here**](CONTRIBUTING.md). 494 | 495 | ## License 496 | 497 | The RudderStack `rudder-json-template-engine` is released under the [**MIT License**](https://opensource.org/licenses/MIT). 498 | -------------------------------------------------------------------------------- /release-please-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", 3 | "release-type": "node", 4 | "include-component-in-tag": false, 5 | "packages": { 6 | ".": { 7 | "extra-files": ["readme.md"] 8 | } 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /sonar-project.properties: -------------------------------------------------------------------------------- 1 | sonar.log.level=INFO 2 | sonar.verbose=false 3 | sonar.qualitygate.wait=false 4 | 5 | # Project details 6 | sonar.projectKey=rudderlabs_rudder-json-template-engine 7 | sonar.organization=rudderlabs 8 | sonar.projectName=rudder-json-template-engine 9 | sonar.projectVersion=0.8.2 10 | 11 | # Meta-data for the project 12 | sonar.links.scm=https://github.com/rudderlabs/rudder-json-template-engine 13 | sonar.links.issue=https://github.com/rudderlabs/rudder-json-template-engine/issues 14 | 15 | # Path to reports 16 | sonar.javascript.lcov.reportPaths=reports/coverage/lcov.info 17 | sonar.eslint.reportPaths=reports/eslint.json 18 | 19 | # Path to sources 20 | sonar.sources=src 21 | sonar.inclusions=**/*.ts 22 | sonar.exclusions=**/*.json,**/*.html,**/*.png,**/*.jpg,**/*.gif,**/*.svg,**/*.yml 23 | # Path to tests 24 | sonar.tests=test 25 | sonar.test.inclusions=**/*.test.ts 26 | sonar.test.exclusions=**/*.json,**/*.html,**/*.png,**/*.jpg,**/*.gif,**/*.svg 27 | sonar.coverage.exclusions=test/**/*,**/*.json,**/*.html,**/*.png,**/*.jpg,**/*.gif,**/*.svg 28 | 29 | # Source encoding 30 | sonar.sourceEncoding=UTF-8 31 | 32 | # Exclusions for copy-paste detection 33 | sonar.cpd.exclusions=test/**/* -------------------------------------------------------------------------------- /src/constants.ts: -------------------------------------------------------------------------------- 1 | import { SyntaxType } from './types'; 2 | 3 | export const VARS_PREFIX = '___'; 4 | export const DATA_PARAM_KEY = '___d'; 5 | export const BINDINGS_PARAM_KEY = '___b'; 6 | export const BINDINGS_CONTEXT_KEY = '___b.context.'; 7 | export const RESULT_KEY = '___r'; 8 | export const FUNCTION_RESULT_KEY = '___f'; 9 | export const INDENTATION_SPACES = 4; 10 | export const EMPTY_EXPR = { type: SyntaxType.EMPTY }; 11 | -------------------------------------------------------------------------------- /src/engine.test.ts: -------------------------------------------------------------------------------- 1 | import { JsonTemplateEngine } from './engine'; 2 | import { PathType } from './types'; 3 | 4 | describe('engine', () => { 5 | describe('isValidJSONPath', () => { 6 | it('should return true for valid JSON root path', () => { 7 | expect(JsonTemplateEngine.isValidJSONPath('$.user.name')).toBeTruthy(); 8 | }); 9 | 10 | it('should return true for valid JSON relative path', () => { 11 | expect(JsonTemplateEngine.isValidJSONPath('.user.name')).toBeTruthy(); 12 | 13 | expect(JsonTemplateEngine.isValidJSONPath('@.user.name')).toBeTruthy(); 14 | }); 15 | 16 | it('should return false for invalid JSON path', () => { 17 | expect(JsonTemplateEngine.isValidJSONPath('userId')).toBeFalsy(); 18 | }); 19 | 20 | it('should return false for invalid template', () => { 21 | expect(JsonTemplateEngine.isValidJSONPath('a=')).toBeFalsy(); 22 | }); 23 | 24 | it('should return false for empty path', () => { 25 | expect(JsonTemplateEngine.isValidJSONPath('')).toBeFalsy(); 26 | }); 27 | }); 28 | describe('validateMappings', () => { 29 | it('should validate mappings', () => { 30 | expect(() => 31 | JsonTemplateEngine.validateMappings([ 32 | { 33 | input: '$.userId', 34 | output: '$.user.id', 35 | }, 36 | { 37 | input: '$.discount', 38 | output: '$.events[0].items[*].discount', 39 | }, 40 | ]), 41 | ).not.toThrow(); 42 | }); 43 | 44 | it('should throw error for mappings which are not compatible with each other', () => { 45 | expect(() => 46 | JsonTemplateEngine.validateMappings([ 47 | { 48 | input: '$.a[0]', 49 | output: '$.b[0].name', 50 | }, 51 | { 52 | input: '$.discount', 53 | output: '$.b[0].name[*].discount', 54 | }, 55 | ]), 56 | ).toThrowError('Invalid mapping'); 57 | }); 58 | 59 | it('should throw error for mappings with invalid json paths', () => { 60 | expect(() => 61 | JsonTemplateEngine.validateMappings([ 62 | { 63 | input: 'events[0]', 64 | output: 'events[0].name', 65 | }, 66 | ]), 67 | ).toThrowError('Invalid mapping'); 68 | }); 69 | }); 70 | describe('isValidMapping', () => { 71 | it('should convert to JSON paths when options are used', () => { 72 | expect( 73 | JsonTemplateEngine.isValidMapping( 74 | { 75 | input: '$.a[0]', 76 | output: 'b[0].name', 77 | }, 78 | { defaultPathType: PathType.JSON }, 79 | ), 80 | ).toBeTruthy(); 81 | }); 82 | it('should throw error when output is not valid json path without engine options', () => { 83 | expect( 84 | JsonTemplateEngine.isValidMapping({ 85 | input: '$.events[0]', 86 | output: 'events[0].name', 87 | }), 88 | ).toBeFalsy(); 89 | }); 90 | }); 91 | }); 92 | -------------------------------------------------------------------------------- /src/engine.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable import/no-cycle */ 2 | import { BINDINGS_PARAM_KEY, DATA_PARAM_KEY, EMPTY_EXPR } from './constants'; 3 | import { JsonTemplateMappingError } from './errors/mapping'; 4 | import { JsonTemplateLexer } from './lexer'; 5 | import { JsonTemplateParser } from './parser'; 6 | import { JsonTemplateReverseTranslator } from './reverse_translator'; 7 | import { JsonTemplateTranslator } from './translator'; 8 | import { 9 | EngineOptions, 10 | Expression, 11 | FlatMappingAST, 12 | FlatMappingPaths, 13 | PathType, 14 | SyntaxType, 15 | TemplateInput, 16 | } from './types'; 17 | import { CreateAsyncFunction, convertToObjectMapping, isExpression } from './utils'; 18 | 19 | export class JsonTemplateEngine { 20 | private readonly fn: Function; 21 | 22 | private constructor(fn: Function) { 23 | this.fn = fn; 24 | } 25 | 26 | private static compileAsSync(template: TemplateInput, options?: EngineOptions): Function { 27 | // eslint-disable-next-line @typescript-eslint/no-implied-eval 28 | return Function( 29 | DATA_PARAM_KEY, 30 | BINDINGS_PARAM_KEY, 31 | JsonTemplateEngine.translate(template, options), 32 | ); 33 | } 34 | 35 | private static compileAsAsync(templateOrExpr: TemplateInput, options?: EngineOptions): Function { 36 | return CreateAsyncFunction( 37 | DATA_PARAM_KEY, 38 | BINDINGS_PARAM_KEY, 39 | JsonTemplateEngine.translate(templateOrExpr, options), 40 | ); 41 | } 42 | 43 | private static translateExpression(expr: Expression): string { 44 | const translator = new JsonTemplateTranslator(expr); 45 | return translator.translate(); 46 | } 47 | 48 | static isValidJSONPath(path: string = ''): boolean { 49 | try { 50 | const expression = JsonTemplateEngine.parse(path, { defaultPathType: PathType.JSON }); 51 | const statement = expression.statements?.[0]; 52 | return ( 53 | statement && 54 | statement.type === SyntaxType.PATH && 55 | (!statement.root || statement.root === DATA_PARAM_KEY) 56 | ); 57 | } catch (e) { 58 | return false; 59 | } 60 | } 61 | 62 | private static toJsonPath(input: string): string { 63 | if (input.startsWith('$')) { 64 | return input; 65 | } 66 | 67 | // Check if it's wrapped in quotes 68 | // or is a simple identifier 69 | // or contains dots 70 | if ( 71 | /^'.*'$/.test(input) || 72 | /^".*"$/.test(input) || 73 | /^\w+$/.test(input) || 74 | input.includes('.') 75 | ) { 76 | return `$.${input}`; 77 | } 78 | 79 | // If input contains special characters 80 | return `$.'${input}'`; 81 | } 82 | 83 | private static convertToJSONPath(path?: string, options?: EngineOptions): string | undefined { 84 | if (!path) { 85 | return path; 86 | } 87 | if (options?.defaultPathType === PathType.JSON) { 88 | return JsonTemplateEngine.toJsonPath(path); 89 | } 90 | return path; 91 | } 92 | 93 | private static prepareMapping(mapping: FlatMappingPaths, options?: EngineOptions) { 94 | return { 95 | ...mapping, 96 | input: mapping.input ?? mapping.from, 97 | output: JsonTemplateEngine.convertToJSONPath(mapping.output ?? mapping.to, options), 98 | }; 99 | } 100 | 101 | private static prepareMappings( 102 | mappings: FlatMappingPaths[], 103 | options?: EngineOptions, 104 | ): FlatMappingPaths[] { 105 | return mappings 106 | .map((mapping) => JsonTemplateEngine.prepareMapping(mapping, options)) 107 | .filter((mapping) => mapping.input && mapping.output); 108 | } 109 | 110 | static validateMappings(mappings: FlatMappingPaths[], options?: EngineOptions) { 111 | JsonTemplateEngine.prepareMappings(mappings, options).forEach((mapping) => { 112 | if (!JsonTemplateEngine.isValidJSONPath(mapping.output)) { 113 | throw new JsonTemplateMappingError( 114 | 'Invalid mapping: invalid JSON path', 115 | mapping.input as string, 116 | mapping.output as string, 117 | ); 118 | } 119 | }); 120 | JsonTemplateEngine.parseMappingPaths(mappings, options); 121 | } 122 | 123 | static isValidMapping(mapping: FlatMappingPaths, options?: EngineOptions) { 124 | try { 125 | JsonTemplateEngine.validateMappings([mapping], options); 126 | return true; 127 | } catch (e) { 128 | return false; 129 | } 130 | } 131 | 132 | private static createFlatMappingsAST( 133 | mappings: FlatMappingPaths[], 134 | options?: EngineOptions, 135 | ): FlatMappingAST[] { 136 | const newOptions = { ...options, mappings: true }; 137 | return JsonTemplateEngine.prepareMappings(mappings, options) 138 | .filter((mapping) => mapping.input && mapping.output) 139 | .map((mapping) => ({ 140 | ...mapping, 141 | inputExpr: JsonTemplateEngine.parse(mapping.input, newOptions).statements[0], 142 | outputExpr: JsonTemplateEngine.parse(mapping.output, newOptions).statements[0], 143 | })); 144 | } 145 | 146 | static parseMappingPaths(mappings: FlatMappingPaths[], options?: EngineOptions): Expression { 147 | return convertToObjectMapping(JsonTemplateEngine.createFlatMappingsAST(mappings, options)); 148 | } 149 | 150 | static create(templateOrExpr: TemplateInput, options?: EngineOptions): JsonTemplateEngine { 151 | return new JsonTemplateEngine(JsonTemplateEngine.compileAsAsync(templateOrExpr, options)); 152 | } 153 | 154 | static createAsSync(template: TemplateInput, options?: EngineOptions): JsonTemplateEngine { 155 | return new JsonTemplateEngine(JsonTemplateEngine.compileAsSync(template, options)); 156 | } 157 | 158 | static parse(template: TemplateInput, options?: EngineOptions): Expression { 159 | if (!template) { 160 | return EMPTY_EXPR; 161 | } 162 | if (isExpression(template)) { 163 | return template as Expression; 164 | } 165 | if (typeof template === 'string') { 166 | const lexer = new JsonTemplateLexer(template); 167 | const parser = new JsonTemplateParser(lexer, options); 168 | return parser.parse(); 169 | } 170 | return JsonTemplateEngine.parseMappingPaths(template as FlatMappingPaths[], options); 171 | } 172 | 173 | static translate(template: TemplateInput, options?: EngineOptions): string { 174 | return JsonTemplateEngine.translateExpression(JsonTemplateEngine.parse(template, options)); 175 | } 176 | 177 | static reverseTranslate(expr: Expression | FlatMappingPaths[], options?: EngineOptions): string { 178 | const translator = new JsonTemplateReverseTranslator(options); 179 | let newExpr = expr; 180 | if (Array.isArray(expr)) { 181 | newExpr = JsonTemplateEngine.parseMappingPaths(expr, options); 182 | } 183 | return translator.translate(newExpr as Expression); 184 | } 185 | 186 | static convertMappingsToTemplate(mappings: FlatMappingPaths[], options?: EngineOptions): string { 187 | return JsonTemplateEngine.reverseTranslate( 188 | JsonTemplateEngine.parse(mappings, options), 189 | options, 190 | ); 191 | } 192 | 193 | static evaluateAsSync( 194 | template: TemplateInput, 195 | options: EngineOptions = {}, 196 | data: unknown = {}, 197 | bindings: Record