json-web-streams 1.0.0 → 1.2.0

package/README.md

@@ -35,16 +35,14 @@ import { JSONParseStream } from "json-web-streams";
 
 // data.json contains: [{ "x": 1 }, { "x": 2 }, { "x": 3 }]
 const response = await fetch("https://example.com/data.json");
-await response.body
+
+const stream = response.body
 	.pipeThrough(new TextDecoderStream())
-	.pipeThrough(new JSONParseStream(["$[*]"]))
-	.pipeTo(
-		new WritableStream({
-			write({ value }) {
-				console.log(value);
-			},
-		}),
-	);
+	.pipeThrough(new JSONParseStream(["$[*]"]));
+
+for await (const { value } of stream) {
+	console.log(value);
+}
 
 // Output:
 // {"x": 1}
@@ -52,28 +50,16 @@ await response.body
 // {"x": 3}
 ```
 
-> [!TIP]
-> If you don't have to support Safari, [most other environments](https://caniuse.com/mdn-api_readablestream_--asynciterator) let you use a nicer syntax for consuming stream output as an async iterator:
->
-> ```ts
-> const stream = response.body
-> 	.pipeThrough(new TextDecoderStream())
-> 	.pipeThrough(new JSONParseStream(["$[*]"]));
-> for await (const { value } of stream) {
-> 	console.log(value);
-> }
-> ```
-
 ## API
 
 ```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 +88,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,60 +131,76 @@ 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
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
 		},
 	})
-	.pipeThrough(new JSONParseStream(["$.bar[*]", "$.foo[*]"]))
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				if (record.path === "$.bar[*]") {
-					// Do something with the values from bar
-				} else {
-					// Do something with the values from foo
-				}
-			},
-		}),
-	);
+	.pipeThrough(new JSONParseStream(["$.bar[*]", "$.foo[*]"]));
+
+for await (const record of stream) {
+	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
+const stream = new ReadableStream({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(new JSONParseStream([{ key: "bar", path: "$.bar[*]" }, "$.foo[*]"]));
+
+for await (const record of stream) {
+	if (record.key === "bar") {
+		// Do something with the values from bar
+	} else {
+		// Do something with the values from foo
+	}
+}
 ```
 
 `wildcardKeys` is defined when you have a wildcard in an object (not an array) somewhere in your JSONPath. For example:
 
 <!-- prettier-ignore -->
 ```ts
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
 		},
 	})
-	.pipeThrough(new JSONParseStream(["$[*]"]))
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				console.log(record);
-			},
-		}),
-	);
+	.pipeThrough(new JSONParseStream(["$[*]"]));
+
+for await (const record of stream) {
+	console.log(record);
+}
+
 // 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.
@@ -198,7 +208,7 @@ The purpose of `wildcardKeys` is to allow you to easily distinguish different ty
 > [!WARNING]
 > It is possible to have two JSONPath queries that output overlapping objects, like if your data is `{ "foo": [1, 2] }` and you query for both `$` and `$.foo`. This will emit two objects: `{ foo: [1, 2] }` and `[1, 2]`. Due to how json-web-streams works internally, both of those objects share the same array instance, meaning that if the array in one is mutated it will affect the other.
 >
-> Some schema validation libraries do a deep clone of objects they validate. In that case, you won't have this issue. Otherwise, in the rare case that you query for overlapping objects, you will have to handle this problem, such as by deep cloning one of the objects.
+> Some schema validation libraries do a deep clone of objects they validate. In that case, you won't have this issue.
 
 #### Schema validation and types for `JSONParseStream` output
 
@@ -210,7 +220,7 @@ To use schema validation for a JSONPath query, then pass an object `{ path: JSON
 ```ts
 import * as z from "zod";
 
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
@@ -221,32 +231,57 @@ await new ReadableStream({
 			{ path: "$.foo[*]", schema: z.number() },
 			{ path: "$.bar[*]", schema: z.string() },
 		]),
-	)
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				if (record.path === "$.foo[*]") {
-					// Type of record.value is number
-				} else {
-					// Type of record.value is string
-				}
-			},
-		}),
 	);
-```
 
-> [!TIP]
-> If you only want to validate some values, you can mix `{ path: JSONPath; schema: StandardSchemaV1 }` and `JSONPath` in the `jsonPaths` array.
+for await (const record of stream) {
+	if (record.key === "$.foo[*]") {
+		// Type of record.value is `number`
+	} else {
+		// Type of record.value is `string`
+	}
+}
+```
 
 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, so you can use it to discriminate between object types in the output. For example:
+
+<!-- prettier-ignore -->
+```ts
+import * as z from "zod";
+
+const stream = 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() },
+		]),
+	);
+
+for await (const record of stream) {
+	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:
 
 - **The root node**, represented by the symbol `$` which must be the first character of any JSONPath query.
 
-- **Name selectors** which are like accessing a property in a JS object. For instance if you have an object like `{ "foo": { bar: 5 } }`, then `$.foo.bar` refers to the value `5`. You can also write this in the more verbose bracket notation like `$["foo"]["bar"]` or `$["foo", "bar"]`, which is useful if your key names include characters that need escaping. You can also mix them like `$.foo["bar"]` or use single quotes like `$['foo']['bar']` - all of these JSONPath queries have the same meaning.
+- **Name selectors** which are like accessing a property in a JS object. For instance if you have an object like `{ "foo": { bar: 5 } }`, then `$.foo.bar` refers to the value `5`. You can also write this in the more verbose bracket notation like `$["foo"]["bar"]`, which is useful if your key names include characters that need escaping. You can also mix them like `$.foo["bar"]` or use single quotes like `$['foo']['bar']` - all of these JSONPath queries have the same meaning.
 
 - **Wildcard selectors** which select every value in an array or object. With this JSON `{ "foo": { "a": 1, "b": 2, "c": 3 } }`, the JSONPath query `$.foo[*]` would emit the three individual numbers `1`, `2`, and `3`. If the inner object was changed to an array like `{ "foo": [1, 2, 3] }`, the same JSONPath query would emit the same values.
 
@@ -264,7 +299,7 @@ Or if the array is at the root if the object like this data:
 [{ "x": 1 }, { "x": 2 }, { "x": 3 }]
 ```
 
-then you'd write something like `$[*]` to emit each object (`{ x: 1}`, `{x: 2}`, `{x: 3}`), or `$[*].key` to emit just the numbers (`1`, `2`, `3`).
+then you'd write something like `$[*]` to emit each object (`{ x: 1}`, `{x: 2}`, `{x: 3}`), or `$[*].x` to emit just the numbers (`1`, `2`, `3`).
 
 To emit the whole object at once (okay in that case you wouldn't use this library, but maybe just for testing, or for `multi` mode) you just use `$`.
 
@@ -285,11 +320,11 @@ 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
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
@@ -297,25 +332,22 @@ await new ReadableStream({
 	})
 	.pipeThrough(
 		new JSONParseStream(["$.foo[*]", "$.bar[*]"]),
-	)
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				if (record.path === "$.foo[*]") {
-					// 1, 2
-				} else {
-					// a, b, c
-				}
-			},
-		}),
 	);
+
+for await (const record of stream) {
+	if (record.key === "$.foo[*]") {
+		// 1, 2
+	} else {
+		// a, b, c
+	}
+}
 ```
 
 Or you could use one JSONPath query with a wildcard, and then use `.wildcardKeys` to distinguish the objects:
 
 <!-- prettier-ignore -->
 ```ts
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
@@ -323,18 +355,15 @@ await new ReadableStream({
 	})
 	.pipeThrough(
 		new JSONParseStream(["$[*][*]"]),
-	)
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				if (record.wildcardKeys[0] === "foo") {
-					// 1, 2
-				} else {
-					// a, b, c
-				}
-			},
-		}),
 	);
+
+for await (const record of stream) {
+	if (record.wildcardKeys[0] === "foo") {
+		// 1, 2
+	} else {
+		// a, b, c
+	}
+}
 ```
 
 Using multiple JSONPath queries is a little more explicit, but using wildcard keys is more concise, especially if you had more than just two types of objects. And instead of known keys like `foo` and `bar` your JSON had some unknown keys, then using a wildcard would be your only option.
@@ -347,7 +376,7 @@ In this example, Zod schemas enforce that `record.value` is either a `string` or
 ```ts
 import * as z from "zod";
 
-await new ReadableStream({
+const stream = new ReadableStream({
 		start(controller) {
 			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
 			controller.close();
@@ -358,16 +387,13 @@ await new ReadableStream({
 			{ path: "$.foo[*]", schema: z.number() },
 			{ path: "$.bar[*]", schema: z.string() },
 		]),
-	)
-	.pipeTo(
-		new WritableStream({
-			write(record) {
-				if (record.path === "$.foo[*]") {
-					// 1, 2
-				} else {
-					// a, b, c
-				}
-			},
-		}),
 	);
+
+for await (const record of stream) {
+	if (record.key === "$.foo[*]") {
+		// Type of record.value is `number` rather than `unknown`
+	} else {
+		// Type of record.value is `string` rather than `unknown`
+	}
+}
 ```

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,21 @@ 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") return y.mode === "ARRAY" || y.mode === "OBJECT";
+	return y.mode === "OBJECT" && x.value === y.key;
 };
 var JSONParseStream = class extends TransformStream {
 	_parser;
 	constructor(jsonPaths, options) {
 		let parser;
-		const multi = options?.multi ?? false;
 		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;
 			}
@@ -39,63 +27,71 @@ var JSONParseStream = class extends TransformStream {
 				wildcardIndexes.push(i);
 			}
 			return {
+				key,
 				path,
 				pathArray,
-				schema,
+				validate: schema?.["~standard"].validate,
 				wildcardIndexes
 			};
 		});
+		const makeLevel = (jsonPathInfos$1, depth, matchesAbove) => {
+			return {
+				jsonPathInfos: jsonPathInfos$1,
+				matchesHere: jsonPathInfos$1.some((info) => info.pathArray.length === depth),
+				matchesAbove,
+				matchesBelow: jsonPathInfos$1.some((info) => info.pathArray.length > depth)
+			};
+		};
+		const levels = [makeLevel(jsonPathInfos, 0, false)];
+		const updateLevel = (depth) => {
+			const parent = levels[depth - 1];
+			levels[depth] = makeLevel(parent.jsonPathInfos.filter((info) => info.pathArray.length >= depth && isEqual(info.pathArray[depth - 1], parser)), depth, parent.matchesAbove || parent.matchesHere);
+		};
 		super({
 			start(controller) {
 				parser = new JSONParseStreamRaw({
-					multi,
+					multi: options?.multi,
+					parseWholeValue: () => !levels[parser.stack.length].matchesBelow,
+					onKey: updateLevel,
+					onPush: updateLevel,
+					onPop: (depth) => {
+						levels.length = depth + 1;
+					},
 					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);
-									}
+						const depth = parser.stack.length;
+						const level = levels[depth];
+						if (level.matchesHere) for (const { key, path, pathArray, validate, wildcardIndexes } of level.jsonPathInfos) {
+							if (pathArray.length !== depth) continue;
+							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 (wildcardKeys) controller.enqueue({
+								key: key ?? path,
+								value: valueToEmit,
+								wildcardKeys
+							});
+							else controller.enqueue({
+								key: key ?? path,
+								value: valueToEmit
+							});
 						}
-						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 (level.matchesAbove) 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;
 						}
 					}
 				});
@@ -103,9 +99,8 @@ var JSONParseStream = class extends TransformStream {
 			transform(chunk) {
 				parser.write(chunk);
 			},
-			flush(controller) {
+			flush() {
 				parser.checkEnd();
-				controller.terminate();
 			}
 		});
 		this._parser = parser;

package/dist/JSONParseStreamRaw.d.ts

@@ -1,7 +1,7 @@
 //#region src/JSONParseStreamRaw.d.ts
 type Token = "LEFT_BRACE" | "RIGHT_BRACE" | "LEFT_BRACKET" | "RIGHT_BRACKET" | "COLON" | "COMMA" | "TRUE" | "FALSE" | "NULL" | "STRING" | "NUMBER";
 type ParserState = "VALUE" | "KEY" | "VALUE_AFTER_COMMA" | "KEY_AFTER_COMMA";
-type TokenizerState = "START" | "TRUE1" | "TRUE2" | "TRUE3" | "FALSE1" | "FALSE2" | "FALSE3" | "FALSE4" | "NULL1" | "NULL2" | "NULL3" | "NUMBER-" | "NUMBER0" | "NUMBER" | "STRING1" | "STRING2" | "STRING3" | "STRING4" | "STRING5" | "STRING6";
+type TokenizerState = "START" | "TRUE1" | "TRUE2" | "TRUE3" | "FALSE1" | "FALSE2" | "FALSE3" | "FALSE4" | "NULL1" | "NULL2" | "NULL3" | "NUMBER-" | "NUMBER0" | "NUMBER" | "NUMBER_DOT" | "NUMBER_FRACTION" | "NUMBER_E" | "NUMBER_E_SIGN" | "NUMBER_EXPONENT" | "STRING1" | "STRING2" | "STRING3" | "STRING4" | "STRING5" | "STRING6";
 type Mode = "OBJECT" | "ARRAY";
 type Key = string | number;
 type Value = any;
@@ -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,27 +21,50 @@ 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;
+  parseWholeValue: (() => boolean) | undefined;
+  captureDisabled: boolean;
+  capturePieces: string[] | undefined;
+  captureStart: number;
+  captureDepth: number;
+  captureInString: boolean;
+  captureEscaped: boolean;
   constructor({
     multi,
-    onValue
+    onKey,
+    onPop,
+    onPush,
+    onValue,
+    parseWholeValue
   }: {
-    multi: boolean;
+    multi?: boolean;
+    onKey?: OnPopPush;
+    onPop?: OnPopPush;
+    onPush?: OnPopPush;
     onValue: OnValue;
+    parseWholeValue?: () => boolean;
   });
   charError(char: string, i: number): void;
   parseError(token: Token, value: Value, i: number): void;
+  shouldCapture(): boolean;
+  startCapture(text: string, i: number): number;
+  scanCapture(text: string, start: number): number;
+  endCapture(json: string): void;
+  parseCaptureStrict(json: string): void;
   write(text: string): void;
-  push(): void;
+  push(mode: Mode, value: object): void;
   pop(): void;
+  setKey(key: string): void;
   emit(value: Value): void;
   onToken(token: Token, value: Value, i: number): void;
-  numberReviver(text: string, i: number): void;
+  endNumber(i: number): void;
   checkEnd(): void;
 }
 //#endregion

package/dist/JSONParseStreamRaw.js

@@ -1,10 +1,5 @@
 //#region src/JSONParseStreamRaw.ts
-const WHITESPACE = new Set([
-	" ",
-	"	",
-	"\n",
-	"\r"
-]);
+const isWhitespace = (n) => n === " " || n === "\n" || n === "\r" || n === "	";
 var JSONParseStreamRaw = class {
 	tokenizerState = "START";
 	state = "VALUE";
@@ -14,15 +9,28 @@ var JSONParseStreamRaw = class {
 	key;
 	value;
 	position = 0;
+	onKey;
+	onPop;
+	onPush;
 	onValue;
 	unicode;
-	highSurrogate;
 	seenRootObject = false;
 	multi;
 	multiIndex = 0;
-	constructor({ multi, onValue }) {
-		this.onValue = onValue;
+	parseWholeValue;
+	captureDisabled = false;
+	capturePieces;
+	captureStart = 0;
+	captureDepth = 0;
+	captureInString = false;
+	captureEscaped = false;
+	constructor({ multi, onKey, onPop, onPush, onValue, parseWholeValue }) {
 		this.multi = multi;
+		this.onKey = onKey;
+		this.onPop = onPop;
+		this.onPush = onPush;
+		this.onValue = onValue;
+		this.parseWholeValue = parseWholeValue;
 	}
 	charError(char, i) {
 		throw new Error(`Unexpected ${JSON.stringify(char)} at position ${this.position + i} in state ${this.tokenizerState}`);
@@ -30,13 +38,91 @@ var JSONParseStreamRaw = class {
 	parseError(token, value, i) {
 		throw new Error(`Unexpected ${token}${value ? `(${JSON.stringify(value)})` : ""} at position ${this.position + i} in state ${this.state}`);
 	}
+	shouldCapture() {
+		return this.parseWholeValue !== void 0 && !this.captureDisabled && (this.state === "VALUE" || this.state === "VALUE_AFTER_COMMA") && this.parseWholeValue();
+	}
+	startCapture(text, i) {
+		this.captureStart = this.position + i;
+		this.captureDepth = 0;
+		this.captureInString = false;
+		this.captureEscaped = false;
+		const end = this.scanCapture(text, i);
+		if (end === -1) {
+			this.capturePieces = [text.slice(i)];
+			return text.length - 1;
+		}
+		this.endCapture(text.slice(i, end + 1));
+		return end;
+	}
+	scanCapture(text, start) {
+		const l = text.length;
+		let j = start;
+		if (this.captureEscaped && j < l) {
+			this.captureEscaped = false;
+			j += 1;
+		}
+		let depth = this.captureDepth;
+		let inString = this.captureInString;
+		for (; j < l; j++) {
+			const code = text.charCodeAt(j);
+			if (inString) {
+				if (code === 92) {
+					j += 1;
+					if (j === l) this.captureEscaped = true;
+				} else if (code === 34) inString = false;
+			} else if (code === 34) inString = true;
+			else if (code === 123 || code === 91) depth += 1;
+			else if (code === 125 || code === 93) {
+				depth -= 1;
+				if (depth === 0) return j;
+			}
+		}
+		this.captureDepth = depth;
+		this.captureInString = inString;
+		return -1;
+	}
+	endCapture(json) {
+		this.capturePieces = void 0;
+		let value;
+		try {
+			value = JSON.parse(json);
+		} catch {
+			this.parseCaptureStrict(json);
+			return;
+		}
+		if (this.stack.length === 0) this.seenRootObject = true;
+		if (this.value) this.value[this.key] = value;
+		this.emit(value);
+	}
+	parseCaptureStrict(json) {
+		const position = this.position;
+		this.position = this.captureStart;
+		this.captureDisabled = true;
+		this.write(json);
+		this.captureDisabled = false;
+		this.position = position;
+	}
 	write(text) {
-		for (let i = 0, l = text.length; i < l; i++) {
+		let i = 0;
+		if (this.capturePieces !== void 0) {
+			const end = this.scanCapture(text, 0);
+			if (end === -1) {
+				this.capturePieces.push(text);
+				this.position += text.length;
+				return;
+			}
+			this.capturePieces.push(text.slice(0, end + 1));
+			this.endCapture(this.capturePieces.join(""));
+			i = end + 1;
+		}
+		for (const l = text.length; i < l; i++) {
 			const n = text[i];
-			if (!this.multi && this.stack.length === 0 && this.seenRootObject && !WHITESPACE.has(n)) return this.charError(n, i);
-			if (this.tokenizerState === "START") if (n === "{") this.onToken("LEFT_BRACE", "{", i);
+			if (!this.multi && this.stack.length === 0 && this.seenRootObject && !isWhitespace(n)) return this.charError(n, i);
+			if (this.tokenizerState === "START") if (n === "{") if (this.shouldCapture()) i = this.startCapture(text, i);
+			else this.onToken("LEFT_BRACE", "{", i);
 			else if (n === "}") this.onToken("RIGHT_BRACE", "}", i);
-			else if (n === "[") this.onToken("LEFT_BRACKET", "[", i);
+			else if (n === "[") if (this.shouldCapture()) i = this.startCapture(text, i);
+			else this.onToken("LEFT_BRACKET", "[", i);
 			else if (n === "]") this.onToken("RIGHT_BRACKET", "]", i);
 			else if (n === ":") this.onToken("COLON", ":", i);
 			else if (n === ",") this.onToken("COMMA", ",", i);
@@ -55,15 +141,21 @@ var JSONParseStreamRaw = class {
 			} else if (n >= "1" && n <= "9") {
 				this.string = n;
 				this.tokenizerState = "NUMBER";
-			} else if (WHITESPACE.has(n)) {} else if (n === "␞" && this.multi && this.stack.length === 0) {} else return this.charError(n, i);
+			} else if (isWhitespace(n)) {} else if (n === "␞" && this.multi && this.stack.length === 0) {} else return this.charError(n, i);
 			else if (this.tokenizerState === "STRING1") if (n === "\"") {
 				this.tokenizerState = "START";
 				this.onToken("STRING", this.string, i);
 				this.string = void 0;
 			} else if (n === "\\") this.tokenizerState = "STRING2";
 			else {
-				if (n.charCodeAt(0) <= 31) this.charError(n, i);
-				this.string += n;
+				let j = i;
+				for (; j < l; j++) {
+					const code = text.charCodeAt(j);
+					if (code === 34 || code === 92) break;
+					if (code <= 31) return this.charError(text[j], j);
+				}
+				this.string += text.slice(i, j);
+				i = j - 1;
 			}
 			else if (this.tokenizerState === "STRING2") if (n === "\"") {
 				this.string += "\"";
@@ -94,59 +186,75 @@ var JSONParseStreamRaw = class {
 				this.tokenizerState = "STRING3";
 			} else return this.charError(n, i);
 			else if (this.tokenizerState === "STRING3" || this.tokenizerState === "STRING4" || this.tokenizerState === "STRING5" || this.tokenizerState === "STRING6") {
+				if (!(n >= "0" && n <= "9" || n >= "a" && n <= "f" || n >= "A" && n <= "F")) return this.charError(n, i);
 				this.unicode += n;
 				if (this.tokenizerState === "STRING3") this.tokenizerState = "STRING4";
 				else if (this.tokenizerState === "STRING4") this.tokenizerState = "STRING5";
 				else if (this.tokenizerState === "STRING5") this.tokenizerState = "STRING6";
 				else if (this.tokenizerState === "STRING6") {
 					const intVal = Number.parseInt(this.unicode, 16);
-					if (Number.isNaN(intVal)) return this.charError(n, i);
 					this.unicode = void 0;
-					if (this.highSurrogate !== void 0 && intVal >= 56320 && intVal < 57344) {
-						this.string += String.fromCharCode(this.highSurrogate, intVal);
-						this.highSurrogate = void 0;
-					} else if (this.highSurrogate === void 0 && intVal >= 55296 && intVal < 56320) this.highSurrogate = intVal;
-					else {
-						if (this.highSurrogate !== void 0) {
-							this.string += String.fromCharCode(this.highSurrogate);
-							this.highSurrogate = void 0;
-						}
-						this.string += String.fromCharCode(intVal);
-					}
+					this.string += String.fromCharCode(intVal);
 					this.tokenizerState = "STRING1";
 				}
-			} else if (this.tokenizerState === "NUMBER" || this.tokenizerState === "NUMBER-" || this.tokenizerState === "NUMBER0") {
-				if (this.tokenizerState === "NUMBER0" && n >= "0" && n <= "9") return this.charError("0", i - 1);
-				switch (n) {
-					case "0":
-						this.string += n;
-						this.tokenizerState = this.tokenizerState === "NUMBER-" ? "NUMBER0" : "NUMBER";
-						break;
-					case "1":
-					case "2":
-					case "3":
-					case "4":
-					case "5":
-					case "6":
-					case "7":
-					case "8":
-					case "9":
-					case ".":
-					case "e":
-					case "E":
-					case "+":
-					case "-":
-						this.string += n;
-						this.tokenizerState = "NUMBER";
-						break;
-					default:
-						this.tokenizerState = "START";
-						this.numberReviver(this.string, i);
-						this.string = void 0;
-						i--;
-						break;
-				}
-			} else if (this.tokenizerState === "TRUE1") if (n === "r") this.tokenizerState = "TRUE2";
+			} else if (this.tokenizerState === "NUMBER") if (n >= "0" && n <= "9") this.string += n;
+			else if (n === ".") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_DOT";
+			} else if (n === "e" || n === "E") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_E";
+			} else {
+				this.endNumber(i);
+				i--;
+			}
+			else if (this.tokenizerState === "NUMBER_FRACTION") if (n >= "0" && n <= "9") this.string += n;
+			else if (n === "e" || n === "E") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_E";
+			} else {
+				this.endNumber(i);
+				i--;
+			}
+			else if (this.tokenizerState === "NUMBER0") if (n >= "0" && n <= "9") return this.charError("0", i - 1);
+			else if (n === ".") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_DOT";
+			} else if (n === "e" || n === "E") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_E";
+			} else {
+				this.endNumber(i);
+				i--;
+			}
+			else if (this.tokenizerState === "NUMBER-") if (n === "0") {
+				this.string += n;
+				this.tokenizerState = "NUMBER0";
+			} else if (n >= "1" && n <= "9") {
+				this.string += n;
+				this.tokenizerState = "NUMBER";
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "NUMBER_DOT") if (n >= "0" && n <= "9") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_FRACTION";
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "NUMBER_E") if (n >= "0" && n <= "9") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_EXPONENT";
+			} else if (n === "+" || n === "-") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_E_SIGN";
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "NUMBER_E_SIGN") if (n >= "0" && n <= "9") {
+				this.string += n;
+				this.tokenizerState = "NUMBER_EXPONENT";
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "NUMBER_EXPONENT") if (n >= "0" && n <= "9") this.string += n;
+			else {
+				this.endNumber(i);
+				i--;
+			}
+			else if (this.tokenizerState === "TRUE1") if (n === "r") this.tokenizerState = "TRUE2";
 			else return this.charError(n, i);
 			else if (this.tokenizerState === "TRUE2") if (n === "u") this.tokenizerState = "TRUE3";
 			else return this.charError(n, i);
@@ -175,12 +283,17 @@ var JSONParseStreamRaw = class {
 		}
 		this.position += text.length;
 	}
-	push() {
+	push(mode, value) {
 		this.stack.push({
 			value: this.value,
 			key: this.key,
 			mode: this.mode
 		});
+		if (this.value) this.value[this.key] = value;
+		this.value = value;
+		this.mode = mode;
+		this.key = mode === "ARRAY" ? 0 : void 0;
+		this.onPush?.(this.stack.length);
 	}
 	pop() {
 		const value = this.value;
@@ -189,8 +302,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;
+		this.onKey?.(this.stack.length);
+	}
 	emit(value) {
 		if (this.mode) this.state = "COMMA";
 		if (value === void 0) return;
@@ -204,18 +322,10 @@ var JSONParseStreamRaw = class {
 			if (this.value) this.value[this.key] = value;
 			this.emit(value);
 		} else if (token === "LEFT_BRACE") {
-			this.push();
-			if (this.value) this.value = this.value[this.key] = {};
-			else this.value = {};
-			this.key = void 0;
+			this.push("OBJECT", {});
 			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.mode = "ARRAY";
+			this.push("ARRAY", []);
 			this.state = "VALUE";
 		} else if (token === "RIGHT_BRACE") if (this.mode === "OBJECT" && this.state !== "VALUE_AFTER_COMMA") this.pop();
 		else return this.parseError(token, value, i);
@@ -223,7 +333,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);
@@ -238,17 +348,22 @@ var JSONParseStreamRaw = class {
 		else return this.parseError(token, value, i);
 		else return this.parseError(token, value, i);
 	}
-	numberReviver(text, i) {
-		const number = JSON.parse(text);
-		if (Number.isNaN(number)) return this.charError(text, i);
+	endNumber(i) {
+		const number = Number(this.string);
+		this.string = void 0;
+		this.tokenizerState = "START";
 		this.onToken("NUMBER", number, i);
 	}
 	checkEnd() {
+		if (this.capturePieces !== void 0) {
+			const json = this.capturePieces.join("");
+			this.capturePieces = void 0;
+			this.parseCaptureStrict(json);
+		}
 		if (this.stack.length > 0) throw new Error(`Unexpected end of input at position ${this.position} in state ${this.state}`);
-		if (this.state === "VALUE" && this.tokenizerState === "NUMBER" && this.string !== void 0) {
-			this.numberReviver(this.string, this.position - 1);
-			this.string = void 0;
-		} else if (!this.seenRootObject) throw new Error("No data in input");
+		if (this.tokenizerState === "NUMBER" || this.tokenizerState === "NUMBER0" || this.tokenizerState === "NUMBER_FRACTION" || this.tokenizerState === "NUMBER_EXPONENT") this.endNumber(this.position - 1);
+		if (this.tokenizerState !== "START") throw new Error(`Unexpected end of input at position ${this.position} in state ${this.tokenizerState}`);
+		if (!this.seenRootObject) throw new Error("No data in input");
 	}
 };
 

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/dist/jsonPathToPathArray.js

@@ -8,22 +8,23 @@ const jsonPathToPathArray = (path) => {
 	} catch (error) {
 		throw new Error(`Error parsing JSONPath "${path}"`, { cause: error });
 	}
-	return parsed.segments.flatMap((segment) => {
+	return parsed.segments.map((segment) => {
 		if (segment.type === "ChildSegment") {
 			const node = segment.node;
 			if (node.type === "MemberNameShorthand") return {
 				type: "key",
 				value: node.value
 			};
-			else if (node.type === "BracketedSelection") return node.selectors.map((selector) => {
+			else if (node.type === "BracketedSelection") {
+				if (node.selectors.length !== 1) throw new Error(`Multiple selectors in brackets are not supported in JSONPath "${path}"`);
+				const selector = node.selectors[0];
 				if (selector.type === "NameSelector") return {
 					type: "key",
 					value: selector.value
 				};
 				else if (selector.type === "WildcardSelector") return { type: "wildcard" };
 				else throw new Error(`Unsupported node: ${JSON.stringify(node)}`);
-			});
-			else if (node.type === "WildcardSelector") return { type: "wildcard" };
+			} else if (node.type === "WildcardSelector") return { type: "wildcard" };
 			else throw new Error(`${segment.type} node type not supported`);
 		} else throw new Error(`${segment.type} segment type not supported`);
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "json-web-streams",
-	"version": "1.0.0",
+	"version": "1.2.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",
@@ -14,6 +14,7 @@
 	},
 	"license": "Apache-2.0",
 	"author": "Jeremy Scheff <jeremy@zengm.com> (https://zengm.com/)",
+	"sideEffects": false,
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -21,6 +22,7 @@
 		"dist"
 	],
 	"scripts": {
+		"bench": "vitest bench --run",
 		"build": "tsdown --unbundle",
 		"format": "prettier --write .",
 		"lint": "npm-run-all --parallel lint:oxlint lint:tsc",
@@ -28,7 +30,7 @@
 		"lint:tsc": "tsc",
 		"prepack": "node --run build",
 		"prepare": "husky",
-		"test": "vitest"
+		"test": "vitest --run"
 	},
 	"lint-staged": {
 		"*.{js,cjs,mjs,jsx,json,scss,ts,cts,mts,tsx,md}": "prettier --write"
@@ -39,21 +41,21 @@
 	},
 	"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.6",
 		"npm-run-all2": "^8.0.4",
-		"oxlint": "^1.23.0",
-		"oxlint-tsgolint": "^0.2.0",
+		"oxlint": "^1.24.0",
+		"oxlint-tsgolint": "^0.3.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",
+		"vitest": "^4.0.3",
 		"zod": "^4.1.12"
 	},
 	"engines": {
 		"node": ">=22",
-		"pnpm": "^10.0.0"
+		"pnpm": "^11.0.0"
 	}
 }