1- ![ Build] ( https://github.com/jmespath-community/typescript- jmespath/actions/workflows/nodejs.yml/badge.svg?branch=main )
1+ ![ Build] ( https://github.com/letsflow/ jmespath/actions/workflows/nodejs.yml/badge.svg?branch=main )
22
3- # @jmespath-community /jmespath
3+ # @letsflow /jmespath
44
5-
6- @jmespath-community/jmespath is a ** TypeScript** implementation of the [ JMESPath] ( https://jmespath.site/ ) spec.
5+ @letsflow/jmespath is a ** TypeScript** implementation of the [ JMESPath] ( https://jmespath.org/ ) spec.
76
87JMESPath is a query language for JSON. It will take a JSON document
98as input and transform it into another JSON document
109given a JMESPath expression.
1110
11+ This fork extends the original specs, adding the following functionality;
12+
13+ * [ Custom functions] ( #custom-functions )
14+ * [ Root value access] ( #root-value-access )
15+ * [ Number literals] ( #number-literals )
16+
1217## INSTALLATION
1318
1419```
15- npm install @jmespath-community /jmespath
20+ npm install @letsflow /jmespath
1621```
1722
1823## USAGE
1924
2025### ` search(data: JSONValue, expression: string): JSONValue `
2126
2227``` javascript
23- import { search } from ' @jmespath-community /jmespath' ;
28+ import { search } from ' @letsflow /jmespath' ;
2429
2530search (
26- {foo: {bar: {baz: [0 , 1 , 2 , 3 , 4 ]}} },
31+ { foo: { bar: { baz: [0 , 1 , 2 , 3 , 4 ] } } },
2732 " foo.bar.baz[2]"
28- );
33+ );
2934
3035// OUTPUTS: 2
3136```
@@ -39,48 +44,48 @@ The JMESPath language can do *a lot* more than select an element
3944from a list. Here are a few more examples:
4045
4146``` javascript
42- import { search } from ' @jmespath-community /jmespath' ;
47+ import { search } from ' @letsflow /jmespath' ;
4348
44- /* --- EXAMPLE 1 --- */
45-
46- let JSON_DOCUMENT = {
49+ const document = {
4750 foo: {
4851 bar: {
4952 baz: [0 , 1 , 2 , 3 , 4 ]
5053 }
5154 }
5255};
5356
54- search (JSON_DOCUMENT , " foo.bar" );
57+ search (document , " foo.bar" );
5558// OUTPUTS: { baz: [ 0, 1, 2, 3, 4 ] }
59+ ```
5660
61+ ``` javascript
62+ import { search } from ' @letsflow/jmespath' ;
5763
58- /* --- EXAMPLE 2 --- */
59-
60- JSON_DOCUMENT = {
64+ const document = {
6165 " foo" : [
62- {" first" : " a" , " last" : " b" },
63- {" first" : " c" , " last" : " d" }
66+ { " first" : " a" , " last" : " b" },
67+ { " first" : " c" , " last" : " d" }
6468 ]
6569};
6670
67- search (JSON_DOCUMENT , " foo[*].first" )
71+ search (document , " foo[*].first" )
6872// OUTPUTS: [ 'a', 'c' ]
73+ ```
6974
75+ ``` javascript
76+ import { search } from ' @letsflow/jmespath' ;
7077
71- /* --- EXAMPLE 3 --- */
72-
73- JSON_DOCUMENT = {
78+ const document = {
7479 " foo" : [
75- {" age" : 20 },
76- {" age" : 25 },
77- {" age" : 30 },
78- {" age" : 35 },
79- {" age" : 40 }
80+ { " age" : 20 },
81+ { " age" : 25 },
82+ { " age" : 30 },
83+ { " age" : 35 },
84+ { " age" : 40 }
8085 ]
8186}
8287
83- search (JSON_DOCUMENT , " foo[?age > `30`]" );
88+ search (document , " foo[?age > `30`]" );
8489// OUTPUTS: [ { age: 35 }, { age: 40 } ]
8590```
8691
@@ -95,82 +100,91 @@ import { compile, TreeInterpreter } from '@jmespath-community/jmespath';
95100
96101const ast = compile (' foo.bar' );
97102
98- TreeInterpreter .search (ast, {foo: {bar: ' BAZ' } })
103+ TreeInterpreter .search (ast, { foo: { bar: ' BAZ' } })
99104// RETURNS: "BAZ"
100-
101105```
102106
103- ---
104107## EXTENSIONS TO ORIGINAL SPEC
105108
106- 1 . ### Register you own custom functions
109+ ### Custom functions
107110
108- #### ` registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void `
111+ #### ` registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void `
109112
110- Extend the list of built in JMESpath expressions with your own functions.
113+ Extend the list of built- in JMESpath expressions with your own functions.
111114
112- ``` javascript
113- import {search , registerFunction , TYPE_NUMBER } from ' @jmespath-community/jmespath'
114-
115-
116- search ({ foo: 60 , bar: 10 }, ' divide(foo, bar)' )
117- // THROWS ERROR: Error: Unknown function: divide()
115+ ``` javascript
116+ import {search , registerFunction , TYPE_NUMBER } from ' @letsflow/jmespath'
117+
118+ search ({ foo: 60 , bar: 10 }, ' divide(foo, bar)' )
119+ // THROWS ERROR: Error: Unknown function: divide()
120+
121+ registerFunction (
122+ ' divide' , // FUNCTION NAME
123+ (resolvedArgs ) => { // CUSTOM FUNCTION
124+ const [dividend , divisor ] = resolvedArgs;
125+ return dividend / divisor;
126+ },
127+ [{ types: [TYPE_NUMBER ] }, { types: [TYPE_NUMBER ] }] // SIGNATURE
128+ );
118129
119- registerFunction (
120- ' divide' , // FUNCTION NAME
121- (resolvedArgs ) => { // CUSTOM FUNCTION
122- const [dividend , divisor ] = resolvedArgs;
123- return dividend / divisor;
124- },
125- [{ types: [TYPE_NUMBER ] }, { types: [TYPE_NUMBER ] }] // SIGNATURE
126- );
130+ search ({ foo: 60 , bar: 10 }, ' divide(foo, bar)' );
131+ // OUTPUTS: 6
132+ ```
127133
128- search ({ foo: 60 ,bar: 10 }, ' divide(foo, bar)' );
129- // OUTPUTS: 6
134+ Optional arguments are supported by setting ` {..., optional: true} ` in argument signatures
130135
131- ```
136+ ``` javascript
137+ registerFunction (
138+ ' divide' ,
139+ (resolvedArgs ) => {
140+ const [dividend , divisor ] = resolvedArgs;
141+ return dividend / divisor ?? 1 ; // OPTIONAL DIVISOR THAT DEFAULTS TO 1
142+ },
143+ [{ types: [TYPE_NUMBER ] }, { types: [TYPE_NUMBER ], optional: true }] // SIGNATURE
144+ );
132145
133- Optional arguments are supported by setting ` {..., optional: true}` in argument signatures
146+ search ({ foo: 60 , bar: 10 }, ' divide(foo)' );
147+ // OUTPUTS: 60
148+ ` ` `
134149
150+ ### Root value access
135151
136- ` ` ` javascript
152+ Use ` $ ` to access the document root.
137153
138- registerFunction(
139- 'divide',
140- (resolvedArgs) => {
141- const [dividend, divisor] = resolvedArgs;
142- return dividend / divisor ?? 1; //OPTIONAL DIVISOR THAT DEFAULTS TO 1
143- },
144- [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER], optional: true }] //SIGNATURE
145- );
154+ ` ` ` javascript
155+ search ({foo: { bar: 999 }, baz: [1 , 2 , 3 ]}, ' $.baz[*].[@, $.foo.bar]' )
146156
147- search({ foo: 60, bar: 10 }, 'divide(foo)');
148- // OUTPUTS: 60
157+ // OUTPUTS:
158+ // [ [ 1, 999 ], [ 2, 999 ], [ 3, 999 ] ]
159+ ` ` `
149160
150- ` ` `
161+ ### Number literals
151162
152- 2. ### Root value access with ` $` symbol
163+ Numbers in the root scope are treated as number literals. This means that you don't
164+ need to quote numbers with backticks.
153165
154166` ` ` javascript
167+ search ([{" bar" : 1 }, {" bar" : 10 }]}, ' [?bar==10]' )
155168
156- search({foo: {bar: 999}, baz: [1, 2, 3]}, '$.baz[*].[@, $.foo.bar]')
169+ // OUTPUTS;
170+ // [{"bar": 10}]
171+ ` ` `
172+
173+ You can also use numbers in arithmetic operations
157174
158- // OUTPUTS:
159- // [ [ 1, 999 ], [ 2, 999 ], [ 3, 999 ] ]
160175` ` `
176+ search ({}, ' 16 + 26' ); // 42
161177
178+ // With the original specs we'd need to do
179+ search ({}, ' `16` + `26`' );
180+ ` ` `
162181
163182## More Resources
164183
165- The example above only show a small amount of what
184+ The example above only shows a small amount of what
166185a JMESPath expression can do. If you want to take a
167186tour of the language, the *best* place to go is the
168- [JMESPath Tutorial](http: // jmespath.site/main#tutorial).
169-
170- One of the best things about JMESPath is that it is
171- implemented in many different programming languages including
172- python, ruby, php, lua, etc . To see a complete list of libraries,
173- check out the [JMESPath libraries page](http: // jmespath.site/main#libraries).
187+ [JMESPath Tutorial](https://jmespath.org/tutorial.html).
174188
175- And finally , the full JMESPath specification can be found
176- on the [JMESPath site](https: // jmespath.site/main/# specification).
189+ The full JMESPath specification can be found
190+ on the [JMESPath site](https://jmespath.org/ specification.html ).
0 commit comments