#mizchi/jq

#Features

• Lexer, recursive descent parser, callback-based evaluator
• 87.3% compatibility with jq's official test suite (151/173 verified tests)
• 50+ builtin functions
• Target: js (Node.js)

#Supported Syntax

#Known Incompatibilities with jq

#Parser Limitations

• {x:-.} (unary minus as object value without parens) is not supported. Use {x:(-.)}.
• try -.? does not propagate to catch correctly.
• String interpolation \(expr) is not supported.

#Numeric Precision

• Numbers use IEEE 754 double precision. Integers larger than 2^53 overflow to Infinity instead of being represented exactly.
• jq outputs 2.0 for some integer-valued float results (e.g., 1+1 with string input gives 2.0 in jq, 2 here).
• Scientific notation in output (e.g., 1e-1, 9E+999999999) may differ.

#Unicode / String Handling

• Control characters (\b, \f) are output as literal characters instead of \u00XX escape sequences.
• Unicode escapes like \u03bc may be output as the actual character (μ) instead of the escape form.
• contains with NUL bytes (\u0000) may not match correctly due to JavaScript string handling.

#Slice Indexing

• Float slice indices like .[1.2:3.5] use truncation (.[1:3]) instead of jq's rounding behavior (.[1:4]).

#Unsupported Features

• Assignment operators: =, |=, +=, -=, *=, /=, %=, //=
• Alternative operator: //
• Destructuring bind: as [$a, $b], as {$a}
• Alternative destructuring: ?//
• String interpolation: \(expr)
• Control flow: while, until, label, break, foreach
• Path operations: path, paths, setpath, delpaths, del, pick
• Format strings: @csv, @tsv, @sh, @urid
• Module system: import, include, modulemeta
• I/O: input, inputs, input_line_number
• Regex: test (pattern), match, capture, scan, sub, gsub, splits
• Other: env, builtins, $__loc__, $ENV, nth, skip, toboolean, utf8bytelength, halt, stderr, debug(msg), sqrt, sin, cos, atan, log, exp, pow, strftime, strptime, now, date, JOIN, REGEX

#walk Behavior

• walk(f) where f produces multiple outputs generates a combinatorial explosion instead of jq's first-output behavior.

#Benchmark (js target, pre-compiled eval)

#Optimizations Applied

• compile/run_compiled separation: Parse the filter once, evaluate many times
• Persistent scope chain: Linked-list env makes bind_var O(1) (no array copy)
• eval_single fast path: Single-output filters (Identity, Field, Literal, Pipe chains, variable refs) bypass callback/closure overhead
• AST optimization pass: Eliminates Pipe(Identity, x) → x, strips Paren wrappers at compile time
• Pre-baked $ prefix: Variable names include $ at parse time, avoiding runtime string concatenation

#Quick Commands

just           # check + test
just fmt       # format code
just check     # type check
just test      # run tests
just run       # run main

#License

#mizchi/jq

#Quick Start

///|
test {
  inspect(
    @jq.run_string(".foo", "{\"foo\":42}"),
    content=(
      #|["42"]
    ),
  )
}

#API

#run_string — One-shot string-based execution

///|
test {
  inspect(
    @jq.run_string("[.[] | select(. > 3)]", "[1,2,3,4,5]"),
    content=(
      #|["[4,5]"]
    ),
  )
}

#run — Execute with Json value

///|
test {
  let input = @json.parse("{\"a\":1,\"b\":2}")
  let results = @jq.run("{sum: (.a + .b)}", input)
  inspect(
    results[0].stringify(),
    content=(
      #|{"sum":3}
    ),
  )
}

#compile + run_compiled — Pre-compile for repeated use

///|
test {
  let filter = @jq.compile("map(. * 2)")
  let r1 = @jq.run_compiled(filter, @json.parse("[1,2,3]"))
  let r2 = @jq.run_compiled(filter, @json.parse("[10,20]"))
  inspect(r1[0].stringify(), content="[2,4,6]")
  inspect(r2[0].stringify(), content="[20,40]")
}

#Error Handling

///|
test {
  let result = @jq.run_string(".foo", "not json") catch {
    @jq.JqError::JqError(msg) => ["Error: " + msg]
  }
  inspect(result[0].has_prefix("Error:"), content="true")
}

#Examples

#Field Access and Pipes

///|
test {
  let input = "{\"user\":{\"name\":\"alice\",\"age\":30}}"
  inspect(
    @jq.run_string(".user.name", input),
    content=(
      #|["\"alice\""]
    ),
  )
  inspect(
    @jq.run_string(".user | keys", input),
    content=(
      #|["[\"age\",\"name\"]"]
    ),
  )
}

#Array Operations

///|
test {
  let arr = "[3,1,4,1,5,9,2,6]"
  inspect(
    @jq.run_string("sort | unique", arr),
    content=(
      #|["[1,2,3,4,5,6,9]"]
    ),
  )
  inspect(
    @jq.run_string("map(. * 2) | add", arr),
    content=(
      #|["62"]
    ),
  )
}

#Reduce

///|
test {
  inspect(
    @jq.run_string("reduce .[] as $x (0; . + $x)", "[1,2,3,4,5]"),
    content=(
      #|["15"]
    ),
  )
}

#Object Construction

///|
test {
  let input = "[{\"name\":\"a\",\"val\":1},{\"name\":\"b\",\"val\":2}]"
  inspect(
    @jq.run_string("map({(.name): .val}) | add", input),
    content=(
      #|["{\"a\":1,\"b\":2}"]
    ),
  )
}

#Conditionals

///|
test {
  inspect(
    @jq.run_string(
      "map(if . > 0 then \"pos\" elif . == 0 then \"zero\" else \"neg\" end)", "[-1,0,1]",
    ),
    content=(
      #|["[\"neg\",\"zero\",\"pos\"]"]
    ),
  )
}

#User-Defined Functions

///|
test {
  inspect(
    @jq.run_string(
      "def double: . * 2; def inc: . + 1; map(double | inc)", "[1,2,3]",
    ),
    content=(
      #|["[3,5,7]"]
    ),
  )
}

#Format Strings

///|
test {
  inspect(
    @jq.run_string("@base64", "\"hello\""),
    content=(
      #|["\"aGVsbG8=\""]
    ),
  )
  inspect(
    @jq.run_string("@base64d", "\"aGVsbG8=\""),
    content=(
      #|["\"hello\""]
    ),
  )
}