tessl/npm-jsonpath
Query JavaScript objects with JSONPath expressions using a robust and safe JSONPath engine for Node.js.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Pending
The risk profile of this skill
querying.mddocs/
Data Querying
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 with script expressions, and recursive descent.
Capabilities
Query Function
Find elements in an object matching a JSONPath expression and return their values.
/**
* Find elements matching JSONPath expression
* @param {Object} obj - Target object to query (must be an object)
* @param {string} pathExpression - JSONPath expression string
* @param {number} [count] - Optional limit for number of results
* @returns {Array} Array of matching values, or empty array if none matched
*/
function query(obj, pathExpression, count);Usage Examples:
const jp = require('jsonpath');
const data = {
store: {
book: [
{ author: "Nigel Rees", title: "Sayings of the Century", price: 8.95 },
{ author: "Evelyn Waugh", title: "Sword of Honour", price: 12.99 },
{ author: "Herman Melville", title: "Moby Dick", price: 8.99 },
{ author: "J. R. R. Tolkien", title: "Lord of the Rings", price: 22.99 }
],
bicycle: { color: "red", price: 19.95 }
}
};
// Get all authors
const authors = jp.query(data, '$..author');
// Result: ['Nigel Rees', 'Evelyn Waugh', 'Herman Melville', 'J. R. R. Tolkien']
// Get all prices
const prices = jp.query(data, '$..price');
// Result: [8.95, 12.99, 8.99, 22.99, 19.95]
// Get books cheaper than 10
const cheapBooks = jp.query(data, '$..book[?(@.price<10)]');
// Result: [{ author: "Nigel Rees", title: "Sayings of the Century", price: 8.95 }, ...]
// Limit results with count parameter
const firstTwoAuthors = jp.query(data, '$..author', 2);
// Result: ['Nigel Rees', 'Evelyn Waugh']Paths Function
Find paths to elements matching a JSONPath expression. Returns arrays of keys representing the location of each match.
/**
* Find paths to elements matching JSONPath expression
* @param {Object} obj - Target object to query (must be an object)
* @param {string} pathExpression - JSONPath expression string
* @param {number} [count] - Optional limit for number of paths returned
* @returns {Array<Array>} Array of path arrays, where each path is array of keys
*/
function paths(obj, pathExpression, count);Usage Examples:
const jp = require('jsonpath');
// Get paths to all authors
const authorPaths = jp.paths(data, '$..author');
// Result: [
// ['$', 'store', 'book', 0, 'author'],
// ['$', 'store', 'book', 1, 'author'],
// ['$', 'store', 'book', 2, 'author'],
// ['$', 'store', 'book', 3, 'author']
// ]
// Get paths to all items in store
const storePaths = jp.paths(data, '$.store.*');
// Result: [
// ['$', 'store', 'book'],
// ['$', 'store', 'bicycle']
// ]
// Limit paths with count parameter
const firstThreePaths = jp.paths(data, '$..*', 3);
// Result: [['$', 'store'], ['$', 'store', 'book'], ['$', 'store', 'bicycle']]Nodes Function
Find elements and their corresponding paths matching a JSONPath expression. Returns objects containing both the path and value for each match.
/**
* Find elements and their paths matching JSONPath expression
* @param {Object} obj - Target object to query (must be an object)
* @param {string} pathExpression - JSONPath expression string
* @param {number} [count] - Optional limit for number of nodes returned
* @returns {Array<Object>} Array of node objects with {path: Array, value: any} structure
*/
function nodes(obj, pathExpression, count);Usage Examples:
const jp = require('jsonpath');
// Get nodes for all authors
const authorNodes = jp.nodes(data, '$..author');
// Result: [
// { path: ['$', 'store', 'book', 0, 'author'], value: 'Nigel Rees' },
// { path: ['$', 'store', 'book', 1, 'author'], value: 'Evelyn Waugh' },
// { path: ['$', 'store', 'book', 2, 'author'], value: 'Herman Melville' },
// { path: ['$', 'store', 'book', 3, 'author'], value: 'J. R. R. Tolkien' }
// ]
// Get nodes for all books
const bookNodes = jp.nodes(data, '$.store.book[*]');
// Result: [
// { path: ['$', 'store', 'book', 0], value: { author: "Nigel Rees", ... } },
// { path: ['$', 'store', 'book', 1], value: { author: "Evelyn Waugh", ... } },
// ...
// ]
// Filter and get first matching node only
const expensiveBookNode = jp.nodes(data, '$..book[?(@.price>20)]', 1);
// Result: [{ path: ['$', 'store', 'book', 3], value: { author: "J. R. R. Tolkien", ... } }]JSONPath Expression Syntax
The library supports comprehensive JSONPath syntax:
Basic Operators
$- Root object/element@- Current object/element (used in filters).property- Child member access..property- Recursive descendant search*- Wildcard for all properties/elements[n]- Array index access['property']- Bracketed property access
Advanced Operators
[start:end:step]- Array slicing (Python-style)[index1,index2,...]- Union operator for multiple indices[?(@.property)]- Filter expression (elements with property)[?(@.property==value)]- Filter expression (property equals value)[?(@.property<value)]- Filter expression (property less than value)[?(@.property>value && @.other<value)]- Complex filter expressions[(@.length-1)]- Script expressions for dynamic indices
Example Expressions
$.store.book[*].author- All book authors$..author- All authors anywhere in the structure$.store.*- All direct children of store$..book[2]- Third book (0-indexed)$..book[-1:]- Last book using slice$..book[0,1]- First two books using union$..book[:2]- First two books using slice$..book[?(@.price<10)]- Books cheaper than 10$..*- All elements in the structure
Error Handling
All query functions validate their inputs:
- Throws
AssertionErrorifobjis not an object - Throws
AssertionErrorifpathExpressionis not a string - Returns empty array
[]if no matches found - Returns empty array
[]ifcountis 0 - Throws
Errorfor invalid JSONPath syntax during parsing