{"id":11148,"library":"jora","title":"Jora","description":"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.","status":"active","version":"1.0.0-beta.15","language":"javascript","source_language":"en","source_url":"https://github.com/discoveryjs/jora","tags":["javascript","query","data","path","language","json"],"install":[{"cmd":"npm install jora","lang":"bash","label":"npm"},{"cmd":"yarn add jora","lang":"bash","label":"yarn"},{"cmd":"pnpm add jora","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Jora is primarily consumed as a default export, providing the main query function.","wrong":"const jora = require('jora')","symbol":"jora","correct":"import jora from 'jora'"},{"note":"The `setup` function is a named export, used for configuring custom methods and assertions globally or per-instance.","wrong":"import jora, { setup } from 'jora'; jora.setup(...)","symbol":"setup","correct":"import { setup } from 'jora'"},{"note":"The `syntax` object provides utilities for parsing, tokenizing, and working with the Jora query AST, useful for advanced tooling and editor integrations.","wrong":"import { JoraSyntax } from 'jora'","symbol":"syntax","correct":"import { syntax } from 'jora'"}],"quickstart":{"code":"import jora, { setup } from 'jora';\n\n// Setup custom methods and assertions globally (optional)\nsetup({\n  methods: {\n    addOne: (value) => value + 1,\n    sumAll: (arr) => arr.reduce((acc, current) => acc + current, 0),\n  },\n  assertions: {\n    isPositive: (value) => value > 0,\n    hasTag: (value, tag) => Array.isArray(value) && value.includes(tag),\n  }\n});\n\nconst data = [\n  { id: 1, name: 'Apple', price: 1.2, tags: ['fruit', 'sweet'] },\n  { id: 2, name: 'Banana', price: 0.8, tags: ['fruit'] },\n  { id: 3, name: 'Carrot', price: 0.5, tags: ['vegetable', 'root'] },\n  { id: 4, name: 'Milk', price: 2.5, tags: ['dairy', 'drink'] },\n  { id: 5, name: 'Orange', price: 1.5, tags: ['fruit', 'citrus'] }\n];\n\n// Compile a query using custom methods and assertions\nconst query = jora(`\n  .[tags.hasTag('fruit') and price.isPositive()] | {\n    count: count(),\n    avgPrice: avg(price),\n    names: name.addOne()\n  }\n`);\n\n// Execute the compiled query against the data\nconst result = query(data);\nconsole.log(JSON.stringify(result, null, 2));\n\n/*\nExpected output:\n{\n  \"count\": 3,\n  \"avgPrice\": 1.1666666666666667,\n  \"names\": [\n    \"Apple1\",\n    \"Banana1\",\n    \"Orange1\"\n  ]\n}\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Always review release notes when upgrading to new beta versions and test existing queries thoroughly for compatibility.","message":"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.","severity":"breaking","affected_versions":">=1.0.0-beta.0"},{"fix":"Update your `setup` calls to pass an options object: `setup({ methods: { ... }, assertions: { ... } })`.","message":"The signature for the `setup()` function was changed from `setup(methods)` to `setup({ methods })`. Directly passing the methods dictionary will no longer work.","severity":"breaking","affected_versions":">=1.0.0-beta.8"},{"fix":"Rewrite function expressions using the new syntax: `$arg => expr` or `($a, $b) => expr`.","message":"Support for a legacy function syntax, i.e., `<expr>`, was removed. Queries using this format will fail to parse.","severity":"breaking","affected_versions":">=1.0.0-beta.9"},{"fix":"Ensure all parameter names within Jora function definitions are unique.","message":"Duplicate parameter names in function definitions (e.g., `($a, $a) => expr`) are now prohibited and will cause a compilation error.","severity":"breaking","affected_versions":">=1.0.0-beta.13"},{"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.","message":"The behavior of `this` within custom methods and assertions defined as functions was changed. `this` now includes a `context` reference to the query context.","severity":"breaking","affected_versions":">=1.0.0-beta.10"},{"fix":"Upgrade to `v1.0.0-beta.14` or later immediately to patch this vulnerability. Review any queries using complex escape sequences.","message":"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.","severity":"breaking","affected_versions":">=1.0.0-beta.14"},{"fix":"Choose unique names for your custom methods and assertions that do not clash with Jora's built-in functions.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-beta.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Register your custom method using `jora.setup({ methods: { foo: (value) => ... } })` before compiling the query.","cause":"Attempting to use a custom method named `foo` that has not been registered with Jora.","error":"Method \"foo\" is not defined"},{"fix":"Modify the function definition to use unique parameter names for each argument, e.g., `($a, $b) => expr`.","cause":"A Jora function expression within your query defines the same parameter name more than once, which is now disallowed.","error":"SyntaxError: Duplicate parameter name '$a'"},{"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.","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`).","error":"Error: Built-in method \"length\" cannot be overridden"},{"fix":"Update the function definition to use the modern Jora function syntax, such as `$arg => expr` or `($a, $b) => expr`.","cause":"Your Jora query contains a function definition using the deprecated `<expr>` syntax, which has been removed.","error":"Error: Unexpected token <"}],"ecosystem":"npm"}