Skip to content

feat(jq): add --arg and --argjson flags#162

Open
pawaca wants to merge 3 commits intovercel-labs:mainfrom
pawaca:feat/jq-arg-argjson
Open

feat(jq): add --arg and --argjson flags#162
pawaca wants to merge 3 commits intovercel-labs:mainfrom
pawaca:feat/jq-arg-argjson

Conversation

@pawaca
Copy link
Copy Markdown

@pawaca pawaca commented Mar 19, 2026

Summary

Adds the two most commonly used jq variable-passing flags:

  • --arg name value — binds $name as a string value
  • --argjson name json — binds $name as a parsed JSON value

These are essential for parameterized jq filters in shell scripts, e.g.:

echo '{"items":[{"name":"a"},{"name":"b"}]}' | jq --arg target b '.items[] | select(.name == $target)'
echo 'null' | jq -n --argjson config '{"limit":10}' '$config.limit'

Implementation

Leverages the existing variable binding infrastructure in the query engine (EvalContext.vars / withVar):

  • evaluator.ts: Added initialVars?: Map<string, QueryValue> to EvaluateOptions, used to pre-populate EvalContext.vars in createContext()
  • jq.ts: Parse --arg/--argjson flags during argument processing, collect into initialVars map, pass to evaluate options
  • Error handling for missing arguments and invalid JSON (exit code 2, matching real jq behavior)

Total change: ~30 lines of implementation + ~120 lines of tests.

Tests

13 new test cases covering:

  • --arg: string binding, select filtering, multiple args, type correctness (always string)
  • --argjson: number, object, array, boolean binding
  • Error cases: missing arguments, invalid JSON
  • Combined --arg + --argjson usage
  • All 47 jq tests pass (34 existing + 13 new)

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 19, 2026

@pawaca is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

@cramforce
Copy link
Copy Markdown
Contributor

Looks great. Please fix lint!

pawaca and others added 3 commits March 20, 2026 23:07
Implement the two most commonly used jq variable-passing flags:

- `--arg name value` binds $name as a string
- `--argjson name json` binds $name as a parsed JSON value

These leverage the existing variable binding infrastructure in the
query engine (EvalContext.vars / withVar). The implementation adds
an `initialVars` field to EvaluateOptions that pre-populates the
evaluation context before filter execution.

Includes 13 new tests covering: string binding, select filtering,
multiple args, type correctness (--arg always string), JSON types
(number/object/array/boolean), error handling, and combined usage.
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants