How jsonata-js/jsonata works
Project type and purpose
• JSONata is a reference implementation of a JSON query & transformation language.
• It can be embedded in Node.js or browsers.
• It provides a parser, evaluator, built-in function library, and a small polyfill for older JS environments.
• It ships docs and a static website as part of the repo.
File structure
Top-level components:
• src/ → core modules
– jsonata.js → public API entry
– parser.js → converts expression strings to AST
– signature.js → builds the evaluation signature tree
– functions.js → registry for all built-in functions
– datetime.js → date/time library
– utils.js → shared utilities
• polyfill.js → ES feature polyfills
• test/ → test harness and JSONata conformance suites
• docs/ → Markdown reference docs
• website/ → Docusaurus-style static site
• package.json, bower.json → build & distribution configs
Key points from the README
• “Require('jsonata')” or “<script src='jsonata.min.js'>”
• expression.evaluate(data) asynchronously returns results
• Extensive language docs live on docs.jsonata.org
• repo contains both code & documentation sources
Main components and relationships
A. External Clients
– Node.js applications
– Browser applications
↳ both import the same UMD bundle (jsonata.min.js) which may include polyfill.js
B. Public API Facade (src/jsonata.js)
– Exposes jsonata() factory → Expression object
C. Parser (src/parser.js)
– Parses expression text → produces AST
D. Signature Builder (src/signature.js)
– Converts AST → internal “signature tree” for evaluation
E. Evaluator & Runtime
– Walks signature tree → invokes built-in functions
– Uses functions.js & datetime.js for built-in behavior
– Utils.js provides generic helpers (e.g., deep-equals)
F. Built-in Function Registry (src/functions.js)
– Registers each “$sum”, “$filter”, etc.
G. Polyfill Layer (polyfill.js)
– Provides compatibility (e.g., Promise in older browsers)
H. Test Harness (test/run-test-suite.js)
– Loads test/test-suite data & runs parser + evaluator → conformance results
I. Documentation & Website
– docs/ Markdown guides → website/ static site generator → published docs
Architectural patterns & design principles
• Modularized: parser, signature, evaluator are separate
• Pluggable Parser: regex-based, can replace regex engine
• Functional: built-ins are pure and registered centrally
• UMD build: works in Node, AMD, browser globals
Side Subsystems
• Test Harness:
– Loads AST & signature, runs conformance tests against datasets
• Documentation Pipeline:
– docs/ + versioned_docs/ → static site in website/