@jmespath-community/jmespath 1.2.0 → 1.4.0

package/README.md

@@ -8,29 +8,91 @@ JMESPath is a query language for JSON. It will take a JSON document
 as input and transform it into another JSON document
 given a JMESPath expression.
 
-## INSTALLATION
-
-```
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [ESM (Node.js)](#esm-nodejs)
+  - [CommonJS (Node.js)](#commonjs-nodejs)
+  - [Browser (UMD)](#browser-umd)
+- [API](#api)
+  - [`search(data, expression, options)`](#searchdata-d-expression-string-options-options-t)
+  - [`searchStream(source, expression, options)`](#searchstreamsource-expression-options-asyncgenerator)
+  - [`compile(expression)`](#compileexpression-string-expressionnodetree)
+  - [`compileQuery(expression, options)`](#compilequeryexpression-string-options-options-compiledquery)
+  - [`validate(expression, options)`](#validateexpression-string-options-options-validationresult)
+- [Extensions](#extensions-to-original-spec)
+- [More Resources](#more-resources)
+- [Experimental Features](#experimental-features)
+
+## Installation
+
+```bash
 npm install @jmespath-community/jmespath
 ```
 
-## USAGE
+## Usage
 
-### `search(data: JSONValue, expression: string): JSONValue`
+### ESM (Node.js)
 
 ```javascript
 import { search } from "@jmespath-community/jmespath";
 
-search({ foo: { bar: { baz: [0, 1, 2, 3, 4] } } }, "foo.bar.baz[2]");
+const data = { foo: { bar: { baz: [0, 1, 2, 3, 4] } } };
+const result = search(data, "foo.bar.baz[2]");
 
-// OUTPUTS: 2
+console.log(result);
+// Outputs: 2
 ```
 
+### CommonJS (Node.js)
+
+```javascript
+const { search } = require("@jmespath-community/jmespath");
+
+const data = { foo: { bar: { baz: [0, 1, 2, 3, 4] } } };
+const result = search(data, "foo.bar.baz[2]");
+
+console.log(result);
+// Outputs: 2
+```
+
+### Browser (UMD)
+
+You can include the UMD build directly in your HTML file. The library will be available under the `jmespath` global variable.
+
+```html
+<script src="https://unpkg.com/@jmespath-community/jmespath/dist/index.umd.min.js"></script>
+<script>
+  const data = { foo: { bar: { baz: [0, 1, 2, 3, 4] } } };
+  const result = jmespath.search(data, "foo.bar.baz[2]");
+  console.log(result);
+  // Outputs: 2
+</script>
+```
+
+## API
+
+### `search<T = JSONValue, D = unknown>(data: D, expression: string, options?: Options): T`
+
 In the example we gave the `search` function input data of
 `{foo: {bar: {baz: [0, 1, 2, 3, 4]}}}` as well as the JMESPath
 expression `foo.bar.baz[2]`, and the `search` function evaluated
 the expression against the input data to produce the result `2`.
 
+Accepts custom TypeScript interfaces directly without casting:
+
+```typescript
+interface User {
+  name: string;
+  age: number;
+}
+
+const user: User = { name: "Alice", age: 30 };
+const name = search<string>(user, "name");
+// name is typed as string
+```
+
 The JMESPath language can do _a lot_ more than select an element
 from a list. Here are a few more examples:
 
@@ -72,6 +134,61 @@ search(JSON_DOCUMENT, "foo[?age > `30`]");
 // OUTPUTS: [ { age: 35 }, { age: 40 } ]
 ```
 
+#### Automatic Type Inference
+
+Literal path queries automatically infer property types without requiring manual type parameters or type assertions:
+
+```typescript
+const user = {
+  profile: { name: "Alice", email: "alice@example.com" },
+  tags: ["admin", "dev"],
+};
+
+const name = search(user, "profile.name"); // inferred as string
+const tag = search(user, "tags[0]");       // inferred as string
+const tags = search(user, "tags[*]");      // inferred as string[]
+```
+
+#### Runtime Security Options
+
+Pass `options` to restrict execution limits on untrusted queries:
+
+```typescript
+search(data, expression, {
+  maxDepth: 32,                            // expression and evaluation recursion limit
+  maxNodes: 128,                           // maximum AST node count
+  maxOutputSize: 1000,                     // maximum elements or characters in results
+  allowedFunctions: ['length', 'contains'], // allow-list specific built-ins
+  disallowedFunctions: ['custom_heavy'],   // deny-list specific built-ins
+  timeoutMs: 100,                          // query execution time limit in ms
+});
+```
+
+### `searchStream<T = JSONValue, D = unknown>(source: StreamSource<D>, expression: string | ExpressionNode, options?: StreamOptions): AsyncGenerator<T, void, unknown>`
+
+Evaluates a JMESPath expression incrementally over an `AsyncIterable`, `ReadableStream`, or Node.js `stream.Readable`, yielding matching results without buffering large datasets in memory:
+
+```typescript
+import jmespath from "@jmespath-community/jmespath";
+
+async function* getEvents() {
+  yield { id: 1, level: "info", message: "connected" };
+  yield { id: 2, level: "error", message: "disk full" };
+}
+
+for await (const msg of jmespath.searchStream(getEvents(), "[?level == 'error'].message")) {
+  console.log(msg); // "disk full"
+}
+```
+
+Supports automatic NDJSON / JSON lines chunk decoding (`parseJson: 'auto'`), chunk flattening, precompiled ASTs, and early termination:
+
+```typescript
+for await (const item of jmespath.searchStream(logStream, "[:10]", { limit: 10 })) {
+  console.log(item);
+}
+```
+
 ### `compile(expression: string): ExpressionNodeTree`
 
 You can precompile all your expressions ready for use later on. The `compile`
@@ -83,19 +200,48 @@ import { compile, TreeInterpreter } from "@jmespath-community/jmespath";
 
 const ast = compile("foo.bar");
 
-TreeInterpreter.search(ast, { foo: { bar: "BAZ" } });
+const result = TreeInterpreter.search(ast, { foo: { bar: "BAZ" } });
 // RETURNS: "BAZ"
 ```
 
+### `compileQuery<T = JSONValue, D = unknown>(expression: string, options?: Options): CompiledQuery<T, D>`
+
+Precompiles an expression into a reusable, callable function:
+
+```typescript
+import { compileQuery } from "@jmespath-community/jmespath";
+
+const getName = compileQuery<string, { user: { name: string } }>("user.name");
+
+const result = getName({ user: { name: "Alice" } });
+// Outputs: "Alice"
+```
+
+### `validate(expression: string, options?: Options): ValidationResult`
+
+Validates an expression without throwing exceptions, checking syntax and security options:
+
+```typescript
+import { validate } from "@jmespath-community/jmespath";
+
+const result = validate("foo.bar");
+// { valid: true, ast: { type: 'Subexpression', ... } }
+
+const invalid = validate("foo.", { maxNodes: 10 });
+// { valid: false, error: 'Syntax error: ...' }
+```
+
 ---
 
 ## EXTENSIONS TO ORIGINAL SPEC
 
-1. ### Register you own custom functions
+1. ### Register your own custom functions
 
-   #### `registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void`
+   #### Enhanced Function Registry API
 
-   Extend the list of built in JMESpath expressions with your own functions.
+   The library provides both backward-compatible and enhanced APIs for registering custom functions with improved developer experience, type safety, and flexible override behavior.
+
+   ##### Basic Usage (Backward Compatible)
 
    ```javascript
    import { search, registerFunction, TYPE_NUMBER } from "@jmespath-community/jmespath";
@@ -117,6 +263,76 @@ TreeInterpreter.search(ast, { foo: { bar: "BAZ" } });
    // OUTPUTS: 6
    ```
 
+   ##### Enhanced Registry API with Type Safety
+
+   ```typescript
+   import { register, search, TYPE_NUMBER } from "@jmespath-community/jmespath";
+
+   // TypeScript prevents registering built-in functions at compile time
+   // register('sum', myFunc, signature); // TypeScript error!
+
+   // Enhanced registration with better error handling
+   const result = register('multiply', ([a, b]) => a * b, [
+     { types: [TYPE_NUMBER] },
+     { types: [TYPE_NUMBER] }
+   ]);
+
+   if (result.success) {
+     console.log(result.message); // "Function multiply() registered successfully"
+   } else {
+     console.error(result.message); // Detailed error information
+   }
+   ```
+
+   ##### Override Existing Functions
+
+   ```javascript
+   import { registerFunction, register } from "@jmespath-community/jmespath";
+
+   // Option 1: Using registerFunction with options
+   registerFunction('myFunc', () => 'first', []);
+   registerFunction('myFunc', () => 'second', [], { override: true, warn: true });
+   // Console: "Warning: Overriding existing function: myFunc()"
+
+   // Option 2: Using enhanced register API
+   const result = register('myFunc', () => 'third', [], { override: true });
+   console.log(result.message); // "Function myFunc() overridden successfully"
+   ```
+
+   ##### Registry Management
+
+   ```javascript
+   import {
+     isRegistered,
+     getRegisteredFunctions,
+     getCustomFunctions,
+     unregisterFunction,
+     clearCustomFunctions
+   } from "@jmespath-community/jmespath";
+
+   // Check if function exists
+   console.log(isRegistered('sum')); // true (built-in)
+   console.log(isRegistered('myFunc')); // true (if registered)
+
+   // Get all registered functions
+   const allFunctions = getRegisteredFunctions();
+   console.log(allFunctions); // ['abs', 'avg', 'ceil', ..., 'myFunc']
+
+   // Get only custom functions
+   const customFunctions = getCustomFunctions();
+   console.log(customFunctions); // ['myFunc', 'divide', ...]
+
+   // Unregister custom function (built-ins cannot be unregistered)
+   const removed = unregisterFunction('myFunc');
+   console.log(removed); // true if successful
+
+   // Clear all custom functions
+   clearCustomFunctions();
+   console.log(getCustomFunctions()); // []
+   ```
+
+   ##### Optional Arguments
+
    Optional arguments are supported by setting `{..., optional: true}` in argument signatures
 
    ```javascript
@@ -124,7 +340,7 @@ TreeInterpreter.search(ast, { foo: { bar: "BAZ" } });
      "divide",
      (resolvedArgs) => {
        const [dividend, divisor] = resolvedArgs;
-       return dividend / divisor ?? 1; //OPTIONAL DIVISOR THAT DEFAULTS TO 1
+       return dividend / (divisor ?? 1); //OPTIONAL DIVISOR THAT DEFAULTS TO 1
      },
      [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER], optional: true }], //SIGNATURE
    );