Jora

Common errors

• Method "foo" is not defined

  cause 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'

  cause 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

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

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

Warnings

• breaking The 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.
• breaking The 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: { ... } })`.
• breaking Support 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`.
• breaking Duplicate 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.
• breaking The 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.
• breaking A 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.
• gotcha It 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.

Install

• npm install jora npm
• yarn add jora yarn
• pnpm add jora pnpm

Imports

• jora
  wrong:

  const jora = require('jora')

  correct:

  import jora from 'jora'

  Jora is primarily consumed as a default export, providing the main query function.
• setup
  wrong:

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

  correct:

  import { setup } from 'jora'

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

  import { JoraSyntax } from 'jora'

  correct:

  import { syntax } from 'jora'

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

Quickstart

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"
  ]
}
*/