0
# JSONPath
1
2
JSONPath is a robust and safe JavaScript library for querying JavaScript objects using JSONPath expressions. It provides a comprehensive API for extracting data, finding paths, manipulating values, and parsing JSONPath expressions in both Node.js and browser environments.
3
4
## Package Information
5
6
- **Package Name**: jsonpath
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jsonpath`
10
11
## Core Imports
12
13
```javascript
14
const jp = require('jsonpath');
15
```
16
17
All functionality is available on the main import:
18
19
```javascript
20
const jp = require('jsonpath');
21
// Use as: jp.query(), jp.paths(), jp.nodes(), etc.
22
```
23
24
Browser (using bundled file):
25
26
```html
27
<script src="jsonpath.min.js"></script>
28
<script>
29
// Access via global jsonpath object
30
const jp = jsonpath;
31
</script>
32
```
33
34
## Basic Usage
35
36
```javascript
37
const jp = require('jsonpath');
38
39
const data = {
40
"store": {
41
"book": [
42
{
43
"category": "reference",
44
"author": "Nigel Rees",
45
"title": "Sayings of the Century",
46
"price": 8.95
47
},
48
{
49
"category": "fiction",
50
"author": "Evelyn Waugh",
51
"title": "Sword of Honour",
52
"price": 12.99
53
}
54
],
55
"bicycle": {
56
"color": "red",
57
"price": 19.95
58
}
59
}
60
};
61
62
// Query for all authors
63
const authors = jp.query(data, '$..author');
64
// Result: ['Nigel Rees', 'Evelyn Waugh']
65
66
// Get paths to all books
67
const bookPaths = jp.paths(data, '$.store.book[*]');
68
// Result: [['$', 'store', 'book', 0], ['$', 'store', 'book', 1]]
69
70
// Find nodes (path + value) for all prices
71
const priceNodes = jp.nodes(data, '$..price');
72
// Result: [
73
// { path: ['$', 'store', 'book', 0, 'price'], value: 8.95 },
74
// { path: ['$', 'store', 'book', 1, 'price'], value: 12.99 },
75
// { path: ['$', 'store', 'bicycle', 'price'], value: 19.95 }
76
// ]
77
```
78
79
## Architecture
80
81
JSONPath is built around several key components:
82
83
- **Query Engine**: Core querying functionality (`query`, `paths`, `nodes`) for finding data
84
- **Value Manipulation**: Functions for getting/setting values (`value`, `parent`, `apply`)
85
- **Path Processing**: Utilities for parsing and formatting JSONPath expressions (`parse`, `stringify`)
86
- **Expression Parser**: Formal BNF grammar-based parser for JSONPath expressions
87
- **Safe Evaluation**: Static evaluation of script expressions to prevent code injection
88
- **Universal Compatibility**: Works in Node.js and browsers with multiple module formats
89
90
## Capabilities
91
92
### Data Querying
93
94
Core querying functionality for finding elements, paths, and nodes in JavaScript objects using JSONPath expressions. Supports the full JSONPath syntax including wildcards, array slicing, filtering, and recursive descent.
95
96
```javascript { .api }
97
/**
98
* Find elements matching JSONPath expression
99
* @param {Object} obj - Target object to query
100
* @param {string} pathExpression - JSONPath expression string
101
* @param {number} [count] - Optional limit for number of results
102
* @returns {Array} Array of matching values
103
*/
104
function query(obj, pathExpression, count);
105
106
/**
107
* Find paths to elements matching JSONPath expression
108
* @param {Object} obj - Target object to query
109
* @param {string} pathExpression - JSONPath expression string
110
* @param {number} [count] - Optional limit for number of results
111
* @returns {Array<Array>} Array of path arrays (each path is array of keys)
112
*/
113
function paths(obj, pathExpression, count);
114
115
/**
116
* Find elements and their paths matching JSONPath expression
117
* @param {Object} obj - Target object to query
118
* @param {string} pathExpression - JSONPath expression string
119
* @param {number} [count] - Optional limit for number of results
120
* @returns {Array<Object>} Array of objects with {path: Array, value: any} structure
121
*/
122
function nodes(obj, pathExpression, count);
123
```
124
125
[Data Querying](./querying.md)
126
127
### Value Manipulation
128
129
Functions for getting, setting, and transforming values at specific JSONPath locations. Includes support for creating intermediate objects and applying transformations to multiple matching elements.
130
131
```javascript { .api }
132
/**
133
* Get or set value of first matching element
134
* @param {Object} obj - Target object
135
* @param {string|Array} pathExpression - JSONPath expression string or normalized path array
136
* @param {*} [newValue] - New value to set (optional, creates intermediate objects/arrays as needed)
137
* @returns {*} Current value (if getting) or new value (if setting)
138
*/
139
function value(obj, pathExpression, newValue);
140
141
/**
142
* Get parent of first matching element
143
* @param {Object} obj - Target object
144
* @param {string} pathExpression - JSONPath expression string
145
* @returns {*} Parent object of first match
146
*/
147
function parent(obj, pathExpression);
148
149
/**
150
* Apply function to all matching elements, modifying them in place
151
* @param {Object} obj - Target object
152
* @param {string} pathExpression - JSONPath expression string
153
* @param {Function} fn - Transformation function (value) => newValue
154
* @returns {Array<Object>} Array of modified node objects with {path: Array, value: any}
155
*/
156
function apply(obj, pathExpression, fn);
157
```
158
159
[Value Manipulation](./manipulation.md)
160
161
### Path Processing
162
163
Utilities for parsing JSONPath expressions into component objects and converting path arrays back to JSONPath strings. Essential for programmatic manipulation of JSONPath expressions.
164
165
```javascript { .api }
166
/**
167
* Parse JSONPath expression into component objects
168
* @param {string} pathExpression - JSONPath expression string
169
* @returns {Array<Object>} Array of path components with {expression: {type, value}, operation?, scope?}
170
*/
171
function parse(pathExpression);
172
173
/**
174
* Convert path array or parsed components to JSONPath expression string
175
* @param {Array|string} path - Flat array of keys, array of parsed path components, or path string
176
* @returns {string} JSONPath expression string
177
*/
178
function stringify(path);
179
```
180
181
[Path Processing](./path-processing.md)
182
183
## Types
184
185
```javascript { .api }
186
/**
187
* JSONPath node object containing path and value
188
* @typedef {Object} JSONPathNode
189
* @property {Array} path - Array of keys representing location in object
190
* @property {*} value - The matched value at this location
191
*/
192
193
/**
194
* JSONPath component object from parsing
195
* @typedef {Object} JSONPathComponent
196
* @property {Object} expression - Expression object with type and value
197
* @property {string} expression.type - Expression type ('root', 'identifier', 'numeric_literal', etc.)
198
* @property {*} expression.value - Expression value
199
* @property {string} [operation] - Operation type ('member', 'subscript')
200
* @property {string} [scope] - Scope type ('child', 'descendant')
201
*/
202
203
/**
204
* Main JSONPath class for creating custom instances
205
* Available as: require('jsonpath').JSONPath
206
*/
207
class JSONPath {
208
constructor();
209
query(obj, pathExpression, count);
210
paths(obj, pathExpression, count);
211
nodes(obj, pathExpression, count);
212
value(obj, pathExpression, newValue);
213
parent(obj, pathExpression);
214
apply(obj, pathExpression, fn);
215
parse(pathExpression);
216
stringify(path);
217
}
218
219
/**
220
* Internal Handlers class for path component resolution
221
* Available as: require('jsonpath').Handlers
222
*/
223
class Handlers {
224
constructor();
225
resolve(component);
226
register(key, handler);
227
}
228
229
/**
230
* Internal Parser class for JSONPath expression parsing
231
* Available as: require('jsonpath').Parser
232
*/
233
class Parser {
234
constructor();
235
parse(pathExpression);
236
}
237
238
/**
239
* Usage examples:
240
* const jp = require('jsonpath');
241
* const { JSONPath, Handlers, Parser } = jp;
242
* const customInstance = new JSONPath();
243
*/
244
```