jora

library1.0.0-beta.15jsnpmunverified

Jora is a JavaScript object query engine and language for processing and querying JSON-like data structures efficiently. While currently in a beta development phase (v1.0.0-beta.15), it is considered stable, though its syntax might undergo changes in future releases. The project maintains a relatively frequent release cadence for beta versions, actively introducing new features, improvements, and addressing issues. Jora distinguishes itself with a compact, JavaScript-like syntax for common data manipulation tasks, tolerant query execution that simply returns nothing for unreachable paths instead of throwing errors, and automatic aggregation and deduplication of values. It also includes advanced features like a stat collecting mode for powering suggestions in editors and an extensible Domain Specific Language (DSL) via custom methods and assertions, making it highly adaptable for complex data transformations. It is a core component within the Discovery.js ecosystem, used for data visualization and building interactive reports.

data serialization

npm install jora

github ↗package ↗

INSTALL

IMPORT

SIG · JORA

jora

datajavascriptv1.0.0-beta.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jora

✓ import jora from 'jora'

✗ const jora = require('jora')

Jora is primarily consumed as a default export, providing the main query function.

setup

✓ import { setup } from 'jora'

✗ import jora, { setup } from 'jora'; jora.setup(...)

The `setup` function is a named export, used for configuring custom methods and assertions globally or per-instance.

syntax

✓ import { syntax } from 'jora'

✗ import { JoraSyntax } from 'jora'

The `syntax` object provides utilities for parsing, tokenizing, and working with the Jora query AST, useful for advanced tooling and editor integrations.

This example demonstrates defining global custom methods and assertions using `setup`, then compiling and executing a Jora query that filters data, uses the custom functions, and aggregates results.

import jora, { setup } from 'jora'; // Setup custom methods and assertions globally (optional) setup({ methods: { addOne: (value) => value + 1, sumAll: (arr) => arr.reduce((acc, current) => acc + current, 0), }, assertions: { isPositive: (value) => value > 0, hasTag: (value, tag) => Array.isArray(value) && value.includes(tag), } }); const data = [ { id: 1, name: 'Apple', price: 1.2, tags: ['fruit', 'sweet'] }, { id: 2, name: 'Banana', price: 0.8, tags: ['fruit'] }, { id: 3, name: 'Carrot', price: 0.5, tags: ['vegetable', 'root'] }, { id: 4, name: 'Milk', price: 2.5, tags: ['dairy', 'drink'] }, { id: 5, name: 'Orange', price: 1.5, tags: ['fruit', 'citrus'] } ]; // Compile a query using custom methods and assertions const query = jora(` .[tags.hasTag('fruit') and price.isPositive()] | { count: count(), avgPrice: avg(price), names: name.addOne() } `); // Execute the compiled query against the data const result = query(data); console.log(JSON.stringify(result, null, 2)); /* Expected output: { "count": 3, "avgPrice": 1.1666666666666667, "names": [ "Apple1", "Banana1", "Orange1" ] } */

Debug

Known issues

breakingThe Jora project is still in beta, and its syntax is explicitly noted as subject to change in future releases. Queries written against current beta versions might require adjustments when upgrading.

fix

Always review release notes when upgrading to new beta versions and test existing queries thoroughly for compatibility.

affects: >=1.0.0-beta.0

breakingThe signature for the `setup()` function was changed from `setup(methods)` to `setup({ methods })`. Directly passing the methods dictionary will no longer work.

fix

Update your `setup` calls to pass an options object: `setup({ methods: { ... }, assertions: { ... } })`.

affects: >=1.0.0-beta.8

breakingSupport for a legacy function syntax, i.e., `<expr>`, was removed. Queries using this format will fail to parse.

fix

Rewrite function expressions using the new syntax: `$arg => expr` or `($a, $b) => expr`.

affects: >=1.0.0-beta.9

breakingDuplicate parameter names in function definitions (e.g., `($a, $a) => expr`) are now prohibited and will cause a compilation error.

fix

Ensure all parameter names within Jora function definitions are unique.

affects: >=1.0.0-beta.13

breakingThe behavior of `this` within custom methods and assertions defined as functions was changed. `this` now includes a `context` reference to the query context.

fix

If your custom methods relied on a different `this` context, refactor them to access the new `context` property or adjust based on the updated `this` binding.

affects: >=1.0.0-beta.10

breakingA JavaScript injection vulnerability in queries using escape sequences (e.g., `{\u005balert\u00281\u0029\u005d: 'test'}`) was fixed. While a fix, this might subtly change behavior for queries that intentionally or unintentionally relied on such constructions.

fix

Upgrade to `v1.0.0-beta.14` or later immediately to patch this vulnerability. Review any queries using complex escape sequences.

affects: >=1.0.0-beta.14

gotchaIt is no longer possible to override built-in methods and assertions using the `setup()` or `jora()` functions. Attempting to do so will result in an error.

fix

Choose unique names for your custom methods and assertions that do not clash with Jora's built-in functions.

affects: >=1.0.0-beta.8

Errors

Common errors & fixes

Method "foo" is not defined

Attempting to use a custom method named `foo` that has not been registered with Jora.

fix

Register your custom method using `jora.setup({ methods: { foo: (value) => ... } })` before compiling the query.

SyntaxError: Duplicate parameter name '$a'

A Jora function expression within your query defines the same parameter name more than once, which is now disallowed.

fix

Modify the function definition to use unique parameter names for each argument, e.g., `($a, $b) => expr`.

Error: Built-in method "length" cannot be overridden

Attempting to define a custom method or assertion with a name that conflicts with an existing built-in Jora method or assertion (e.g., `length`, `count`, `map`).

fix

Rename your custom method or assertion to avoid conflict with Jora's built-in functions. Refer to Jora documentation for a list of built-ins.

Error: Unexpected token <

Your Jora query contains a function definition using the deprecated `<expr>` syntax, which has been removed.

fix

Update the function definition to use the modern Jora function syntax, such as `$arg => expr` or `($a, $b) => expr`.

Upgrade

Version history

1.0.0-beta.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/discoveryjs/jora ↗

packagehttps://www.npmjs.com/package/jora ↗