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 )
2
2
3
- # @jmespath-community /jmespath
3
+ # @letsflow /jmespath
4
4
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.
7
6
8
7
JMESPath is a query language for JSON. It will take a JSON document
9
8
as input and transform it into another JSON document
10
9
given a JMESPath expression.
11
10
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
+
12
17
## INSTALLATION
13
18
14
19
```
15
- npm install @jmespath-community /jmespath
20
+ npm install @letsflow /jmespath
16
21
```
17
22
18
23
## USAGE
19
24
20
25
### ` search(data: JSONValue, expression: string): JSONValue `
21
26
22
27
``` javascript
23
- import { search } from ' @jmespath-community /jmespath' ;
28
+ import { search } from ' @letsflow /jmespath' ;
24
29
25
30
search (
26
- {foo: {bar: {baz: [0 , 1 , 2 , 3 , 4 ]}} },
31
+ { foo: { bar: { baz: [0 , 1 , 2 , 3 , 4 ] } } },
27
32
" foo.bar.baz[2]"
28
- );
33
+ );
29
34
30
35
// OUTPUTS: 2
31
36
```
@@ -39,48 +44,48 @@ The JMESPath language can do *a lot* more than select an element
39
44
from a list. Here are a few more examples:
40
45
41
46
``` javascript
42
- import { search } from ' @jmespath-community /jmespath' ;
47
+ import { search } from ' @letsflow /jmespath' ;
43
48
44
- /* --- EXAMPLE 1 --- */
45
-
46
- let JSON_DOCUMENT = {
49
+ const document = {
47
50
foo: {
48
51
bar: {
49
52
baz: [0 , 1 , 2 , 3 , 4 ]
50
53
}
51
54
}
52
55
};
53
56
54
- search (JSON_DOCUMENT , " foo.bar" );
57
+ search (document , " foo.bar" );
55
58
// OUTPUTS: { baz: [ 0, 1, 2, 3, 4 ] }
59
+ ```
56
60
61
+ ``` javascript
62
+ import { search } from ' @letsflow/jmespath' ;
57
63
58
- /* --- EXAMPLE 2 --- */
59
-
60
- JSON_DOCUMENT = {
64
+ const document = {
61
65
" foo" : [
62
- {" first" : " a" , " last" : " b" },
63
- {" first" : " c" , " last" : " d" }
66
+ { " first" : " a" , " last" : " b" },
67
+ { " first" : " c" , " last" : " d" }
64
68
]
65
69
};
66
70
67
- search (JSON_DOCUMENT , " foo[*].first" )
71
+ search (document , " foo[*].first" )
68
72
// OUTPUTS: [ 'a', 'c' ]
73
+ ```
69
74
75
+ ``` javascript
76
+ import { search } from ' @letsflow/jmespath' ;
70
77
71
- /* --- EXAMPLE 3 --- */
72
-
73
- JSON_DOCUMENT = {
78
+ const document = {
74
79
" 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 }
80
85
]
81
86
}
82
87
83
- search (JSON_DOCUMENT , " foo[?age > `30`]" );
88
+ search (document , " foo[?age > `30`]" );
84
89
// OUTPUTS: [ { age: 35 }, { age: 40 } ]
85
90
```
86
91
@@ -95,82 +100,91 @@ import { compile, TreeInterpreter } from '@jmespath-community/jmespath';
95
100
96
101
const ast = compile (' foo.bar' );
97
102
98
- TreeInterpreter .search (ast, {foo: {bar: ' BAZ' } })
103
+ TreeInterpreter .search (ast, { foo: { bar: ' BAZ' } })
99
104
// RETURNS: "BAZ"
100
-
101
105
```
102
106
103
- ---
104
107
## EXTENSIONS TO ORIGINAL SPEC
105
108
106
- 1 . ### Register you own custom functions
109
+ ### Custom functions
107
110
108
- #### ` registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void `
111
+ #### ` registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void `
109
112
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.
111
114
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
+ );
118
129
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
+ ```
127
133
128
- search ({ foo: 60 ,bar: 10 }, ' divide(foo, bar)' );
129
- // OUTPUTS: 6
134
+ Optional arguments are supported by setting ` {..., optional: true} ` in argument signatures
130
135
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
+ );
132
145
133
- Optional arguments are supported by setting ` {..., optional: true}` in argument signatures
146
+ search ({ foo: 60 , bar: 10 }, ' divide(foo)' );
147
+ // OUTPUTS: 60
148
+ ` ` `
134
149
150
+ ### Root value access
135
151
136
- ` ` ` javascript
152
+ Use ` $ ` to access the document root.
137
153
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]' )
146
156
147
- search({ foo: 60, bar: 10 }, 'divide(foo)');
148
- // OUTPUTS: 60
157
+ // OUTPUTS:
158
+ // [ [ 1, 999 ], [ 2, 999 ], [ 3, 999 ] ]
159
+ ` ` `
149
160
150
- ` ` `
161
+ ### Number literals
151
162
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.
153
165
154
166
` ` ` javascript
167
+ search ([{" bar" : 1 }, {" bar" : 10 }]}, ' [?bar==10]' )
155
168
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
157
174
158
- // OUTPUTS:
159
- // [ [ 1, 999 ], [ 2, 999 ], [ 3, 999 ] ]
160
175
` ` `
176
+ search ({}, ' 16 + 26' ); // 42
161
177
178
+ // With the original specs we'd need to do
179
+ search ({}, ' `16` + `26`' );
180
+ ` ` `
162
181
163
182
## More Resources
164
183
165
- The example above only show a small amount of what
184
+ The example above only shows a small amount of what
166
185
a JMESPath expression can do. If you want to take a
167
186
tour 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).
174
188
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