-
-
Notifications
You must be signed in to change notification settings - Fork 200
Expand file tree
/
Copy pathindex.html
More file actions
443 lines (433 loc) · 43.8 KB
/
index.html
File metadata and controls
443 lines (433 loc) · 43.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
<!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>jsonpath-plus</title><meta name="description" content="Documentation for jsonpath-plus"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script><script async src="assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">jsonpath-plus</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>jsonpath-plus</h1></div><div class="tsd-panel tsd-typography"><p><a href="https://www.npmjs.com/package/jsonpath-plus"><img src="https://img.shields.io/npm/v/jsonpath-plus.svg" alt="npm"></a></p>
<p><a href="badges/tests-badge.svg"><img src="https://raw.githubusercontent.com/s3u/JSONPath/master/badges/tests-badge.svg?sanitize=true" alt="testing badge"></a>
<a href="badges/coverage-badge.svg"><img src="https://raw.githubusercontent.com/s3u/JSONPath/master/badges/coverage-badge.svg?sanitize=true" alt="coverage badge"></a></p>
<p><a href="https://snyk.io/test/github/s3u/JSONPath"><img src="https://snyk.io/test/github/s3u/JSONPath/badge.svg" alt="Known Vulnerabilities"></a></p>
<!--[](LICENSE-MIT.txt)-->
<p><a href="badges/licenses-badge.svg"><img src="https://raw.githubusercontent.com/s3u/JSONPath/master/badges/licenses-badge.svg?sanitize=true" alt="Licenses badge"></a></p>
<p><a href="https://github.com/JSONPath-Plus/JSONPath/actions/workflows/node.js.yml"><img src="https://github.com/JSONPath-Plus/JSONPath/actions/workflows/node.js.yml/badge.svg" alt="Node.js CI status"></a></p>
<p><small>(see also <a href="https://raw.githubusercontent.com/s3u/JSONPath/master/badges/licenses-badge-dev.svg?sanitize=true">licenses for dev. deps.</a>)</small></p>
<a id="jsonpath-plus" class="tsd-anchor"></a><h1 class="tsd-anchor-link">JSONPath Plus<a href="#jsonpath-plus" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p>Analyse, transform, and selectively extract data from JSON
documents (and JavaScript objects).</p>
<p><code>jsonpath-plus</code> expands on the original specification to add some
additional operators and makes explicit some behaviors the original
did not spell out.</p>
<p>Try the <a href="https://jsonpath-plus.github.io/JSONPath/demo/">browser demo</a> or
<a href="https://npm.runkit.com/jsonpath-plus">Runkit (Node)</a>.</p>
<p><em><strong>Please note: This project is not currently being actively maintained. We
may accept well-documented PRs or some simple updates, but are not looking
to make fixes or add new features ourselves.</strong></em></p>
<a id="features" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Features<a href="#features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
<li><strong>Compliant</strong> with the original jsonpath spec</li>
<li>Convenient <strong>additions or elaborations</strong> not provided in the original spec:
<ul>
<li><code>^</code> for grabbing the <strong>parent</strong> of a matching item</li>
<li><code>~</code> for grabbing <strong>property names</strong> of matching items (as array)</li>
<li><strong>Type selectors</strong> for obtaining:
<ul>
<li>Basic JSON types: <code>@null()</code>, <code>@boolean()</code>, <code>@number()</code>, <code>@string()</code>, <code>@array()</code>, <code>@object()</code></li>
<li><code>@integer()</code></li>
<li>The compound type <code>@scalar()</code> (which also accepts <code>undefined</code> and
non-finite numbers when querying JavaScript objects as well as all of the basic non-object/non-function types)</li>
<li><code>@other()</code> usable in conjunction with a user-defined <code>otherTypeCallback</code></li>
<li>Non-JSON types that can nevertheless be used when querying
non-JSON JavaScript objects (<code>@undefined()</code>, <code>@function()</code>, <code>@nonFinite()</code>)</li>
</ul>
</li>
<li><code>@path</code>/<code>@parent</code>/<code>@property</code>/<code>@parentProperty</code>/<code>@root</code> <strong>shorthand selectors</strong> within filters</li>
<li><strong>Escaping</strong>
<ul>
<li><code>`</code> for escaping remaining sequence</li>
<li><code>@['...']</code>/<code>?@['...']</code> syntax for escaping special characters within
property names in filters</li>
</ul>
</li>
<li>Documents <code>$..</code> (<strong>getting all parent components</strong>)</li>
</ul>
</li>
<li><strong>ESM</strong> and <strong>UMD</strong> export formats</li>
<li>In addition to queried values, <strong>can return various meta-information</strong>
including paths or pointers to the value, as well as the parent
object and parent property name (to allow for modification).</li>
<li><strong>Utilities for converting</strong> between paths, arrays, and pointers</li>
<li>Option to <strong>prevent evaluations</strong> permitted in the original spec or supply
a <strong>sandbox</strong> for evaluated values.</li>
<li>Option for <strong>callback to handle results</strong> as they are obtained.</li>
</ul>
<a id="benchmarking" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Benchmarking<a href="#benchmarking" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><code>jsonpath-plus</code> is consistently performant with both large and small datasets compared to other json querying libraries per <a href="https://github.com/andykais/json-querying-performance-testing">json-querying-performance-testing</a>. You can verify these findings by <a href="https://github.com/andykais/json-querying-performance-testing#how-to-run">running the project yourself</a> and adding more perf cases.</p>
<a id="install" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Install<a href="#install" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">jsonpath-plus</span>
</code><button type="button">Copy</button></pre>
<a id="setup" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Setup<a href="#setup" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="nodejs" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Node.js<a href="#nodejs" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="js"><span class="hl-3">const</span><span class="hl-1"> {</span><span class="hl-4">JSONPath</span><span class="hl-1">} = </span><span class="hl-0">require</span><span class="hl-1">(</span><span class="hl-2">'jsonpath-plus'</span><span class="hl-1">);</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">result</span><span class="hl-1"> = </span><span class="hl-0">JSONPath</span><span class="hl-1">({</span><span class="hl-5">path:</span><span class="hl-1"> </span><span class="hl-2">'...'</span><span class="hl-1">, </span><span class="hl-5">json</span><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<a id="browser" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Browser<a href="#browser" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>For browser usage you can directly include <code>dist/index-browser-umd.cjs</code>; no
Browserify magic is necessary:</p>
<pre><code class="html"><span class="hl-6"><</span><span class="hl-7">script</span><span class="hl-8"> </span><span class="hl-9">src</span><span class="hl-8">=</span><span class="hl-10">"node_modules/jsonpath-plus/dist/index-browser-umd.cjs"</span><span class="hl-6">></</span><span class="hl-7">script</span><span class="hl-6">></span><br/><br/><span class="hl-6"><</span><span class="hl-7">script</span><span class="hl-6">></span><br/><br/><span class="hl-3">const</span><span class="hl-8"> </span><span class="hl-4">result</span><span class="hl-8"> </span><span class="hl-1">=</span><span class="hl-8"> </span><span class="hl-5">JSONPath</span><span class="hl-8">.</span><span class="hl-0">JSONPath</span><span class="hl-8">({</span><span class="hl-5">path:</span><span class="hl-8"> </span><span class="hl-2">'...'</span><span class="hl-8">, </span><span class="hl-5">json:</span><span class="hl-8"> {}});</span><br/><br/><span class="hl-6"></</span><span class="hl-7">script</span><span class="hl-6">></span>
</code><button type="button">Copy</button></pre>
<a id="esm-modern-browsers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">ESM (Modern browsers)<a href="#esm-modern-browsers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>You may also use ES6 Module imports (for modern browsers):</p>
<pre><code class="html"><span class="hl-6"><</span><span class="hl-7">script</span><span class="hl-8"> </span><span class="hl-9">type</span><span class="hl-8">=</span><span class="hl-10">"module"</span><span class="hl-6">></span><br/><br/><span class="hl-11">import</span><span class="hl-8"> {</span><br/><span class="hl-8"> </span><span class="hl-5">JSONPath</span><br/><span class="hl-8">} </span><span class="hl-11">from</span><span class="hl-8"> </span><span class="hl-2">'./node_modules/jsonpath-plus/dist/index-browser-esm.js'</span><span class="hl-8">;</span><br/><br/><span class="hl-3">const</span><span class="hl-8"> </span><span class="hl-4">result</span><span class="hl-8"> </span><span class="hl-1">=</span><span class="hl-8"> </span><span class="hl-0">JSONPath</span><span class="hl-8">({</span><span class="hl-5">path:</span><span class="hl-8"> </span><span class="hl-2">'...'</span><span class="hl-8">, </span><span class="hl-5">json:</span><span class="hl-8"> {}});</span><br/><br/><span class="hl-6"></</span><span class="hl-7">script</span><span class="hl-6">></span>
</code><button type="button">Copy</button></pre>
<a id="esm-bundlers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">ESM (Bundlers)<a href="#esm-bundlers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Or if you are bundling your JavaScript (e.g., with Rollup), just use,
noting that <a href="https://github.com/rollup/plugins/tree/master/packages/node-resolve#mainfields"><code>mainFields</code></a>
should include <code>browser</code> for browser builds (for Node, the default, which
checks <code>module</code>, should be fine):</p>
<pre><code class="js"><span class="hl-11">import</span><span class="hl-1"> {</span><span class="hl-5">JSONPath</span><span class="hl-1">} </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-2">'jsonpath-plus'</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">result</span><span class="hl-1"> = </span><span class="hl-0">JSONPath</span><span class="hl-1">({</span><span class="hl-5">path:</span><span class="hl-1"> </span><span class="hl-2">'...'</span><span class="hl-1">, </span><span class="hl-5">json</span><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<a id="usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>The full signature available is:</p>
<pre><code><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">result</span><span class="hl-1"> = </span><span class="hl-0">JSONPath</span><span class="hl-1">([</span><span class="hl-5">options</span><span class="hl-1">,] </span><span class="hl-5">path</span><span class="hl-1">, </span><span class="hl-5">json</span><span class="hl-1">, </span><span class="hl-5">callback</span><span class="hl-1">, </span><span class="hl-5">otherTypeCallback</span><span class="hl-1">);</span>
</code><button>Copy</button></pre>
<p>The arguments <code>path</code>, <code>json</code>, <code>callback</code>, and <code>otherTypeCallback</code>
can alternatively be expressed (along with any other of the
available properties) on <code>options</code>.</p>
<p>Note that <code>result</code> will contain all items found (optionally
wrapped into an array) whereas <code>callback</code> can be used if you
wish to perform some operation as each item is discovered, with
the callback function being executed 0 to N times depending
on the number of independent items to be found in the result.
See the docs below for more on <code>JSONPath</code>'s available arguments.</p>
<p>See also the <a href="https://jsonpath-plus.github.io/JSONPath/docs/ts/">API docs</a>.</p>
<a id="properties" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Properties<a href="#properties" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The properties that can be supplied on the options object or
evaluate method (as the first argument) include:</p>
<ul>
<li><em><strong>path</strong></em> (<strong>required</strong>) - The JSONPath expression as a (normalized
or unnormalized) string or array</li>
<li><em><strong>json</strong></em> (<strong>required</strong>) - The JSON object to evaluate (whether of
null, boolean, number, string, object, or array type).</li>
<li><em><strong>autostart</strong></em> (<strong>default: true</strong>) - If this is supplied as <code>false</code>,
one may call the <code>evaluate</code> method manually.</li>
<li><em><strong>flatten</strong></em> (<strong>default: false</strong>) - Whether the returned array of results
will be flattened to a single dimension array.</li>
<li><em><strong>resultType</strong></em> (<strong>default: "value"</strong>) - Can be case-insensitive form of
"value", "path", "pointer", "parent", or "parentProperty" to determine
respectively whether to return results as the values of the found items,
as their absolute paths, as <a href="https://tools.ietf.org/html/rfc6901">JSON Pointers</a>
to the absolute paths, as their parent objects, or as their parent's
property name. If set to "all", all of these types will be returned on
an object with the type as key name.</li>
<li><em><strong>sandbox</strong></em> (<strong>default: {}</strong>) - Key-value map of variables to be
available to code evaluations such as filtering expressions. (Note
that the current path and value will also be available to those
expressions; see the Syntax section for details.)</li>
<li><em><strong>wrap</strong></em> (<strong>default: true</strong>) - Whether or not to wrap the results
in an array. If <code>wrap</code> is set to <code>false</code>, and no results are found,
<code>undefined</code> will be returned (as opposed to an empty array when
<code>wrap</code> is set to true). If <code>wrap</code> is set to <code>false</code> and a single
non-array result is found, that result will be the only item returned
(not within an array). An array will still be returned if multiple
results are found, however. To avoid ambiguities (in the case where
it is necessary to distinguish between a result which is a failure
and one which is an empty array), it is recommended to switch the
default to <code>false</code>.</li>
<li><em><strong>eval</strong></em> (<strong>default: "safe"</strong>) - Script evaluation method.
<code>safe</code>: In browser, it will use a minimal scripting engine which doesn't
use <code>eval</code> or <code>Function</code> and satisfies Content Security Policy. In NodeJS,
it has no effect and is equivalent to native as scripting is safe there.
<code>native</code>: uses the native scripting capabilities. i.e. unsafe <code>eval</code> or
<code>Function</code> in browser and <code>vm.Script</code> in nodejs. <code>false</code>: Disable JavaScript
evaluation expressions and throw exceptions when these expressions are attempted.
<code>callback [ (code, context) => value]</code>: A custom implementation which is called
with <code>code</code> and <code>context</code> as arguments to return the evaluated value.
<code>class</code>: A class which is created with <code>code</code> as constructor argument and code
is evaluated by calling <code>runInNewContext</code> with <code>context</code>.
``</li>
<li><em><strong>ignoreEvalErrors</strong></em> (<strong>default: false</strong>) - Ignore errors encountered during
script evaluation.</li>
<li><em><strong>parent</strong></em> (<strong>default: null</strong>) - In the event that a query could be
made to return the root node, this allows the parent of that root node
to be returned within results.</li>
<li><em><strong>parentProperty</strong></em> (<strong>default: null</strong>) - In the event that a query
could be made to return the root node, this allows the <code>parentProperty</code>
of that root node to be returned within results.</li>
<li><em><strong>callback</strong></em> (<strong>default: (none)</strong>) - If supplied, a callback will be
called immediately upon retrieval of an end point value. The three arguments
supplied will be the value of the payload (according to <code>resultType</code>),
the type of the payload (whether it is a normal "value" or a "property"
name), and a full payload object (with all <code>resultType</code>s).</li>
<li><em><strong>otherTypeCallback</strong></em> (<strong>default: <A function that throws an error</strong>
<strong>when @other() is encountered></strong>) - In the current absence of JSON
Schema support, one can determine types beyond the built-in types by
adding the operator <code>@other()</code> at the end of one's query. If such a
path is encountered, the <code>otherTypeCallback</code> will be invoked with the
value of the item, its path, its parent, and its parent's property name,
and it should return a boolean indicating whether the supplied value
belongs to the "other" type or not (or it may handle transformations and
return false).</li>
</ul>
<a id="instance-methods" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Instance methods<a href="#instance-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
<li><em><strong>evaluate(path, json, callback, otherTypeCallback)</strong></em> OR
<em><strong>evaluate({path: <path>, json: <json object>, callback:</strong></em>
<em><strong><callback function>, otherTypeCallback:</strong></em>
<em><strong><otherTypeCallback function>})</strong></em> - This method is only
necessary if the <code>autostart</code> property is set to <code>false</code>. It
can be used for repeated evaluations using the same configuration.
Besides the listed properties, the latter method pattern can
accept any of the other allowed instance properties (except
for <code>autostart</code> which would have no relevance here).</li>
</ul>
<a id="class-properties-and-methods" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Class properties and methods<a href="#class-properties-and-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
<li><em><strong>JSONPath.cache</strong></em> - Exposes the cache object for those who wish
to preserve and reuse it for optimization purposes.</li>
<li><em><strong>JSONPath.toPathArray(pathAsString)</strong></em> - Accepts a normalized or
unnormalized path as string and converts to an array: for
example, <code>['$', 'aProperty', 'anotherProperty']</code>.</li>
<li><em><strong>JSONPath.toPathString(pathAsArray)</strong></em> - Accepts a path array and
converts to a normalized path string. The string will be in a form
like: <code>$['aProperty']['anotherProperty][0]</code>. The JSONPath terminal
constructions <code>~</code> and <code>^</code> and type operators like <code>@string()</code> are
silently stripped.</li>
<li><em><strong>JSONPath.toPointer(pathAsArray)</strong></em> - Accepts a path array and
converts to a <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a>.
The string will be in a form like: <code>/aProperty/anotherProperty/0</code>
(with any <code>~</code> and <code>/</code> internal characters escaped as per the JSON
Pointer spec). The JSONPath terminal constructions <code>~</code> and <code>^</code> and
type operators like <code>@string()</code> are silently stripped.</li>
</ul>
<a id="syntax-through-examples" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Syntax through examples<a href="#syntax-through-examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Given the following JSON, taken from <a href="http://goessner.net/articles/JsonPath/">http://goessner.net/articles/JsonPath/</a>:</p>
<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-12">"store"</span><span class="hl-1">: {</span><br/><span class="hl-1"> </span><span class="hl-12">"book"</span><span class="hl-1">: [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-12">"category"</span><span class="hl-1">: </span><span class="hl-2">"reference"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"author"</span><span class="hl-1">: </span><span class="hl-2">"Nigel Rees"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"title"</span><span class="hl-1">: </span><span class="hl-2">"Sayings of the Century"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"price"</span><span class="hl-1">: </span><span class="hl-13">8.95</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-12">"category"</span><span class="hl-1">: </span><span class="hl-2">"fiction"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"author"</span><span class="hl-1">: </span><span class="hl-2">"Evelyn Waugh"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"title"</span><span class="hl-1">: </span><span class="hl-2">"Sword of Honour"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"price"</span><span class="hl-1">: </span><span class="hl-13">12.99</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-12">"category"</span><span class="hl-1">: </span><span class="hl-2">"fiction"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"author"</span><span class="hl-1">: </span><span class="hl-2">"Herman Melville"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"title"</span><span class="hl-1">: </span><span class="hl-2">"Moby Dick"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"isbn"</span><span class="hl-1">: </span><span class="hl-2">"0-553-21311-3"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"price"</span><span class="hl-1">: </span><span class="hl-13">8.99</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-12">"category"</span><span class="hl-1">: </span><span class="hl-2">"fiction"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"author"</span><span class="hl-1">: </span><span class="hl-2">"J. R. R. Tolkien"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"title"</span><span class="hl-1">: </span><span class="hl-2">"The Lord of the Rings"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"isbn"</span><span class="hl-1">: </span><span class="hl-2">"0-395-19395-8"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"price"</span><span class="hl-1">: </span><span class="hl-13">22.99</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> </span><span class="hl-12">"bicycle"</span><span class="hl-1">: {</span><br/><span class="hl-1"> </span><span class="hl-12">"color"</span><span class="hl-1">: </span><span class="hl-2">"red"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-12">"price"</span><span class="hl-1">: </span><span class="hl-13">19.95</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span><br/><span class="hl-1">}</span>
</code><button type="button">Copy</button></pre>
<p>and the following XML representation:</p>
<pre><code class="xml"><store>
<book>
<category>reference</category>
<author>Nigel Rees</author>
<title>Sayings of the Century</title>
<price>8.95</price>
</book>
<book>
<category>fiction</category>
<author>Evelyn Waugh</author>
<title>Sword of Honour</title>
<price>12.99</price>
</book>
<book>
<category>fiction</category>
<author>Herman Melville</author>
<title>Moby Dick</title>
<isbn>0-553-21311-3</isbn>
<price>8.99</price>
</book>
<book>
<category>fiction</category>
<author>J. R. R. Tolkien</author>
<title>The Lord of the Rings</title>
<isbn>0-395-19395-8</isbn>
<price>22.99</price>
</book>
<bicycle>
<color>red</color>
<price>19.95</price>
</bicycle>
</store>
</code><button type="button">Copy</button></pre>
<p>Please note that the XPath examples below do not distinguish between
retrieving elements and their text content (except where useful for
comparisons or to prevent ambiguity). Note: to test the XPath examples
(including 2.0 ones), <a href="http://videlibri.sourceforge.net/cgi-bin/xidelcgi">this demo</a>
may be helpful (set to <code>xml</code> or <code>xml-strict</code>).</p>
<table>
<thead>
<tr>
<th>XPath</th>
<th>JSONPath</th>
<th>Result</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/store/book/author</code></td>
<td><code>$.store.book[*].author</code></td>
<td>The authors of all books in the store</td>
<td>Can also be represented without the <code>$.</code> as <code>store.book[*].author</code> (though this is not present in the original spec); note that some character literals (<code>$</code> and <code>@</code>) require escaping, however</td>
</tr>
<tr>
<td><code>//author</code></td>
<td><code>$..author</code></td>
<td>All authors</td>
<td></td>
</tr>
<tr>
<td><code>/store/*</code></td>
<td><code>$.store.*</code></td>
<td>All things in store, which are its books (a book array) and a red bicycle (a bicycle object).</td>
<td></td>
</tr>
<tr>
<td><code>/store//price</code></td>
<td><code>$.store..price</code></td>
<td>The price of everything in the store.</td>
<td></td>
</tr>
<tr>
<td><code>//book[3]</code></td>
<td><code>$..book[2]</code></td>
<td>The third book (book object)</td>
<td></td>
</tr>
<tr>
<td><code>//book[last()]</code></td>
<td><code>$..book[(@.length-1)]</code> <br> <code>$..book[-1:]</code></td>
<td>The last book in order.</td>
<td>To access a property with a special character, utilize <code>[(@['...'])]</code> for the filter (this particular feature is not present in the original spec)</td>
</tr>
<tr>
<td><code>//book[position()<3]</code></td>
<td><code>$..book[0,1]</code> <br> <code>$..book[:2]</code></td>
<td>The first two books</td>
<td></td>
</tr>
<tr>
<td><code>//book/*[self::category|self::author]</code> or <code>//book/(category,author)</code> in XPath 2.0</td>
<td><code>$..book[0][category,author]</code></td>
<td>The categories and authors of all books</td>
<td></td>
</tr>
<tr>
<td><code>//book[isbn]</code></td>
<td><code>$..book[?(@.isbn)]</code></td>
<td>Filter all books with an ISBN number</td>
<td>To access a property with a special character, utilize <code>[?@['...']]</code> for the filter (this particular feature is not present in the original spec)</td>
</tr>
<tr>
<td><code>//book[price<10]</code></td>
<td><code>$..book[?(@.price<10)]</code></td>
<td>Filter all books cheaper than 10</td>
<td></td>
</tr>
<tr>
<td><code>//*[name() = 'price' and . != 8.95]</code></td>
<td><code>$..*[?(@property === 'price' && @ !== 8.95)]</code></td>
<td>Obtain all property values of objects whose property is price and which does not equal 8.95</td>
<td>With the bare <code>@</code> allowing filtering objects by property value (not necessarily within arrays), you can add <code>^</code> after the expression to get at the object possessing the filtered properties</td>
</tr>
<tr>
<td><code>/</code></td>
<td><code>$</code></td>
<td>The root of the JSON object (i.e., the whole object itself)</td>
<td>To get a literal <code>$</code> (by itself or anywhere in the path), you must use the backtick escape</td>
</tr>
<tr>
<td><code>//*/*|//*/*/text()</code></td>
<td><code>$..*</code></td>
<td>All Elements (and text) beneath root in an XML document. All members of a JSON structure beneath the root.</td>
<td></td>
</tr>
<tr>
<td><code>//*</code></td>
<td><code>$..</code></td>
<td>All Elements in an XML document. All parent components of a JSON structure including root.</td>
<td>This behavior was not directly specified in the original spec</td>
</tr>
<tr>
<td><code>//*[price>19]/..</code></td>
<td><code>$..[?(@.price>19)]^</code></td>
<td>Parent of those specific items with a price greater than 19 (i.e., the store value as the parent of the bicycle and the book array as parent of an individual book)</td>
<td>Parent (caret) not present in the original spec</td>
</tr>
<tr>
<td><code>/store/*/name()</code> (in XPath 2.0)</td>
<td><code>$.store.*~</code></td>
<td>The property names of the store sub-object ("book" and "bicycle"). Useful with wildcard properties.</td>
<td>Property name (tilde) is not present in the original spec</td>
</tr>
<tr>
<td><code>/store/book[not(. is /store/book[1])]</code> (in XPath 2.0)</td>
<td><code>$.store.book[?(@path !== "$['store']['book'][0]")]</code></td>
<td>All books besides that at the path pointing to the first</td>
<td><code>@path</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book[parent::*/bicycle/color = "red"]/category</code></td>
<td><code>$..book[?(@parent.bicycle && @parent.bicycle.color === "red")].category</code></td>
<td>Grabs all categories of books where the parent object of the book has a bicycle child whose color is red (i.e., all the books)</td>
<td><code>@parent</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book/*[name() != 'category']</code></td>
<td><code>$..book.*[?(@property !== "category")]</code></td>
<td>Grabs all children of "book" except for "category" ones</td>
<td><code>@property</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book[position() != 1]</code></td>
<td><code>$..book[?(@property !== 0)]</code></td>
<td>Grabs all books whose property (which, being that we are reaching inside an array, is the numeric index) is not 0</td>
<td><code>@property</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>/store/*/*[name(parent::*) != 'book']</code></td>
<td><code>$.store.*[?(@parentProperty !== "book")]</code></td>
<td>Grabs the grandchildren of store whose parent property is not book (i.e., bicycle's children, "color" and "price")</td>
<td><code>@parentProperty</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book[count(preceding-sibling::*) != 0]/*/text()</code></td>
<td><code>$..book.*[?(@parentProperty !== 0)]</code></td>
<td>Get the property values of all book instances whereby the parent property of these values (i.e., the array index holding the book item parent object) is not 0</td>
<td><code>@parentProperty</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book[price = /store/book[3]/price]</code></td>
<td><code>$..book[?(@.price === @root.store.book[2].price)]</code></td>
<td>Filter all books whose price equals the price of the third book</td>
<td><code>@root</code> is not present in the original spec</td>
</tr>
<tr>
<td><code>//book/../*[. instance of element(*, xs:decimal)]</code> (in XPath 2.0)</td>
<td><code>$..book..*@number()</code></td>
<td>Get the numeric values within the book array</td>
<td><code>@number()</code>, the other basic types (<code>@boolean()</code>, <code>@string()</code>), other low-level derived types (<code>@null()</code>, <code>@object()</code>, <code>@array()</code>), the JSONSchema-added type, <code>@integer()</code>, the compound type <code>@scalar()</code> (which also accepts <code>undefined</code> and non-finite numbers for JavaScript objects as well as all of the basic non-object/non-function types), the type, <code>@other()</code>, to be used in conjunction with a user-defined callback (see <code>otherTypeCallback</code>) and the following non-JSON types that can nevertheless be used with JSONPath when querying non-JSON JavaScript objects (<code>@undefined()</code>, <code>@function()</code>, <code>@nonFinite()</code>) are not present in the original spec</td>
</tr>
<tr>
<td><code>//book/*[name() = 'category' and matches(., 'tion$')]</code> (XPath 2.0)</td>
<td><code>$..book.*[?(@property === "category" && @.match(/TION$/i))]</code></td>
<td>All categories of books which match the regex (end in 'TION' case insensitive)</td>
<td><code>@property</code> is not present in the original spec.</td>
</tr>
<tr>
<td><code>//book/*[matches(name(), 'bn$')]/parent::*</code> (XPath 2.0)</td>
<td><code>$..book.*[?(@property.match(/bn$/i))]^</code></td>
<td>All books which have a property matching the regex (end in 'TION' case insensitive)</td>
<td><code>@property</code> is not present in the original spec. Note: Uses the parent selector <code>^</code> at the end of the expression to return to the parent object; without the parent selector, it matches the two <code>isbn</code> key values.</td>
</tr>
<tr>
<td></td>
<td><code>`</code> (e.g., <code> `$</code> to match a property literally named <code>$</code>)</td>
<td>Escapes the entire sequence following (to be treated as a literal)</td>
<td><code>`</code> is not present in the original spec; to get a literal backtick, use an additional backtick to escape</td>
</tr>
</tbody>
</table>
<p>Any additional variables supplied as properties on the optional "sandbox"
object option are also available to (parenthetical-based)
evaluations.</p>
<a id="potential-sources-of-confusion-for-xpath-users" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Potential sources of confusion for XPath users<a href="#potential-sources-of-confusion-for-xpath-users" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ol>
<li>In JSONPath, a filter expression, in addition to its <code>@</code> being a
reference to its children, actually selects the immediate children
as well, whereas in XPath, filter conditions do not select the children
but delimit which of its parent nodes will be obtained in the result.</li>
<li>In JSONPath, array indexes are, as in JavaScript, 0-based (they begin
from 0), whereas in XPath, they are 1-based.</li>
<li>In JSONPath, equality tests utilize (as per JavaScript) multiple equal signs
whereas in XPath, they use a single equal sign.</li>
</ol>
<a id="command-line-interface" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Command line interface<a href="#command-line-interface" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>A basic command line interface (CLI) is provided. Access it using <code>npx jsonpath-plus <json-file> <jsonpath-query></code>.</p>
<a id="ideas" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Ideas<a href="#ideas" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ol>
<li>Support OR outside of filters (as in XPath <code>|</code>) and grouping.</li>
<li>Create syntax to work like XPath filters in not selecting children?</li>
<li>Allow option for parentNode equivalent (maintaining entire chain of
parent-and-parentProperty objects up to root)</li>
</ol>
<a id="development" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Development<a href="#development" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Running the tests on Node:</p>
<pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">test</span>
</code><button type="button">Copy</button></pre>
<p>For in-browser tests:</p>
<ul>
<li>Serve the js/html files:</li>
</ul>
<pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">browser-test</span>
</code><button type="button">Copy</button></pre>
<ul>
<li>Visit <a href="http://localhost:8082/test/">http://localhost:8082/test/</a>.</li>
</ul>
<a id="security" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Security<a href="#security" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Please see <a href="media/SECURITY.md">SECURITY.md</a> for important security considerations and instructions on how to report vulnerabilities.</p>
<a id="license" class="tsd-anchor"></a><h2 class="tsd-anchor-link">License<a href="#license" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><a href="https://opensource.org/license/mit/">MIT License</a>.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#jsonpath-plus"><span>JSONPath <wbr/>Plus</span></a><ul><li><a href="#features"><span>Features</span></a></li><li><a href="#benchmarking"><span>Benchmarking</span></a></li><li><a href="#install"><span>Install</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><ul><li><a href="#nodejs"><span>Node.js</span></a></li><li><a href="#browser"><span>Browser</span></a></li><li><a href="#esm-modern-browsers"><span>ESM (<wbr/>Modern browsers)</span></a></li><li><a href="#esm-bundlers"><span>ESM (<wbr/>Bundlers)</span></a></li></ul></li><li><a href="#usage"><span>Usage</span></a></li><li><ul><li><a href="#properties"><span>Properties</span></a></li><li><a href="#instance-methods"><span>Instance methods</span></a></li><li><a href="#class-properties-and-methods"><span>Class properties and methods</span></a></li></ul></li><li><a href="#syntax-through-examples"><span>Syntax through examples</span></a></li><li><a href="#potential-sources-of-confusion-for-xpath-users"><span>Potential sources of confusion for XPath users</span></a></li><li><a href="#command-line-interface"><span>Command line interface</span></a></li><li><a href="#ideas"><span>Ideas</span></a></li><li><a href="#development"><span>Development</span></a></li><li><a href="#security"><span>Security</span></a></li><li><a href="#license"><span>License</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">jsonpath-plus</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>