JavaScript object query engine

STATUS: Jora is still very much work in progress. Syntax may change in next releases.

Features:

• Tolerant to data stucture queries (e.g. just returns nothing for paths that not reachable)
• Compact syntax for common tasks
• Aggregate values across arrays and eliminate duplicates by default
• Stat collecting mode (powers suggestions)
• Tolerant parsing mode (useful to provide suggestions for query in an editor)
• Extensible DSL on query build by custom method list

Related projects:

• jora-cli – Command line interface for Jora
• Jora sandbox – A Web interface where you can play with jora syntax or transform some JSON with zero setup
• Discovery – Uses jora to query a data for views
• JsonDiscovery – a browser’s extension for viewing JSON based on Discovery, available for Chrome and Firefox (read more in the article Changing a way we’re viewing JSON in a browser)

TODO:

• AST
• Immutable paths hoisting (reduce computations -> performance)
• Smart computation caching across queries
• Query parts performance stat
• Query transforming, e.g. query merge, subquery to a query, context inlining
• Method namespaces, e.g. semver, path, math etc
• Syntax highlighting
• Prettifier
• Move jison to dev dependencies
• Debugging (step by step evaluation)
• Input data shape prediction suitable for a query (based on touching paths)

More ideas and thoughts: Jora todo gist, Jora ToDo on Discovery.js projects state overview

Table of content:

• Install
• API
• Quick demo
• Syntax
  • Comments
  • Primitives
  • Keywords
  • Operators
  • Comparisons
  • Boolean logic
  • Block & definitions
  • Special references
  • Path chaining
  • Build-in methods
• License

npm install jora

In node.js

const jora = require('jora');

For a browser unminified (dist/jora.js) and minified (dist/jora.min.js) builds are available:

<script src="node_modules/jora/dist/jora.js"></script>
<script src="node_modules/jora/dist/jora.min.js"></script>
<!-- or use one of CDN -->
<script src="https://unpkg.com/jora/dist/jora.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jora/dist/jora.js"></script>

const jora = require('jora');

// create a query
const query = jora('foo.bar');
// or with custom methods
const queryWithCustomMethods = jora.setup({
    myMethod(current) { /* do something and return a new value */ }
});

// perform a query
const result = query(data, context);
const result = queryWithCustomMethods('foo.myMethod()')(data, context);

Options:

• methods

  Type: Object
  Default: undefined

  Additional methods for using in query passed as an object, where a key is a method name and a value is a function to perform an action. It can override build-in methods.

• debug

  Type: Boolean or function(name, value)
  Default: false

  Enables debug output. When set a function, this function will recieve a section name and its value.

• tolerant

  Type: Boolean
  Default: false

  Enables tolerant parsing mode. This mode supresses parsing errors when possible.

• stat

  Type: Boolean
  Default: false

  Enables stat mode. When mode is enabled a query stat interface is returning instead of resulting data.

Get npm dependency paths (as a tree) that have packages with more than one version:

const jora = require('jora');

function printTree() {
    // see implementation in examples/npm-ls.js
}

require('child_process').exec('npm ls --json', (error, stdout) => {
    if (error) {
        return;
    }

    const npmTree = JSON.parse(stdout);
    const tree = JSON.parse(stdout);
    const depsPathsToMultipleVersionPackages = jora(`
        $normalizedDeps: => dependencies.entries().({ name: key, ...value });
        $multiVersionPackages:
            ..$normalizedDeps()
            .group(=>name, =>version)
            .({ name: key, versions: value.sort() })
            .[versions.size() > 1];

        $pathToMultiVersionPackages: => .($name; {
            name,
            version,
            otherVersions: $multiVersionPackages[=>name=$name].versions - version,
            dependencies: $normalizedDeps()
                .$pathToMultiVersionPackages()
                .[name in $multiVersionPackages.name or dependencies]
        });

        $pathToMultiVersionPackages()
    `)(tree);

    printTree(depsPathsToMultipleVersionPackages);
});

Example of output:

jora@1.0.0
├─ browserify@16.2.2
│  ├─ assert@1.4.1
│  │  └─ util@0.10.3 [other versions: 0.10.4]
│  │     └─ inherits@2.0.1 [other versions: 2.0.3]
│  ├─ browser-pack@6.1.0
│  │  └─ combine-source-map@0.8.0
│  │     ├─ source-map@0.5.7 [other versions: 0.6.1, 0.4.4, 0.2.0, 0.1.43]
│  │     └─ inline-source-map@0.6.2
│  │        └─ source-map@0.5.7 [other versions: 0.6.1, 0.4.4, 0.2.0, 0.1.43]
│  ├─ browser-resolve@1.11.3
│  │  └─ resolve@1.1.7 [other versions: 1.8.1]
│  ├─ concat-stream@1.6.2
│  │  └─ inherits@2.0.3 [other versions: 2.0.1]
...

// single-line comment
/* multi-line
comment */

Following keywords can be used with the same meaning as in JavaScript:

• true
• false
• null
• undefined
• Infinity
• NaN

Some constructions suppose to use a block, which may consists of a variable definition list (should comes first) and an expression. Both are optional. When an expression is empty, a current value (i.e. $) returns.

The syntax of definition (white spaces between any part are optional):

$ident ;
$ident : expression ;

For example:

$foo:123;          // Define `$foo` variable
$bar;              // The same as `$bar:$.bar;` or `$a: bar;`
$baz: $foo + $bar; // Definitions may be used in following expressions

In terms of JavaScript, a block creates a new scope. Once a variable is defined, its value never change. Variables can be redefined in nested scopes, but can't be duplicated in the same scope - it causes to error.

Since Jora's query performs as query(data, context), in terms of Jora it looks like query(@, #).

MIT