Nimma is a high-performance JSONPath processor for Node.js. It allows you to efficiently query and manipulate JSON data using JSONPath expressions.
Query JSON Data
This feature allows you to query JSON data using JSONPath expressions. The code sample demonstrates how to extract the authors of all books in a store.
const Nimma = require('nimma');
const nimma = new Nimma();
const json = { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 } ] } };
const result = nimma.query(json, '$.store.book[*].author');
console.log(result); // Output: [ 'Nigel Rees', 'Evelyn Waugh' ]Modify JSON Data
This feature allows you to modify JSON data using JSONPath expressions. The code sample demonstrates how to increase the price of all books in a store by 10%.
const Nimma = require('nimma');
const nimma = new Nimma();
const json = { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 } ] } };
nimma.modify(json, '$.store.book[*].price', price => price * 1.1);
console.log(json); // Output: { store: { book: [ { category: 'reference', author: 'Nigel Rees', title: 'Sayings of the Century', price: 9.845 }, { category: 'fiction', author: 'Evelyn Waugh', title: 'Sword of Honour', price: 14.289 } ] } }jsonpath is a popular library for querying JSON data using JSONPath expressions. It provides similar functionality to nimma but may not be as performant. It is widely used and has a large community.
json-query is another library for querying JSON data, but it uses a different syntax compared to JSONPath. It is flexible and allows for complex queries, but it may not be as intuitive for users familiar with JSONPath.
jsonpath-plus is an extended version of the jsonpath library with additional features and improvements. It offers more flexibility and functionality compared to the original jsonpath library, making it a strong alternative to nimma.
JSON Path expressions? I mog nimma, aba naja. :trollface:
Skypack - recommended for Deno and browsers. Works with Node.js as well if you supply a custom module loader.
Package manager
yarn add nimma
or if npm is the package manager of your choice
npm install nimma --save
in) and regex (~=) operators, as taken from draft-ietf-jsonpath-base-01,import Nimma from 'https://cdn.skypack.dev/nimma';
const n = new Nimma([
'$.info',
'$.info.contact',
'$.info^',
'$.info^~',
'$.servers[*].url',
'$.servers[0:2]',
'$.servers[:5]',
"$.bar['children']",
"$.bar['0']",
"$.bar['children.bar']",
'$.channels[*][publish,subscribe][?(@.schemaFormat === void 0)].payload',
"$..[?( @property === 'get' || @property === 'put' || @property === 'post' )]",
"$..paths..[?( @property === 'get' || @property === 'put' || @property === 'post' )]",
`$.examples.*`,
'$[1:-5:-2]',
'$..foo..[?( @property >= 900 )]..foo',
]);
// you can perform the query...
n.query(document, {
['$.info']({ value, path }) {
//
},
// and so on for each specified path
});
// ... or write the generated code. It's advisable to write the code to further re-use.
await cache.writeFile('./nimma-code.mjs', n.sourceCode); // once
Here's how the sourceCode would look like for the above path expressions
import { Scope, isObject, inBounds } from 'nimma/runtime';
const tree = {
'$.info': function (scope, fn) {
const value = scope.sandbox.root;
if (isObject(value)) {
scope.fork(['info'])?.emit(fn, 0, false);
}
},
'$.info.contact': function (scope, fn) {
const value = scope.sandbox.root?.['info'];
if (isObject(value)) {
scope.fork(['info', 'contact'])?.emit(fn, 0, false);
}
},
'$.info^': function (scope, fn) {
const value = scope.sandbox.root;
if (isObject(value)) {
scope.fork(['info'])?.emit(fn, 1, false);
}
},
'$.info^~': function (scope, fn) {
const value = scope.sandbox.root;
if (isObject(value)) {
scope.fork(['info'])?.emit(fn, 1, true);
}
},
'$.servers[*].url': function (scope, fn) {
if (scope.depth !== 2) return;
if (scope.path[0] !== 'servers') return;
if (scope.path[2] !== 'url') return;
scope.emit(fn, 0, false);
},
'$.servers[0:2]': function (scope, fn) {
if (scope.depth !== 1) return;
if (scope.path[0] !== 'servers') return;
if (typeof scope.path[1] !== 'number' || scope.path[1] >= 2) return;
scope.emit(fn, 0, false);
},
'$.servers[:5]': function (scope, fn) {
if (scope.depth !== 1) return;
if (scope.path[0] !== 'servers') return;
if (typeof scope.path[1] !== 'number' || scope.path[1] >= 5) return;
scope.emit(fn, 0, false);
},
"$.bar['children']": function (scope, fn) {
const value = scope.sandbox.root?.['bar'];
if (isObject(value)) {
scope.fork(['bar', 'children'])?.emit(fn, 0, false);
}
},
"$.bar['0']": function (scope, fn) {
const value = scope.sandbox.root?.['bar'];
if (isObject(value)) {
scope.fork(['bar', '0'])?.emit(fn, 0, false);
}
},
"$.bar['children.bar']": function (scope, fn) {
const value = scope.sandbox.root?.['bar'];
if (isObject(value)) {
scope.fork(['bar', 'children.bar'])?.emit(fn, 0, false);
}
},
'$.channels[*][publish,subscribe][?(@.schemaFormat === void 0)].payload':
function (scope, fn) {
if (scope.depth !== 4) return;
if (scope.path[0] !== 'channels') return;
if (scope.path[2] !== 'publish' && scope.path[2] !== 'subscribe') return;
if (!(scope.sandbox.at(3).value.schemaFormat === void 0)) return;
if (scope.path[4] !== 'payload') return;
scope.emit(fn, 0, false);
},
"$..[?( @property === 'get' || @property === 'put' || @property === 'post' )]":
function (scope, fn) {
if (
!(
scope.sandbox.property === 'get' ||
scope.sandbox.property === 'put' ||
scope.sandbox.property === 'post'
)
)
return;
scope.emit(fn, 0, false);
},
"$..paths..[?( @property === 'get' || @property === 'put' || @property === 'post' )]":
function (scope, fn) {
if (scope.depth < 1) return;
let pos = 0;
if (((pos = scope.path.indexOf('paths', pos)), pos === -1)) return;
if (
scope.depth < pos + 1 ||
((pos = !(
scope.sandbox.property === 'get' ||
scope.sandbox.property === 'put' ||
scope.sandbox.property === 'post'
)
? -1
: scope.depth),
pos === -1)
)
return;
if (scope.depth !== pos) return;
scope.emit(fn, 0, false);
},
'$.examples.*': function (scope, fn) {
if (scope.depth !== 1) return;
if (scope.path[0] !== 'examples') return;
scope.emit(fn, 0, false);
},
'$[1:-5:-2]': function (scope, fn) {
if (scope.depth !== 0) return;
if (
typeof scope.path[0] !== 'number' ||
!inBounds(scope.sandbox.parentValue, scope.path[0], 1, -5, -2)
)
return;
scope.emit(fn, 0, false);
},
'$..foo..[?( @property >= 900 )]..foo': function (scope, fn) {
scope.bail(
'$..foo..[?( @property >= 900 )]..foo',
scope => scope.emit(fn, 0, false),
[
{
fn: scope => scope.property !== 'foo',
deep: true,
},
{
fn: scope => !(scope.sandbox.property >= 900),
deep: true,
},
{
fn: scope => scope.property !== 'foo',
deep: true,
},
],
);
},
};
export default function (input, callbacks) {
const scope = new Scope(input);
const _tree = scope.registerTree(tree);
const _callbacks = scope.proxyCallbacks(callbacks, {});
try {
_tree['$.info'](scope, _callbacks['$.info']);
_tree['$.info.contact'](scope, _callbacks['$.info.contact']);
_tree['$.info^'](scope, _callbacks['$.info^']);
_tree['$.info^~'](scope, _callbacks['$.info^~']);
_tree["$.bar['children']"](scope, _callbacks["$.bar['children']"]);
_tree["$.bar['0']"](scope, _callbacks["$.bar['0']"]);
_tree["$.bar['children.bar']"](scope, _callbacks["$.bar['children.bar']"]);
_tree['$..foo..[?( @property >= 900 )]..foo'](
scope,
_callbacks['$..foo..[?( @property >= 900 )]..foo'],
);
scope.traverse(() => {
_tree['$.servers[*].url'](scope, _callbacks['$.servers[*].url']);
_tree['$.servers[0:2]'](scope, _callbacks['$.servers[0:2]']);
_tree['$.servers[:5]'](scope, _callbacks['$.servers[:5]']);
_tree[
'$.channels[*][publish,subscribe][?(@.schemaFormat === void 0)].payload'
](
scope,
_callbacks[
'$.channels[*][publish,subscribe][?(@.schemaFormat === void 0)].payload'
],
);
_tree[
"$..[?( @property === 'get' || @property === 'put' || @property === 'post' )]"
](
scope,
_callbacks[
"$..[?( @property === 'get' || @property === 'put' || @property === 'post' )]"
],
);
_tree[
"$..paths..[?( @property === 'get' || @property === 'put' || @property === 'post' )]"
](
scope,
_callbacks[
"$..paths..[?( @property === 'get' || @property === 'put' || @property === 'post' )]"
],
);
_tree['$.examples.*'](scope, _callbacks['$.examples.*']);
_tree['$[1:-5:-2]'](scope, _callbacks['$[1:-5:-2]']);
});
} finally {
scope.destroy();
}
}
Since it's a valid ES Module, you can easily load it again and there's no need for new Nimma.
Nimma, although being yet-another-json-path query engine, it's considerably different from its JS counterparts. Nimma takes dozens/hundreds/thousands of JSONPath expressions and attempt to form a proper JS code, while packages like jsonpath-plus or jsonpath take a JSONPath expression and loop over its segments during the query. They are meant to be executed on a single expression, whereas Nimma, for the most time, doesn't really care whether you supply it with 10s or 100s of paths.
Futhermore, Nimma, despite remaining close to the spec, well, "spec", does make certain minor assumptions - the most notable being here that the order of query doesn't matter.
In order words, Nimma guarantees that all matching values will be returned, but doesn't assure any order.
This may be a deal breaker for some, but I haven't spotted such people in my life.
In reality, this would only matter if you used negative boundaries in Slice Expressions.
In addition to that, it also doesn't accumulate the results - this duties lies on the consumer.
These are tradeoffs that are likely to be negligible for the vast percentage of cases, yet they may play a role for some.
Unlike the aforementioned libraries, Nimma forbids any arbitrary code execution.
This is mostly thanks to a forked version of jsep Nimma is equipped with, as well as a set of additional enforcements.
Due to that, it's not possible to reference any object or function, even if it exists in the given environment.
For instance, $[?(Array.isArray(@)] will throw an exception, same as $[(?Object.prototype = {})], etc.
As a result, it's generally safer to execute these expressions, however there's no security guarantee here by any means,
and therefore it's still advisable to run Nimma in an isolated environment if JSONPath expressions cannot be trusted.
Since Nimma serves a different purpose, a use of other libraries is not ruled out.
It certainly doesn't aim to compete with any of them.
In fact, Nimma relies on jsonpath-plus under rare circumstances (mostly when "^" or "~" is not placed at the end of the expression).
Nimma consists of 3 major components. These are:
Parser takes any JSON Path expression and generates an AST that's consumed by the codegen in the next step.
Codegen is a two-step process:
FAQs
Scalable JSONPath engine.
The npm package nimma receives a total of 597,186 weekly downloads. As such, nimma popularity was classified as popular.
We found that nimma demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."