Comparing version 1.5.4 to 1.6.1
@@ -0,1 +1,18 @@ | ||
#### 1.6.0 Milestone Release | ||
- New date/time formatting and parsing capability (issue #166) | ||
- Support for comments in expressions (issue #75) | ||
- Higher-order extension functions (issue #259) | ||
- Allow Boolean to be cast to a number (issue #257) | ||
- New functions | ||
- $eval - parse/evaluate the contexts of a JSON/JSONata string (issue #134) | ||
- $formatInteger - format an integer to a string using picture string definition | ||
- $parseInteger - parse an integer from a string using picture string definition | ||
- Non-functional enhancements: | ||
- Split codebase into multiple files; fixed multiple issues with ES5 generated library | ||
- Multiple conformance tests in a single file | ||
- Documentation moved to main jsonata repo; generated using docusaurus.io | ||
- Minimum node.js runtime v6 (dropped support for v4) | ||
- Numerous bug fixes (#236, #179, #261, #236, #245, #246, #233, #250, #247, #242, #249) | ||
#### 1.5.4 Maintenance Release | ||
@@ -125,5 +142,5 @@ | ||
- $reduce - apply a function to aggregate (fold) all values in an array | ||
#### 1.1.1 Maintenance Release | ||
@@ -155,2 +172,2 @@ | ||
- messages maintained in separate catalog | ||
{ | ||
"name": "jsonata", | ||
"version": "1.5.4", | ||
"version": "1.6.1", | ||
"description": "JSON query and transformation language", | ||
"module": "jsonata.js", | ||
"main": "jsonata-es5.js", | ||
"main": "jsonata.js", | ||
"typings": "jsonata.d.ts", | ||
@@ -17,11 +17,15 @@ "homepage": "http://jsonata.org/", | ||
"test": "npm run mocha", | ||
"posttest": "npm run check-coverage && npm run minify && npm run babel && npm run browserify && npm run minify-es5", | ||
"posttest": "npm run check-coverage && npm run browserify && npm run minify && npm run build-es5", | ||
"build-es5": "npm run mkdir-dist && npm run regenerator && npm run browserify-es5 && npm run minify-es5", | ||
"check-coverage": "istanbul check-coverage -statement 100 -branch 100 -function 100 -line 100", | ||
"minify": "uglifyjs jsonata.js -o jsonata.min.js --compress --mangle", | ||
"lint": "eslint .", | ||
"browserify": "browserify src/jsonata.js --outfile jsonata.js --standalone jsonata", | ||
"mkdir-dist": "mkdirp ./dist", | ||
"regenerator": "regenerator src dist; regenerator --include-runtime src/jsonata.js > dist/jsonata.js", | ||
"browserify-es5": "cat polyfill.js > jsonata-es5.js; browserify dist/jsonata.js --standalone jsonata >> jsonata-es5.js", | ||
"prepublishOnly": "npm run browserify && npm run minify && npm run build-es5", | ||
"lint": "eslint src", | ||
"doc": "jsdoc --configure jsdoc.json .", | ||
"cover": "istanbul cover _mocha", | ||
"coveralls": "npm run cover -- --report lcovonly && cat ./coverage/lcov.info | coveralls", | ||
"babel": "node ./node_modules/babel-cli/bin/babel.js --out-file jsonata-es5.js jsonata.js", | ||
"browserify": "node ./node_modules/browserify/bin/cmd.js jsonata-es5.js --outfile jsonata-es5.js --standalone jsonata", | ||
"minify": "uglifyjs jsonata.js -o jsonata.min.js --compress --mangle", | ||
"minify-es5": "uglifyjs jsonata-es5.js -o jsonata-es5.min.js --compress --mangle" | ||
@@ -39,6 +43,2 @@ }, | ||
"devDependencies": { | ||
"babel-cli": "^6.24.1", | ||
"babel-plugin-transform-runtime": "^6.23.0", | ||
"babel-preset-env": "^1.5.2", | ||
"babel-runtime": "^6.23.0", | ||
"browserify": "^16.1.0", | ||
@@ -52,4 +52,6 @@ "chai": "^4.1.2", | ||
"jsdoc": "^3.4.0", | ||
"mkdirp": "^0.5.1", | ||
"mocha": "^5.0.0", | ||
"mocha-lcov-reporter": "^1.2.0", | ||
"regenerator": "^0.13.2", | ||
"request": "^2.81.0", | ||
@@ -59,4 +61,4 @@ "uglify-es": "^3.0.20" | ||
"engines": { | ||
"node": ">= 4" | ||
"node": ">= 6" | ||
} | ||
} |
184
README.md
@@ -1,3 +0,5 @@ | ||
# jsonata | ||
# JSONata | ||
JSON query and transformation language | ||
[![NPM statistics](https://nodei.co/npm/jsonata.png?downloads=true&downloadRank=true)](https://nodei.co/npm/jsonata/) | ||
@@ -8,5 +10,5 @@ | ||
JavaScript implementation of the [JSONata query and transformation language](http://jsonata.org/). | ||
Reference implementation of the [JSONata query and transformation language](http://jsonata.org/). | ||
* [JSONata tutorial](tutorial.md) | ||
* [JSONata in 5 minutes](https://www.youtube.com/embed/ZBaK40rtIBM) | ||
* [JSONata language documentation](http://docs.jsonata.org/) | ||
@@ -19,3 +21,3 @@ * [Try it out!](http://try.jsonata.org/) | ||
## Usage | ||
## Quick start | ||
@@ -46,3 +48,3 @@ In Node.js: | ||
<title>JSONata test</title> | ||
<script src="lib/jsonata.js"></script> | ||
<script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script> | ||
<script> | ||
@@ -64,171 +66,7 @@ function greeting() { | ||
`jsonata` uses ES2015 features such as [generators](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Statements/function*). For browsers lacking these features, `lib/jsonata-es5.js` is provided. | ||
## API | ||
### jsonata(str) | ||
Parse a string `str` as a JSONata expression and return a compiled JSONata expression object. | ||
```javascript | ||
var expression = jsonata("$sum(example.value)"); | ||
``` | ||
If the expression is not valid JSONata, an `Error` is thrown containing information about the nature of the syntax error, for example: | ||
``` | ||
{ | ||
code: "S0202", | ||
stack: "...", | ||
position: 16, | ||
token: "}", | ||
value: "]", | ||
message: "Syntax error: expected ']' got '}'" | ||
} | ||
``` | ||
`expression` has three methods: | ||
#### expression.evaluate(input[, bindings[, callback]]) | ||
Run the compiled JSONata expression against object `input` and return the result as a new object. | ||
```javascript | ||
var result = expression.evaluate({example: [{value: 4}, {value: 7}, {value: 13}]}); | ||
``` | ||
`input` should be a JavaScript value such as would be returned from `JSON.parse()`. If `input` could not have been parsed from a JSON string (is circular, contains functions, ...), `evaluate`'s behaviour is not defined. `result` is a new JavaScript value suitable for `JSON.stringify()`ing. | ||
`bindings`, if present, contains variable names and values (including functions) to be bound: | ||
```javascript | ||
jsonata("$a + $b()").evaluate({}, {a: 4, b: () => 78}); | ||
// returns 82 | ||
``` | ||
`expression.evaluate()` may throw a run-time `Error`: | ||
```javascript | ||
var expression = jsonata("$notafunction()"); // OK, valid JSONata | ||
expression.evaluate({}); // Throws | ||
``` | ||
The `Error` contains information about the nature of the run-time error, for example: | ||
``` | ||
{ | ||
code: "T1006", | ||
stack: "...", | ||
position: 14, | ||
token: "notafunction", | ||
message: "Attempted to invoke a non-function" | ||
} | ||
``` | ||
If `callback(err, value)` is supplied, `expression.evaluate()` returns `undefined`, the expression is run asynchronously and the `Error` or result is passed to `callback`. | ||
```javascript | ||
jsonata("7 + 12").evaluate({}, {}, (error, result) => { | ||
if(error) { | ||
console.error(error); | ||
return; | ||
} | ||
console.log("Finished with", result); | ||
}); | ||
console.log("Started"); | ||
// Prints "Started", then "Finished with 19" | ||
``` | ||
#### expression.assign(name, value) | ||
Permanently binds a value to a name in the expression, similar to how `bindings` worked above. Modifies `expression` in place and returns `undefined`. Useful in a JSONata expression factory. | ||
```javascript | ||
var expression = jsonata("$a + $b()"); | ||
expression.assign("a", 4); | ||
expression.assign("b", () => 1); | ||
expression.evaluate({}); // 5 | ||
``` | ||
Note that the `bindings` argument in the `expression.evaluate()` call clobbers these values: | ||
```javascript | ||
expression.evaluate({}, {a: 109}); // 110 | ||
``` | ||
#### expression.registerFunction(name, implementation[, signature]) | ||
Permanently binds a function to a name in the expression. | ||
```javascript | ||
var expression = jsonata("$greet()"); | ||
expression.registerFunction("greet", () => "Hello world"); | ||
expression.evaluate({}); // "Hello world" | ||
``` | ||
You can do this using `expression.assign` or `bindings` in `expression.evaluate`, but `expression.registerFunction` allows you to specify a function `signature`. This is a terse string which tells JSONata the expected input argument types and return value type of the function. JSONata raises a run-time error if the actual input argument types do not match (the return value type is not checked yet). | ||
```javascript | ||
var expression = jsonata("$add(61, 10005)"); | ||
expression.registerFunction("add", (a, b) => a + b, "<nn:n>"); | ||
expression.evaluate({}); // 10066 | ||
``` | ||
Function signatures are specified like so: | ||
##### Function signature syntax | ||
A function signature is a string of the form `<params:return>`. `params` is a sequence of type symbols, each one representing an input argument's type. `return` is a single type symbol representing the return value type. | ||
Type symbols work as follows: | ||
Simple types: | ||
- `b` - Boolean | ||
- `n` - number | ||
- `s` - string | ||
- `l` - `null` | ||
Complex types: | ||
- `a` - array | ||
- `o` - object | ||
- `f` - function | ||
Union types: | ||
- `(sao)` - string, array or object | ||
- `(o)` - same as `o` | ||
- `u` - equivalent to `(bnsl)` i.e. Boolean, number, string or `null` | ||
- `j` - any JSON type. Equivalent to `(bnsloa)` i.e. Boolean, number, string, `null`, object or array, but not function | ||
- `x` - any type. Equivalent to `(bnsloaf)` | ||
Parametrised types: | ||
- `a<s>` - array of strings | ||
- `a<x>` - array of values of any type | ||
Some examples of signatures of built-in JSONata functions: | ||
- `$count` has signature `<a:n>`; it accepts an array and returns a number. | ||
- `$append` has signature `<aa:a>`; it accepts two arrays and returns an array. | ||
- `$sum` has signature `<a<n>:n>`; it accepts an array of numbers and returns a number. | ||
- `$reduce` has signature `<fa<j>:j>`; it accepts a reducer function `f` and an `a<j>` (array of JSON objects) and returns a JSON object. | ||
Each type symbol may also have *options* applied. | ||
- `+` - one or more arguments of this type | ||
- E.g. `$zip` has signature `<a+>`; it accepts one array, or two arrays, or three arrays, or... | ||
- `?` - optional argument | ||
- E.g. `$join` has signature `<a<s>s?:s>`; it accepts an array of strings and an optional joiner string which defaults to the empty string. It returns a string. | ||
- `-` - if this argument is missing, use the context value ("focus"). | ||
- E.g. `$length` has signature `<s-:n>`; it can be called as `$length(OrderID)` (one argument) but equivalently as `OrderID.$length()`. | ||
## More information | ||
- JSONata [language documentation](http://docs.jsonata.org/) | ||
- JSONata [tech talk](https://developer.ibm.com/open/videos/dw-open-tech-talk-jsonata/) | ||
- JSONata [documentation](http://docs.jsonata.org/) | ||
- [JavaScript API](http://docs.jsonata.org/embedding-extending) | ||
- [Intro talk](https://www.youtube.com/watch?v=TDWf6R8aqDo) at London Node User Group | ||
- JSONata [tech talk](https://www.youtube.com/watch?v=ZRtlkIj0uDY) | ||
@@ -235,0 +73,0 @@ ## Contributing |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Minified code
QualityThis package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Uses eval
Supply chain riskPackage uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.
Found 1 instance in 1 package
721949
14
14160
0
2
72
8