json-web-streams 1.0.0 → 1.1.0

package/README.md

@@ -68,12 +68,12 @@ await response.body
 
 ```ts
 const jsonParseStream = new JSONParseStream(
-    jsonPaths: (JSONPath | { path: JSONPath; schema: StandardSchemaV1 })[],
+    jsonPaths: (JSONPath | { path: JSONPath; key?: Key; schema?: StandardSchemaV1 })[],
     options?: { multi?: boolean },
 );
 ```
 
-### `jsonPaths: (JSONPath | { path: JSONPath; schema: StandardSchemaV1 })[]`
+### `jsonPaths: (JSONPath | { path: JSONPath; key?: Key; schema?: StandardSchemaV1 })[]`
 
 The first argument to `JSONParseStream` is an array specifying what objects to emit from the stream. The `JSONPath` type is a string containing a JSONPath query. JSONPath is a query language for JSON to let you pick out specific values from a JSON object.
 
@@ -102,7 +102,15 @@ but you can have as many as you want:
 >
 > In total this query means "emit every value in the array/object in the `foo` property of the overall JSON object". So for this JSON `{ foo: ["A", "B", "C"] }` it would emit the three values `"A"`, `"B"`, and `"C"`.
 
-The values of the `jsonPaths` array can either be `JSONPath` strings, or objects like `{ path: JSONPath; schema: StandardSchemaV1 }` where `schema` is a schema validator from any library supporting the [Standard Schema specification](https://github.com/standard-schema/standard-schema) such as Zod, Valibot, or ArkType. When you supply a schema like this, each value will be validated before it is emitted by the stream, and emitted values will have correct TypeScript types rather than being `unknown`. For more details, see the [Schema validation and types for `JSONParseStream` output](#schema-validation-and-types-for-jsonparsestream-output) section below.
+The values of the `jsonPaths` array can either be `JSONPath` strings, or objects like `{ path: JSONPath; key?: Key; schema?: StandardSchemaV1 }` to specify the additional optional `key` and `schema` properties.
+
+#### `key?: Key`
+
+If `key` is defined, it will be propagated through to the `key` property on output objects. So it can be any type, but typically is probably something like a number, string, or Symbol that you want to use to discriminate between types of outputs when you have multiple entries in the `jsonPaths` array. When `key` is not defined, then the value of `path` is used instead. See the [`JSONParseStream` output](#jsonparsestream-output) section below for examples.
+
+#### `schema?: StandardSchemaV1`
+
+`schema` is a schema validator from any library supporting the [Standard Schema specification](https://github.com/standard-schema/standard-schema) such as Zod, Valibot, or ArkType. When you supply a schema like this, each value will be validated before it is emitted by the stream, and emitted values will have correct TypeScript types rather than being `unknown`. For more details, see the [Schema validation and types for `JSONParseStream` output](#schema-validation-and-types-for-jsonparsestream-output) section below.
 
 ### `options?: { multi?: boolean }`
 
@@ -137,16 +145,16 @@ Output from `JSONParseStream` has this format:
 ```ts
 type JSONParseStreamOutput<T = unknown> = {
 	value: T;
-	path: JSONPath;
+	key: Key;
 	wildcardKeys?: string[];
 };
 ```
 
 `value` is the value selected by one of your JSONPath queries.
 
-`path` is the JSONPath query (from the `jsonPaths` parameter of `JSONParseStream`) that matched `value`.
+`key` is the JSONPath query (from the `jsonPaths` parameter of `JSONParseStream`) that matched `value`, or the value from the `key` property inside `jsonPaths` if that was supplied.
 
-If you only have one JSONPath query, you can ignore `path`. But if you have more than one, `path` may be helpful when processing stream output to distinguish between different types of values. For example:
+If you only have one JSONPath query, you can ignore `key`. But if you have more than one, `key` may be helpful when processing stream output to distinguish between different types of values. For example:
 
 <!-- prettier-ignore -->
 ```ts
@@ -160,7 +168,31 @@ await new ReadableStream({
 	.pipeTo(
 		new WritableStream({
 			write(record) {
-				if (record.path === "$.bar[*]") {
+				if (record.key === "$.bar[*]") {
+					// Do something with the values from bar
+				} else {
+					// Do something with the values from foo
+				}
+			},
+		}),
+	);
+```
+
+Or with a manually defined key:
+
+<!-- prettier-ignore -->
+```ts
+await new ReadableStream({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(new JSONParseStream([{ key: "bar", path: "$.bar[*]" }, "$.foo[*]"]))
+	.pipeTo(
+		new WritableStream({
+			write(record) {
+				if (record.key === "bar") {
 					// Do something with the values from bar
 				} else {
 					// Do something with the values from foo
@@ -189,8 +221,8 @@ await new ReadableStream({
 		}),
 	);
 // Output:
-// { path: "$[*]", value: [1, 2], wildcardKeys: ["foo"] },
-// { path: "$[*]", value: ["a", "b", "c"], wildcardKeys: ["bar"] },
+// { key: "$[*]", value: [1, 2], wildcardKeys: ["foo"] },
+// { key: "$[*]", value: ["a", "b", "c"], wildcardKeys: ["bar"] },
 ```
 
 The purpose of `wildcardKeys` is to allow you to easily distinguish different types of objects. `wildcardKeys` has one entry for each wildcard object in your JSONPath query.
@@ -225,7 +257,7 @@ await new ReadableStream({
 	.pipeTo(
 		new WritableStream({
 			write(record) {
-				if (record.path === "$.foo[*]") {
+				if (record.key === "$.foo[*]") {
 					// Type of record.value is number
 				} else {
 					// Type of record.value is string
@@ -235,11 +267,42 @@ await new ReadableStream({
 	);
 ```
 
-> [!TIP]
-> If you only want to validate some values, you can mix `{ path: JSONPath; schema: StandardSchemaV1 }` and `JSONPath` in the `jsonPaths` array.
-
 For JSONPath queries with no schema, emitted values will have the `unknown` type.
 
+The type of the `key` property will be either the string literal `path` from the input paramter (such as `"$.foo[*]`) or whatever you put in the `key` property of the input. For example:
+
+<!-- prettier-ignore -->
+```ts
+import * as z from "zod";
+
+await new ReadableStream({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(
+		new JSONParseStream([
+			{ key: "foo", path: "$.foo[*]", schema: z.number() },
+			{ key: "bar", path: "$.bar[*]", schema: z.string() },
+		]),
+	)
+	.pipeTo(
+		new WritableStream({
+			write(record) {
+				if (record.key === "foo") {
+					// Type of record.value is number
+				} else {
+					// Type of record.value is string
+				}
+			},
+		}),
+	);
+```
+
+> [!TIP]
+> If you only want to validate values or override keys for some queries, you can mix `{ path: JSONPath; key?: Key; schema?: StandardSchemaV1 }` and `JSONPath` in the `jsonPaths` array.
+
 ## JSONPath
 
 json-web-streams supports a subset of JSONPath. Currently the supported components are:
@@ -285,7 +348,7 @@ Let's say you have this JSON:
 { "foo": [1, 2], "bar": ["a", "b", "c"] }
 ```
 
-You want to get all the values in `foo` and all the values in `bar`. You could define them as two separate JSONPath queries and then distinguish the output with `.path`:
+You want to get all the values in `foo` and all the values in `bar`. You could define them as two separate JSONPath queries and then distinguish the output with `.key`:
 
 <!-- prettier-ignore -->
 ```ts
@@ -301,7 +364,7 @@ await new ReadableStream({
 	.pipeTo(
 		new WritableStream({
 			write(record) {
-				if (record.path === "$.foo[*]") {
+				if (record.key === "$.foo[*]") {
 					// 1, 2
 				} else {
 					// a, b, c
@@ -362,7 +425,7 @@ await new ReadableStream({
 	.pipeTo(
 		new WritableStream({
 			write(record) {
-				if (record.path === "$.foo[*]") {
+				if (record.key === "$.foo[*]") {
 					// 1, 2
 				} else {
 					// a, b, c

package/dist/JSONParseStream.d.ts

@@ -4,20 +4,25 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/JSONParseStream.d.ts
 type JSONParseStreamOutput<T> = T extends {
+  key?: infer K | undefined;
   path: infer P extends JSONPath;
-  schema: infer S extends StandardSchemaV1;
+  schema?: infer S extends StandardSchemaV1 | undefined;
 } ? {
-  path: P;
-  value: StandardSchemaV1.InferOutput<S>;
+  value: S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
   wildcardKeys?: string[];
-} : T extends JSONPath ? {
-  path: T;
+} & (undefined extends K ? {
+  key: P;
+} : {
+  key: K;
+}) : T extends JSONPath ? {
+  key: T;
   value: unknown;
   wildcardKeys?: string[];
 } : never;
-declare class JSONParseStream<T extends readonly (JSONPath | {
+declare class JSONParseStream<const Key extends unknown, T extends readonly (JSONPath | {
+  key?: Key;
   path: JSONPath;
-  schema: StandardSchemaV1;
+  schema?: StandardSchemaV1;
 })[]> extends TransformStream<string, JSONParseStreamOutput<T[number]>> {
   _parser: JSONParseStreamRaw;
   constructor(jsonPaths: T, options?: {

package/dist/JSONParseStream.js

@@ -2,33 +2,27 @@ import { JSONParseStreamRaw } from "./JSONParseStreamRaw.js";
 import { jsonPathToPathArray } from "./jsonPathToPathArray.js";
 
 //#region src/JSONParseStream.ts
-const stackToPathComponent = (stackComponent) => {
-	if (stackComponent.mode === "OBJECT" && stackComponent.key !== void 0) return {
-		type: "key",
-		value: stackComponent.key
-	};
-	if (stackComponent.mode === "ARRAY") return { type: "wildcard" };
-	throw new Error(`Unexpected mode "${stackComponent.mode}"`);
-};
 const isEqual = (x, y) => {
 	if (!y) return false;
-	if (x.type === y?.type) {
-		if (x.type === "wildcard") return true;
-		if (x.value === y.value) return true;
-		return false;
-	}
-	return x.type === "wildcard";
+	if (x.type === "wildcard") {
+		if (y.mode === "ARRAY") return true;
+		else if (y.mode === "OBJECT") return true;
+	} else if (y.mode === "OBJECT" && x.value === y.key) return true;
+	return false;
 };
 var JSONParseStream = class extends TransformStream {
 	_parser;
 	constructor(jsonPaths, options) {
 		let parser;
-		const multi = options?.multi ?? false;
+		let minPathArrayLength = Infinity;
+		let maxPathArrayLength = -Infinity;
 		const jsonPathInfos = jsonPaths.map((row) => {
+			let key;
 			let path;
 			let schema;
 			if (typeof row === "string") path = row;
 			else {
+				key = row.key;
 				path = row.path;
 				schema = row.schema;
 			}
@@ -38,64 +32,96 @@ var JSONParseStream = class extends TransformStream {
 				if (wildcardIndexes === void 0) wildcardIndexes = [];
 				wildcardIndexes.push(i);
 			}
+			const matches = pathArray.length === 0 ? "yes" : "unknown";
+			if (pathArray.length > maxPathArrayLength) maxPathArrayLength = pathArray.length;
+			if (pathArray.length < minPathArrayLength) minPathArrayLength = pathArray.length;
 			return {
+				key,
+				matches,
 				path,
 				pathArray,
-				schema,
+				validate: schema?.["~standard"].validate,
 				wildcardIndexes
 			};
 		});
+		const jsonPathInfosThatMatch = new Set(jsonPathInfos.filter((info) => info.matches === "yes"));
+		const updateMatches = (type) => {
+			for (const info of jsonPathInfos) {
+				const pathArray = info.pathArray;
+				if ((info.matches === "unknown" && type === "push" || info.matches !== "unknown" && info.matches !== "noBeforeEnd" && type === "key") && parser.stack.length === pathArray.length) {
+					let pathMatches = "yes";
+					for (let j = 0; j < pathArray.length; j++) {
+						let stackComponent = parser.stack[j + 1];
+						if (!stackComponent) {
+							if (type === "key") stackComponent = parser;
+							else if (pathArray[j].type === "wildcard") {
+								pathMatches = "yes";
+								break;
+							}
+						}
+						if (!isEqual(pathArray[j], stackComponent)) {
+							if (j < pathArray.length - 1) pathMatches = "noBeforeEnd";
+							else pathMatches = "noAtEnd";
+							break;
+						}
+					}
+					info.matches = pathMatches;
+					if (pathMatches === "yes") jsonPathInfosThatMatch.add(info);
+					else jsonPathInfosThatMatch.delete(info);
+				}
+			}
+		};
 		super({
 			start(controller) {
 				parser = new JSONParseStreamRaw({
-					multi,
+					multi: options?.multi,
+					onKey: (stackLength) => {
+						if (stackLength <= maxPathArrayLength && stackLength >= minPathArrayLength) updateMatches("key");
+					},
+					onPop: (stackLength) => {
+						if (stackLength < maxPathArrayLength && stackLength >= minPathArrayLength - 1) {
+							for (const info of jsonPathInfos) if (info.matches !== "unknown" && stackLength < info.pathArray.length) {
+								info.matches = "unknown";
+								jsonPathInfosThatMatch.delete(info);
+							}
+						}
+					},
+					onPush: (stackLength) => {
+						if (stackLength <= maxPathArrayLength && stackLength >= minPathArrayLength) updateMatches("push");
+					},
 					onValue: (value) => {
-						const { key: parserKey, mode: parserMode, stack: parserStack, value: parserValue } = parser;
-						const stackLength = parserStack.length;
-						const stackPathArray = new Array(stackLength);
-						for (let i = 1; i < stackLength; i++) stackPathArray[i - 1] = stackToPathComponent(parserStack[i]);
-						if (parserStack.length > 0) stackPathArray[stackLength - 1] = stackToPathComponent({
-							value: parserValue,
-							key: parserKey,
-							mode: parserMode
-						});
 						let keep = false;
-						for (const { path, pathArray, schema, wildcardIndexes } of jsonPathInfos) {
-							if (stackPathArray.length < pathArray.length) continue;
-							if (pathArray.every((x, j) => isEqual(x, stackPathArray[j]))) if (stackPathArray.length === pathArray.length) {
-								let valueToEmit;
-								if (schema) {
-									const result = schema["~standard"].validate(value);
-									if (result instanceof Promise) throw new TypeError("Schema validation must be synchronous");
-									if (result.issues) throw new Error(JSON.stringify(result.issues, null, 2));
-									valueToEmit = result.value;
-								} else valueToEmit = value;
-								let wildcardKeys;
-								if (wildcardIndexes) for (const index of wildcardIndexes) {
-									const pathComponent = stackPathArray[index];
-									if (pathComponent?.type === "key") {
-										if (!wildcardKeys) wildcardKeys = [];
-										wildcardKeys.push(pathComponent.value);
-									}
+						for (const { key, path, pathArray, validate, wildcardIndexes } of jsonPathInfosThatMatch) if (parser.stack.length === pathArray.length) {
+							let valueToEmit;
+							if (validate) {
+								const result = validate(value);
+								if (result instanceof Promise) throw new TypeError("Schema validation must be synchronous");
+								if (result.issues) throw new Error(JSON.stringify(result.issues, null, 2));
+								valueToEmit = result.value;
+							} else valueToEmit = value;
+							let wildcardKeys;
+							if (wildcardIndexes) for (const index of wildcardIndexes) {
+								const stackComponent = parser.stack[index + 1] ?? parser;
+								if (stackComponent.mode === "OBJECT" && stackComponent.key !== void 0) {
+									if (!wildcardKeys) wildcardKeys = [];
+									wildcardKeys.push(stackComponent.key);
 								}
-								if (wildcardKeys) controller.enqueue({
-									path,
-									value: valueToEmit,
-									wildcardKeys
-								});
-								else controller.enqueue({
-									path,
-									value: valueToEmit
-								});
-							} else keep = true;
-							else {
-								const type = typeof value;
-								if (type === "string" || type === "number" || type === "boolean" || value === null) keep = true;
 							}
-						}
-						if (!keep) {
-							for (const row of parserStack) row.value = void 0;
-							if (typeof parserValue === "object" && parserValue !== null && parserKey !== void 0) parserValue[parserKey] = void 0;
+							if (wildcardKeys) controller.enqueue({
+								key: key ?? path,
+								value: valueToEmit,
+								wildcardKeys
+							});
+							else controller.enqueue({
+								key: key ?? path,
+								value: valueToEmit
+							});
+						} else keep = true;
+						if (keep) return;
+						const type = typeof value;
+						if (!(type === "string" || type === "number" || type === "boolean" || value === null)) {
+							for (const row of parser.stack) row.value = void 0;
+							if (typeof parser.value === "object" && parser.value !== null && parser.key !== void 0) parser.value[parser.key] = void 0;
 						}
 					}
 				});

package/dist/JSONParseStreamRaw.d.ts

@@ -10,6 +10,7 @@ type Stack = {
   value: Value | undefined;
   mode: Mode | undefined;
 }[];
+type OnPopPush = (stackLength: number) => void;
 type OnValue = (value: Value) => void;
 declare class JSONParseStreamRaw {
   tokenizerState: TokenizerState;
@@ -20,17 +21,26 @@ declare class JSONParseStreamRaw {
   key: Key | undefined;
   value: Value;
   position: number;
+  onKey: OnPopPush | undefined;
+  onPop: OnPopPush | undefined;
+  onPush: OnPopPush | undefined;
   onValue: OnValue;
   unicode: string | undefined;
   highSurrogate: number | undefined;
   seenRootObject: boolean;
-  multi: boolean;
+  multi: boolean | undefined;
   multiIndex: number;
   constructor({
     multi,
+    onKey,
+    onPop,
+    onPush,
     onValue
   }: {
-    multi: boolean;
+    multi?: boolean;
+    onKey?: OnPopPush;
+    onPop?: OnPopPush;
+    onPush?: OnPopPush;
     onValue: OnValue;
   });
   charError(char: string, i: number): void;
@@ -38,6 +48,7 @@ declare class JSONParseStreamRaw {
   write(text: string): void;
   push(): void;
   pop(): void;
+  setKey(key: number | string | undefined): void;
   emit(value: Value): void;
   onToken(token: Token, value: Value, i: number): void;
   numberReviver(text: string, i: number): void;

package/dist/JSONParseStreamRaw.js

@@ -14,15 +14,21 @@ var JSONParseStreamRaw = class {
 	key;
 	value;
 	position = 0;
+	onKey;
+	onPop;
+	onPush;
 	onValue;
 	unicode;
 	highSurrogate;
 	seenRootObject = false;
 	multi;
 	multiIndex = 0;
-	constructor({ multi, onValue }) {
-		this.onValue = onValue;
+	constructor({ multi, onKey, onPop, onPush, onValue }) {
 		this.multi = multi;
+		this.onKey = onKey;
+		this.onPop = onPop;
+		this.onPush = onPush;
+		this.onValue = onValue;
 	}
 	charError(char, i) {
 		throw new Error(`Unexpected ${JSON.stringify(char)} at position ${this.position + i} in state ${this.tokenizerState}`);
@@ -181,6 +187,7 @@ var JSONParseStreamRaw = class {
 			key: this.key,
 			mode: this.mode
 		});
+		this.onPush?.(this.stack.length);
 	}
 	pop() {
 		const value = this.value;
@@ -189,8 +196,13 @@ var JSONParseStreamRaw = class {
 		this.key = parent.key;
 		this.mode = parent.mode;
 		this.emit(value);
+		this.onPop?.(this.stack.length);
 		if (!this.mode) this.state = "VALUE";
 	}
+	setKey(key) {
+		this.key = key;
+		if (this.onKey && typeof key === "string" && this.mode === "OBJECT") this.onKey(this.stack.length);
+	}
 	emit(value) {
 		if (this.mode) this.state = "COMMA";
 		if (value === void 0) return;
@@ -207,14 +219,14 @@ var JSONParseStreamRaw = class {
 			this.push();
 			if (this.value) this.value = this.value[this.key] = {};
 			else this.value = {};
-			this.key = void 0;
+			this.setKey(void 0);
 			this.state = "KEY";
 			this.mode = "OBJECT";
 		} else if (token === "LEFT_BRACKET") {
 			this.push();
 			if (this.value) this.value = this.value[this.key] = [];
 			else this.value = [];
-			this.key = 0;
+			this.setKey(0);
 			this.mode = "ARRAY";
 			this.state = "VALUE";
 		} else if (token === "RIGHT_BRACE") if (this.mode === "OBJECT" && this.state !== "VALUE_AFTER_COMMA") this.pop();
@@ -223,7 +235,7 @@ var JSONParseStreamRaw = class {
 		else return this.parseError(token, value, i);
 		else return this.parseError(token, value, i);
 		else if (this.state === "KEY" || this.state === "KEY_AFTER_COMMA") if (token === "STRING") {
-			this.key = value;
+			this.setKey(value);
 			this.state = "COLON";
 		} else if (token === "RIGHT_BRACE" && this.state !== "KEY_AFTER_COMMA") this.pop();
 		else return this.parseError(token, value, i);

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import { JSONParseStreamRaw } from "./JSONParseStreamRaw.js";
 import { JSONPath } from "./jsonPathToPathArray.js";
 import { JSONParseStream } from "./JSONParseStream.js";
-export { JSONParseStream, JSONParseStreamRaw, type JSONPath };
+export { JSONParseStream, type JSONPath };

package/dist/index.js

@@ -1,4 +1,3 @@
-import { JSONParseStreamRaw } from "./JSONParseStreamRaw.js";
 import { JSONParseStream } from "./JSONParseStream.js";
 
-export { JSONParseStream, JSONParseStreamRaw };
+export { JSONParseStream };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "json-web-streams",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Streaming JSON parser built on top of the Web Streams API, so it works in web browsers, Node.js, and many other environments",
 	"keywords": [
 		"web streams",
@@ -21,6 +21,7 @@
 		"dist"
 	],
 	"scripts": {
+		"bench": "vitest bench",
 		"build": "tsdown --unbundle",
 		"format": "prettier --write .",
 		"lint": "npm-run-all --parallel lint:oxlint lint:tsc",
@@ -39,15 +40,15 @@
 	},
 	"devDependencies": {
 		"@ianvs/prettier-plugin-sort-imports": "^4.7.0",
-		"@types/node": "^24.8.1",
+		"@types/node": "^24.9.1",
 		"husky": "^9.1.7",
-		"lint-staged": "^16.2.4",
+		"lint-staged": "^16.2.5",
 		"npm-run-all2": "^8.0.4",
 		"oxlint": "^1.23.0",
 		"oxlint-tsgolint": "^0.2.0",
 		"prettier": "^3.6.2",
 		"prettier-plugin-packagejson": "^2.5.19",
-		"tsdown": "^0.15.7",
+		"tsdown": "^0.15.9",
 		"typescript": "^5.9.3",
 		"vitest": "^3.2.4",
 		"zod": "^4.1.12"