@jmespath-community/jmespath 1.3.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,10 +200,37 @@ 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