tessl/npm-jsonata

JSON query and transformation language for extracting, filtering, and transforming JSON data

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

JSONata

Name: tessl/npm-jsonata
Author: tessl

JSONata is a lightweight query and transformation language for JSON data that provides a comprehensive solution for extracting, filtering, and transforming JSON documents using a functional programming approach. It offers an expressive syntax that combines path expressions, predicates, and built-in functions to enable complex data manipulations, aggregations, and restructuring operations without requiring external dependencies.

Package Information

Package Name: jsonata
Package Type: npm
Language: JavaScript
Installation: npm install jsonata

Core Imports

const jsonata = require("jsonata");

For ES modules:

import jsonata from "jsonata";

Basic Usage

const jsonata = require("jsonata");

const data = {
  example: [
    { value: 4 },
    { value: 7 },
    { value: 13 }
  ]
};

// Create and evaluate expression
const expression = jsonata("$sum(example.value)");
const result = await expression.evaluate(data); // returns 24

// Using bindings
const expr = jsonata("name & ' is ' & $string(age) & ' years old'");
const person = { name: "John", age: 30 };
const greeting = await expr.evaluate(person); // "John is 30 years old"

Architecture

JSONata is built around several key components:

Expression Factory: Main jsonata() function that parses expressions and returns evaluation objects
AST Parser: Converts string expressions into abstract syntax trees for evaluation
Expression Evaluator: Processes AST nodes against input data with environment bindings
Built-in Functions: Comprehensive library of 60+ functions for data manipulation
Type System: Handles JavaScript types with implicit conversions and type checking
Error Handling: Detailed error reporting with position information and error codes

Capabilities

Expression Creation and Evaluation

Core functionality for creating and evaluating JSONata expressions against JSON data.

/**
 * Create a JSONata expression object
 * @param expression - JSONata query expression string
 * @param options - Optional configuration
 * @returns Expression object with evaluation methods
 */
function jsonata(expression, options);

interface JsonataOptions {
  recover?: boolean;        // Attempt to recover on parse errors
  RegexEngine?: RegExp;     // Custom regex engine constructor
}

Expression Management

Numeric Operations

Functions for mathematical calculations, aggregations, and numeric transformations.

// Aggregation functions
function $sum(array);
function $count(array);
function $max(array);
function $min(array);
function $average(array);

// Math functions  
function $abs(number);
function $floor(number);
function $ceil(number);
function $round(number, precision);
function $sqrt(number);
function $power(base, exponent);
function $random();

Numeric Functions

String Processing

Comprehensive string manipulation, formatting, and transformation functions.

// String operations
function $string(value, prettify);
function $substring(string, start, length);
function $substringBefore(string, chars);
function $substringAfter(string, chars);
function $lowercase(string);
function $uppercase(string);
function $length(string);
function $trim(string);
function $pad(string, width, char);

// String processing
function $split(string, separator, limit);
function $join(array, separator);
function $match(string, pattern, limit);
function $contains(string, pattern);
function $replace(string, pattern, replacement, limit);

String Functions

Array and Object Manipulation

Functions for transforming, filtering, and manipulating arrays and objects.

// Array operations
function $map(array, function);
function $filter(array, function);
function $zip(...arrays);
function $append(array1, array2);
function $reverse(array);
function $sort(array, function);
function $shuffle(array);
function $distinct(array);

// Object operations  
function $keys(object);
function $lookup(object, key);
function $spread(object);
function $merge(array);
function $sift(object, function);
function $each(object, function);

Data Manipulation

Date and Time Processing

Functions for working with timestamps, date formatting, and time calculations.

function $now(picture, timezone);
function $millis();
function $toMillis(timestamp, picture);
function $fromMillis(millis, picture, timezone);
function $formatInteger(number, picture);
function $parseInteger(string, picture);

Date/Time Functions

Encoding and Utilities

Encoding functions, type checking, and utility operations.

// Encoding functions
function $base64encode(string);
function $base64decode(string);
function $encodeUrlComponent(string);
function $encodeUrl(string);
function $decodeUrlComponent(string);
function $decodeUrl(string);

// Utility functions
function $type(value);
function $boolean(value);
function $not(value);
function $exists(value);
function $error(message);
function $assert(condition, message);

Utility Functions

Types

// Expression object returned by jsonata()
interface Expression {
  evaluate(input: any, bindings?: Record<string, any>): Promise<any>;
  evaluate(input: any, bindings: Record<string, any> | undefined, callback: (err: JsonataError, resp: any) => void): void;
  assign(name: string, value: any): void;
  registerFunction(name: string, implementation: Function, signature?: string): void;
  ast(): ExprNode;
  errors(): any;
}

// Error object for JSONata runtime errors
interface JsonataError extends Error {
  code: string;
  position: number;
  token: string;
}

// Abstract syntax tree node
interface ExprNode {
  type: string;
  value?: any;
  position?: number;
  arguments?: ExprNode[];
  name?: string;
  procedure?: ExprNode;
  steps?: ExprNode[];
  expressions?: ExprNode[];
  stages?: ExprNode[];
  lhs?: ExprNode | ExprNode[];
  rhs?: ExprNode;
}

// Environment for variable bindings
interface Environment {
  bind(name: string | symbol, value: any): void;
  lookup(name: string | symbol): any;
  readonly timestamp: Date;
  readonly async: boolean;
}

// Execution context for functions
interface Focus {
  readonly environment: Environment;
  readonly input: any;
}