package query-json

query-json is a faster, simpler and more portable implementation of the jq language in OCaml distributed as a binary, but also distributed as a JavaScript package via js_of_ocaml.

query-json allows you to write small programs to operate on top of json files with a concise syntax.

Purpose

It was created with mostly two reasons in mind, learning and having fun

• Learn how to write a programming language with the OCaml stack using menhir, sedlex and friends and try to make great error messages.
• Create a CLI tool in OCaml and being able to distribute it to twoo different platforms: as a binary (for performance) and as a JavaScript library (for portability).

What it brings

• Great Performance: Fast, small footprint and minimum runtime. Check Performance section for a longer explanation, but it can be 2x to 5x faster than jq.

• Delightful errors:

  • Better errors when json types and operation don't match:

        $ query-json '.esy.release.wat' esy.json
    Error:  Trying to ".wat" on an object, that don't have the field "wat":
    { "bin": ... }

  • debug prints the tokens and the AST.
  • verbose flag, prints each operation in each state and it's intermediate states. (Work in progress...)

• Improved API: made small adjustments to the buildin operations. Some examples are:

  • All methods are snake_case instead of alltoghetercase
  • Added filter(p) as an alias for map(select(p))
  • Supports comments in JSONs
• Small: Lexer, Parser and Compiler are just 300 LOC and most of the commands that I use on my day to day are implemented in only 140 LOC.

Installation

Using a bash script

Check the content of scripts/install.sh before running anything in your local. Friends don't let friends curl | bash.

curl -sfL https://raw.githubusercontent.com/davesnx/query-json/master/scripts/install.sh | bash

Using npm

npm install --global @davesnx/query-json

Download zip files from GitHub

Usage

I recommend to write the query in single-quotes inside the terminal, since writting JSON requires double-quotes for accessing properties.

query a json file

query-json '.' pokemons.json

query from stdin

cat pokemons.json | query-json '.'
query-json '.' <<< '{ "bulvasur": { "id": 1, "power": 20 } }'

query a json inlined

query-json --kind=inline '.' '{ "bulvasur": { "id": 1, "power": 20 } }'

query without colors

query-json '.' pokemons.json --no-colors

Performance

This report is not an exhaustive performance report of both tools, it's a overview for the percieved performance of the user. I don't profile each tool and try to see what are the bootlenecks, since I assume that both tools have the penalty of parsing a JSON file.

Aside from that, query-json doesn't have feature parity with jq which is ok at this point, but jq contains a ton of functionality that query-json misses. Adding the missing operations on query-json won't affect the performance of it, that could not be true for features like "modules", "functions" or "tests".

The report shows that query-json is between 2x and 5x faster than jq in all operations tested and same speed (~1.1x) with huge files (> 100M).

Currently supported feature set

Based on jq 1.6

CLI: Invoking jq

• --version ✅

• --kind. This is different than jq ✅

  • --kind=file and the 2nd argument can be a json file
  • --kind=inline and the 2nd argument can be a json as a string
• --no-color. This disables colors ✅
• ...rest ⚠️

Basic filters

• Identity: . ✅
• Object Identifier-Index: .foo, .foo.bar ✅
• Optional Object Identifier-Index: .foo? ✅
• Generic Object Index: .[<string>] ✅
• Array Index: .[2] ✅
• Array Multi-Index: .[0,2,4] ✅
• Pipe: | ✅
• Array/String Slice: .[10:15] ✅
• Array/Object Value Iterator: .[] ✅
• Comma: , ✅
• Parenthesis: () ✅️
• Dictionary Construction: {key: value} ✅

Types and Values ⚠️

Builtin operators and functions

• Abs: abs ✅
• Add: add ✅
• Addition: + ✅
• Subtraction: - ✅
• Multiplication, division: *, / ✅
• Modulo: % ✅
• length ✅
• keys ✅
• map ✅
• select ✅
• has(key) ✅
• in ✅
• path(path_expression) ⚠️
• to_entries, from_entries, with_entries ⚠️
• any, any(condition), any(generator; condition) ⚠️
• all, all(condition), all(generator; condition) ⚠️
• flatten ⚠️
• range(upto), range(from;upto) range(from;upto;by) ✅
• floor, sqrt ⚠️
• tonumber, tostring ⚠️
• type ⚠️
• infinite, nan, isinfinite, isnan, isfinite, isnormal ⚠️
• sort, sort_by(path_expression) ⚠️
• group_by(path_expression) ⚠️
• min, max, min_by(path_exp), max_by(path_exp) ⚠️
• unique, unique_by(path_exp) ⚠️
• reverse ✅
• contains(element) ⚠️
• index(s), rindex(s) ⚠️
• startswith(str), endswith(str) ⚠️
• explode, implode ⚠️
• split(str), join(str) ✅
• while(cond; update), until(cond; next) ⚠️
• recurse(f), recurse, recurse(f; condition), recurse_down ⚠️
• walk(f) ⚠️
• transpose(f) ⚠️
• Format strings and escaping: @text, @csv, etc.. 🔴

Conditionals and Comparisons

• ==, != ✅
• if-then-else ✅
• >, >=, <=, < ✅
• and, or, not ✅
• break 🔴

Regular expressions (PCRE) ⚠️

Advanced features ⚠️

Assignment ⚠️

Modules ⚠️

Contributing

Contributions are what make the open source community such an amazing place to be, learn, inspire, and create. Any contributions you make are greatly appreciated. If you have any questions just contact me on x or email dsnxmoreno at gmail dot com.

Support

I usually hang out at discord.gg/reasonml or x.com/davesnx so feel free to ask anything.

Setup

Requirements: opam

git clone https://github.com/davesnx/query-json
cd query-json
make init # creates opam switch, installs ocaml deps and npm deps
make dev-core # compiles query-json "core" only
make test # runs unit tests and snapshots tests
dune exec query-json # Run binary

Running the playground

# In different terminals
make dev # compiles all packages "query-json" "query-json-s" and "query-json-playground", and runs the bundler
make web-dev # Runs bundler