Repository files navigation

query-json is afaster, simpler and more portable implementation of thejq language in OCaml distributed as a binary, but also distributed as a JavaScript package viajs_of_ocaml.

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

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

• Learn how to write a programming language with the OCaml stack usingmenhir,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).

• Great Performance: Fast, small footprint and minimum runtime. CheckPerformance 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.jsonError:  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
  • Addedfilter(p) as an alias formap(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.

Check the content ofscripts/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

npm install --global @davesnx/query-json

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

NOTE: I have aliased query-json to "q" for short, you can set it in your dotfiles withalias q="query-json".

query-json'.' pokemons.json

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

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

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

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 withjq which is ok at this point, butjq contains a ton of functionality that query-json misses. Adding the missing operations onquery-json won't affect the performance of it, that could not be true for features like "modules", "functions" or "tests".

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

• --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⚠️

• Identity:. ✅
• Object Identifier-Index:.foo,.foo.bar ✅
• Optional Object Identifier-Index:.foo? ✅
• Generic Object Index:.[<string>] ✅
• Array Index:.[2] ✅
• Pipe:| ✅
• Array/String Slice:.[10:15] ✅
• Array/Object Value Iterator:.[]⚠️
• Comma:, ✅
• Parenthesis:() ✅️

• Abs:abs ✅
• Add:add ✅
• Addition:+ ✅
• Subtraction:- ✅
• Multiplication, division, modulo:*,/, and% ✅
• 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.. 🔴

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

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@twitter or email dsnxmoreno at gmail dot com.

I usually hang out atdiscord.gg/reasonml orx.com/davesnx so feel free to ask anything.

Requirements:opam

git clone https://github.com/davesnx/query-jsoncd query-jsonmake init# creates opam switch, installs ocaml deps and npm depsmake dev-core# compiles query-json "core" onlymaketest# runs unit tests and snapshots testsduneexec query-json# Run binary

Running the playground

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