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
```