Jora JavaScript Object Query Engine

Jora is an expressive query language designed for querying and transforming JavaScript-like or JSON data. It acts as a superset of JSON5 and shares significant syntax similarities with JavaScript.

Key characteristics include:

• Compact Syntax: Optimized for common data transformation tasks.
• Automatic Aggregation: Aggregates values across arrays and eliminates duplicates by default.
• Safety: By default, Jora does not mutate input data or cause side effects. It is designed to be exception-safe; if a path is unreachable or an operator is inapplicable, it returns undefined rather than throwing an error.
• Extensibility: Supports custom methods.
• Tooling Support: Includes modes for stat collecting (to power suggestions) and tolerant parsing (useful for editor-based query suggestions).

The Jora documentation is organized into several key areas to help you master the query language:

• Introduction & API: Start with the Introduction for core concepts and the Jora library API for technical details on the library's interface.
• Query Syntax: A comprehensive guide to building queries, covering everything from basic Literals and Operators to advanced Functions and Methods.
• Data Manipulation: Learn how to transform data using Mapping, Filtering, Grouping, and Sorting.
• Complex Queries: For real-world application, refer to the Complex Jora query examples.

Jora is part of a broader ecosystem of tools:

• Discovery: A project that uses Jora as its core functionality to transform data flows for views and query data for reports.
• JsonDiscovery: A browser extension (available for Chrome and Firefox) based on Discovery for viewing JSON documents in a browser.
• jora-cli: A command line interface for transforming JSON-like data using Jora queries.

Comparator functions are specialized functions used to return -1, 0, or 1 to order values. They are used by methods like sort(), min(), and max().

Syntax:

• expr asc: Sorts in ascending order based on the expression.
• expr desc: Sorts in descending order based on the expression.
• Multi-level sorting: You can provide a comma-separated sequence of expressions to define a single comparator (e.g., foo asc, bar.size() desc).

Type Comparison Order: When comparing different types, Jora follows this hierarchy (from lowest to highest):

1. boolean
2. NaN
3. number
4. string
5. null
6. object
7. other
8. undefined

// Basic descending sort
$input: [{ foo: 3 }, { foo: 1 }, { foo: 5 }];
$input.sort(foo desc)

// Multi-level sort example
// (a, b) => a.foo > b.foo ? 1 : ... (then checks bar.size)
foo asc, bar.size() desc

Assertions are functions used to evaluate values against specified criteria. They use a dedicated syntax that is separate from standard methods. The basic syntax is expr is assertion. You can also omit the expression (e.g., is assertion) to assert against the current context.

Assertions support logical operators for complex evaluations:

• not: Negation (is not assertion or is not (assertion and assertion))
• and: Logical AND (is (assertion and assertion))
• or: Logical OR (is (assertion or assertion))
• Parentheses () can be used for grouping logical operations.

Jora's mapping logic has specific rules regarding the size and content of the resulting array:

1. Automatic Uniqueness: Mapping results in an array of unique values. For example, [1, 2, 2].() results in [1, 2].
2. Array Flattening/Concatenation: If the mapping function returns an array, those elements are merged into the result set. Duplicates are still dropped during this process.

// Mapping returns unique values
[ 1, 2, 2, 3, 3, 3 ].() // .() is equivalent to .($)
// Result: [1, 2, 3]

// Concatenating arrays with overall result
$input: [
    { "values": [1, 2, 3] },
    { "values": [3, 4] }
];
$input.(values)
// Result: [ 1, 2, 3, 4 ]

Mapping in Jora allows you to transform elements of an array, or even primitive types and objects, into a new structure.

Key Behaviors:

• Uniqueness: Mapping automatically returns unique values. This means the resulting array may be shorter than the input array.
• Array Concatenation: If the mapping expression returns an array, those elements are concatenated into the overall result (with duplicates dropped).
• Undefined Handling: Jora automatically ignores undefined values during mapping, effectively filtering them out of the result.
• Primitive Support: Mapping can be applied to single values (numbers, strings, etc.) to transform them into objects or other types.

// Syntax options
.(expr)
.map(fn) // or .map(=> expr)

In Jora, the spread operator ... inlines arrays, but leaves other types (like numbers, strings, or objects) as they are within the new array. This differs from JavaScript behavior.

[...[1, 2], ...3, ..."45", ...{ "6": 7 }]
// Result: [1, 2, 3, "45", { "6": 7 }]

While .[…] is generally preferred for concisenness, both syntaxes are functionally equivalent and can be used interchangeably depending on your need for readability or flexibility.

Equivalence mapping:

• .filter(fn) is equivalent to .[fn()]
• .[expr] is equivalent to .filter(=> expr)

In Jora, methods are functions invoked in a functional style. The value on the left side of the method call (the expression expr) is automatically passed as the first argument to the method. If no expression is provided, the implicit value $ is passed as the first argument.

This allows for chaining operations where each method receives the result of the previous one.

// Example of functional chaining
expr.method1().method2()

// Using the implicit '$' if no expression is provided
.method(...args)

// Using a function as a method
method(...args)