jmespath.js

jmespath.js is the official JavaScript implementation of JMESPath, a query language purpose-built for JSON. Instead of writing loops and conditionals to dig values out of nested objects and arrays, you write a single expression string — such as foo.bar[?age > \30`].name` — and jmespath.js parses, compiles, and evaluates it against your data to return exactly the shape you asked for.

The library ships as a dependency-free UMD module with three entry points: search for the common one-shot case, plus compile/tokenize for callers that want to inspect or reuse a parsed expression. Because JMESPath itself is a language specification with implementations across Python, Ruby, PHP, Lua, Go, and more, expressions written against jmespath.js are portable to any other JMESPath-compatible tool — most notably the AWS CLI’s --query flag, which uses the same grammar.

What You Get

• A single search(data, expression) function for one-shot querying of any JSON-compatible JavaScript value
• compile/tokenize APIs for parsing an expression once and reusing or introspecting its AST
• Full JMESPath grammar support: filters, projections, flatten operators, multi-select lists/hashes, and pipe expressions
• A built-in function library covering string, array, and object helpers (sort_by, max_by, merge, contains, to_string, type, and more)
• Zero runtime dependencies and a small, dependency-free UMD bundle that works in Node.js and the browser
• Cross-language expression portability — expressions written here work unmodified against any other JMESPath implementation, including the AWS CLI’s --query

Common Use Cases

• Extracting and reshaping specific fields from deeply nested API responses without writing custom traversal code
• Filtering and projecting arrays of objects (e.g. “names of users over age 30”) in a single expression
• Powering user-facing query boxes where non-developers can filter JSON data using a documented, portable syntax
• Sharing one query expression across services written in different languages via the shared JMESPath spec

Under The Hood

Architecture — jmespath.js is structured as a classic three-stage interpreter pipeline in a single UMD-wrapped file (jmespath.js): a Lexer walks the raw expression string character-by-character into a flat token stream (identifiers, brackets, operators, literals); a Parser consumes that stream with a Pratt (top-down operator-precedence) algorithm — driven by a bindingPower table that ranks operators like | (pipe), ||/&&, comparisons, and ./[ access — into an AST of typed nodes (Field, Subexpression, IndexExpression, Projection, Slice, and more); a TreeInterpreter then walks that AST via a large switch in visit(), threading the current JSON value through each node type and delegating to a Runtime object for built-in function calls. exports.search() composes all three stages for the one-shot case, while exports.compile() exposes just the Lexer+Parser output so callers can cache and reuse an AST across many evaluations.

Tech Stack — the library has zero runtime dependencies; the entire lexer, parser, interpreter, and function table live in one ~1,670-line file distributed as both a raw script and a Grunt-built minified bundle (see Gruntfile.js, artifacts/). Development tooling is Grunt-based (grunt-contrib-jshint, grunt-contrib-uglify, grunt-eslint) and testing uses Mocha. package.json declares "engines": {"node": ">= 0.6.0"}, reflecting the project’s age (created 2014) and its design as a portable, dependency-free reference implementation rather than a modern build-tooled package.

Code Quality — the repo carries two test suites: test/jmespath.js (234 lines of unit tests against the Lexer/Parser/Interpreter directly) and test/compliance.js (56 lines, a harness that runs the shared cross-language JMESPath compliance fixtures under test/compliance/), giving the implementation confidence against the same spec-level test cases used by the Python, Go, and Ruby ports. Error handling is explicit and typed: the Lexer and Parser both throw Error objects with a distinguishing .name (LexerError, ParserError) rather than generic exceptions, and the Runtime performs argument-type checking against declared function signatures (_signature: [{types: [...]}]) before invoking a built-in, producing clear type errors instead of silent undefined results. Naming is consistent and low-abstraction (functions like isArray, isObject, strictDeepEqual are hand-rolled rather than pulled from a utility dependency), consistent with the project’s zero-dependency goal; there are no TypeScript types shipped, and the last commit predates current JS tooling norms.

API Design — the public surface is deliberately minimal: search(data, expression) covers the overwhelming majority of use, with compile/tokenize available for advanced reuse — there is no configuration object, no class to instantiate, and no async surface, so getting started is a single function call shown directly in the README. The real ergonomic payoff is in the expression language itself: JMESPath’s built-in function library (sort_by, merge, contains, to_string, pipe expressions) lets consumers express nontrivial JSON reshaping without writing any JavaScript beyond the query string, and because the grammar is identical across every JMESPath implementation, developers who already know AWS CLI’s --query syntax get zero-cost transfer. The tradeoff is a small learning curve for the expression syntax itself, offset by the official jmespath.org tutorial and interactive spec the README links to.