json-web-streams 0.0.1

package/LICENSE

@@ -0,0 +1,209 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction, and
+    distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by the
+    copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all other
+    entities that control, are controlled by, or are under common control with
+    that entity. For the purposes of this definition, "control" means (i) the
+    power, direct or indirect, to cause the direction or management of such
+    entity, whether by contract or otherwise, or (ii) ownership of
+    fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+    ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity exercising
+    permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation source,
+    and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical transformation
+    or translation of a Source form, including but not limited to compiled
+    object code, generated documentation, and conversions to
+    other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or Object
+    form, made available under the License, as indicated by a copyright notice
+    that is included in or attached to the work (an example is provided in the
+    Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object form,
+    that is based on (or derived from) the Work and for which the editorial
+    revisions, annotations, elaborations, or other modifications represent,
+    as a whole, an original work of authorship. For the purposes of this
+    License, Derivative Works shall not include works that remain separable
+    from, or merely link (or bind by name) to the interfaces of, the Work and
+    Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including the original
+    version of the Work and any modifications or additions to that Work or
+    Derivative Works thereof, that is intentionally submitted to Licensor for
+    inclusion in the Work by the copyright owner or by an individual or
+    Legal Entity authorized to submit on behalf of the copyright owner.
+    For the purposes of this definition, "submitted" means any form of
+    electronic, verbal, or written communication sent to the Licensor or its
+    representatives, including but not limited to communication on electronic
+    mailing lists, source code control systems, and issue tracking systems
+    that are managed by, or on behalf of, the Licensor for the purpose of
+    discussing and improving the Work, but excluding communication that is
+    conspicuously marked or otherwise designated in writing by the copyright
+    owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity on
+    behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+    Subject to the terms and conditions of this License, each Contributor
+    hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+    royalty-free, irrevocable copyright license to reproduce, prepare
+    Derivative Works of, publicly display, publicly perform, sublicense,
+    and distribute the Work and such Derivative Works in
+    Source or Object form.
+
+3. Grant of Patent License.
+
+    Subject to the terms and conditions of this License, each Contributor
+    hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+    royalty-free, irrevocable (except as stated in this section) patent
+    license to make, have made, use, offer to sell, sell, import, and
+    otherwise transfer the Work, where such license applies only to those
+    patent claims licensable by such Contributor that are necessarily
+    infringed by their Contribution(s) alone or by combination of their
+    Contribution(s) with the Work to which such Contribution(s) was submitted.
+    If You institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+    Contribution incorporated within the Work constitutes direct or
+    contributory patent infringement, then any patent licenses granted to
+    You under this License for that Work shall terminate as of the date such
+    litigation is filed.
+
+4. Redistribution.
+
+    You may reproduce and distribute copies of the Work or Derivative Works
+    thereof in any medium, with or without modifications, and in Source or
+    Object form, provided that You meet the following conditions:
+
+    1. You must give any other recipients of the Work or Derivative Works a
+    copy of this License; and
+
+    2. You must cause any modified files to carry prominent notices stating
+    that You changed the files; and
+
+    3. You must retain, in the Source form of any Derivative Works that You
+    distribute, all copyright, patent, trademark, and attribution notices from
+    the Source form of the Work, excluding those notices that do not pertain
+    to any part of the Derivative Works; and
+
+    4. If the Work includes a "NOTICE" text file as part of its distribution,
+    then any Derivative Works that You distribute must include a readable copy
+    of the attribution notices contained within such NOTICE file, excluding
+    those notices that do not pertain to any part of the Derivative Works,
+    in at least one of the following places: within a NOTICE text file
+    distributed as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or, within a
+    display generated by the Derivative Works, if and wherever such
+    third-party notices normally appear. The contents of the NOTICE file are
+    for informational purposes only and do not modify the License.
+    You may add Your own attribution notices within Derivative Works that You
+    distribute, alongside or as an addendum to the NOTICE text from the Work,
+    provided that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and may
+    provide additional or different license terms and conditions for use,
+    reproduction, or distribution of Your modifications, or for any such
+    Derivative Works as a whole, provided Your use, reproduction, and
+    distribution of the Work otherwise complies with the conditions
+    stated in this License.
+
+5. Submission of Contributions.
+
+    Unless You explicitly state otherwise, any Contribution intentionally
+    submitted for inclusion in the Work by You to the Licensor shall be under
+    the terms and conditions of this License, without any additional
+    terms or conditions. Notwithstanding the above, nothing herein shall
+    supersede or modify the terms of any separate license agreement you may
+    have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+
+    This License does not grant permission to use the trade names, trademarks,
+    service marks, or product names of the Licensor, except as required for
+    reasonable and customary use in describing the origin of the Work and
+    reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+    Unless required by applicable law or agreed to in writing, Licensor
+    provides the Work (and each Contributor provides its Contributions)
+    on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+    either express or implied, including, without limitation, any warranties
+    or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS
+    FOR A PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any risks
+    associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+
+    In no event and under no legal theory, whether in tort
+    (including negligence), contract, or otherwise, unless required by
+    applicable law (such as deliberate and grossly negligent acts) or agreed
+    to in writing, shall any Contributor be liable to You for damages,
+    including any direct, indirect, special, incidental, or consequential
+    damages of any character arising as a result of this License or out of
+    the use or inability to use the Work (including but not limited to damages
+    for loss of goodwill, work stoppage, computer failure or malfunction,
+    or any and all other commercial damages or losses), even if such
+    Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+    While redistributing the Work or Derivative Works thereof, You may choose
+    to offer, and charge a fee for, acceptance of support, warranty,
+    indemnity, or other liability obligations and/or rights consistent with
+    this License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf of any
+    other Contributor, and only if You agree to indemnify, defend, and hold
+    each Contributor harmless for any liability incurred by, or claims
+    asserted against, such Contributor by reason of your accepting any such
+    warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+    To apply the Apache License to your work, attach the following boilerplate
+    notice, with the fields enclosed by brackets "[]" replaced with your own
+    identifying information. (Don't include the brackets!) The text should be
+    enclosed in the appropriate comment syntax for the file format. We also
+    recommend that a file or class name and description of purpose be included
+    on the same "printed page" as the copyright notice for easier
+    identification within third-party archives.
+
+        Copyright 2017 Jeremy Scheff
+
+
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+        or implied. See the License for the specific language governing
+        permissions and limitations under the License.
+

package/README.md

@@ -0,0 +1,367 @@
+# json-web-streams
+
+- **Stream large JSON files** without loading everything into memory
+- Built on the **Web Streams API** so it runs in web browsers, Node.js, and more
+- Query with **JSONPath** to extract only the data you need
+- Integrated **schema validation** with full **TypeScript** support
+- Tested on the [JSON Parsing Test Suite](https://github.com/nst/JSONTestSuite) and other edge cases
+
+## Installation
+
+```sh
+npm install json-web-streams
+```
+
+## Getting started
+
+Imagine you have some JSON like:
+
+```json
+[{ "x": 1 }, { "x": 2 }, { "x": 3 }]
+```
+
+You can just `JSON.parse` it and then do whatever you want. But what if it's so large that parsing it all at once is slow or impossible?
+
+By using json-web-streams, you can stream through the JSON object without having to read it all into memory. Here's an example that prints out each object as it is parsed:
+
+```ts
+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
+	.pipeThrough(new TextDecoderStream())
+	.pipeThrough(new JSONParseStream(["$[*]"]))
+	.pipeTo(
+		new WritableStream({
+			write({ value }) {
+				console.log(value);
+			},
+		}),
+	);
+
+// Output:
+// {"x": 1}
+// {"x": 2}
+// {"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 })[],
+    options?: { multi?: boolean },
+);
+```
+
+### `jsonPaths: (JSONPath | { path: JSONPath; 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.
+
+(The `JSONPath` type is just a slightly more restrictive version of a string. I wish it could completely parse and validate the JSONPath syntax, but currently it just enforces some little things like that it must start with a `$`.)
+
+In many cases, you'll just have one JSONPath query, like:
+
+```json
+["$.foo[*]"]
+```
+
+but you can have as many as you want:
+
+```json
+["$.foo[*]", "$.bar", "$.bar.baz"]
+```
+
+> [!IMPORTANT]
+> **json-web-streams only supports a subset of JSONPath.** See the [JSONPath](#jsonpath) section below for more details and examples. But to briefly explain what a typical JSONPath query means:
+>
+> `$.foo[*]` can be broken into three parts:
+>
+> `$` refers to the root node of the JSON object\
+> `.foo` is similar to accessing an object property in JS, so this is the `foo` property of the root node\
+> `[*]` means "every value in this array or object"
+>
+> 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.
+
+### `options?: { multi?: boolean }`
+
+There are various [JSON streaming formats](https://en.wikipedia.org/wiki/JSON_streaming) that make it more convenient to stream JSON by omitting the opening/closing tags and instead emitting multiple JSON objects sequentially. Some of these formats are:
+
+- JSON Lines (JSONL) aka Newline Delimited JSON (NDJSON) - JSON objects are separated by \n
+- JSON Text Sequences aka json-seq - JSON objects are separated by the unicode record separator character ␞
+- Concatenated JSON - JSON objects are simply concatenated with nothing in between.
+
+Setting `multi` to `true` enables support for all of those streaming JSON formats. It's actually a little more permissive - it allows any combination of whitespace and the unicode record separator between JSON objects.
+
+> [!TIP]
+> If you want to emit every one of these individual JSON objects, use the JSONPath query `$` which means "emit the entire object", so in `multi` mode it will emit each of the individual objects.
+
+### `JSONParseStream` input
+
+`new JSONParseStream(jsonPaths)` returns a [TransformStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream), meaning that it receives some input (e.g. from a ReadableStream) and emits some output (e.g. to a WritableStream).
+
+Inputs to the `JSONParseStream` stream must be strings. If you have a stream emitting some binary encoded text (such as from `fetch`), pipe it through `TextDecoderStream` first:
+
+```ts
+const response = await fetch("https://example.com/data.json");
+const stream = response.body
+	.pipeThrough(new TextDecoderStream())
+	.pipeThrough(new JSONParseStream(["$.foo[*]"]));
+```
+
+### `JSONParseStream` output
+
+Output from `JSONParseStream` has this format:
+
+```ts
+type JSONParseStreamOutput<T = unknown> = {
+	value: T;
+	path: JSONPath;
+	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`.
+
+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:
+
+<!-- prettier-ignore -->
+```ts
+await 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
+				}
+			},
+		}),
+	);
+```
+
+`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({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(new JSONParseStream(["$[*]"]))
+	.pipeTo(
+		new WritableStream({
+			write(record) {
+				console.log(record);
+			},
+		}),
+	);
+// Output:
+// { path: "$[*]", value: [1, 2], wildcardKeys: ["foo"] },
+// { path: "$[*]", 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.
+
+> [!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.
+
+#### Schema validation and types for `JSONParseStream` output
+
+If you want to validate the objects as they stream in, json-web-streams integrates with any schema validation library that supports the [Standard Schema specification](https://github.com/standard-schema/standard-schema), such as Zod, Valibot, and ArkType.
+
+To use schema validation for a JSONPath query, then pass an object `{ path: JSONPath; schema: StandardSchemaV1 }` rather just a string `JSONPath`. Then each value will be validated before being output by the stream, and the correct TypeScript types will be propagated through the stream as well.
+
+<!-- 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([
+			{ 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 JSONPath queries with no schema, emitted values will have the `unknown` type.
+
+## 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.
+
+- **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.
+
+You can combine these selectors as deep as you want. For instance, if instead you have an array of objects you can select values inside those individual objects with a query like `$.foo[*].bar`. Applying that to this data:
+
+```json
+{ "foo": [{ "bar": 1 }, { "bar": 2 }, { "bar": 3 }] }
+```
+
+would emit `1`, `2`, and `3`.
+
+Or if the array is at the root if the object like this data:
+
+```json
+[{ "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`).
+
+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 `$`.
+
+> [!TIP]
+> If you want to play around with JSONPath queries to make sure you understand what they are doing, [jsonpath.com](https://jsonpath.com/) is a great website that lets you easily run a JSONPath query on some data.
+
+## JSONParseStream examples
+
+There are several examples above in code blocks throughout the README, and here are a few more!
+
+### `wildcardKeys` vs. multiple entries in `jsonPaths`
+
+Sometimes there are multiple ways to achieve your goal.
+
+Let's say you have this JSON:
+
+```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`:
+
+<!-- prettier-ignore -->
+```ts
+await new ReadableStream({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(
+		new JSONParseStream(["$.foo[*]", "$.bar[*]"]),
+	)
+	.pipeTo(
+		new WritableStream({
+			write(record) {
+				if (record.path === "$.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({
+		start(controller) {
+			controller.enqueue('{ "foo": [1, 2], "bar": ["a", "b", "c"] }');
+			controller.close();
+		},
+	})
+	.pipeThrough(
+		new JSONParseStream(["$[*][*]"]),
+	)
+	.pipeTo(
+		new WritableStream({
+			write(record) {
+				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.
+
+But a nice thing about multiple JSONPath queries is that you can add schema validation to ensure your data is the correct format and give you nice TypeScript types. Whereas if you are using `wildcardKeys` to distinguish types, there is currently no way to use that information in schema validation.
+
+In this example, Zod schemas enforce that `record.value` is either a `string` or `number` as appropriate, rather than `unknown`:
+
+<!-- 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([
+			{ 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
+				}
+			},
+		}),
+	);
+```

package/dist/JSONParserStream.d.ts

@@ -0,0 +1,18 @@
+import { JSONParserText } from "./JSONParserText.js";
+import { JSONPath } from "./jsonPathToQueryPath.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/JSONParserStream.d.ts
+declare const createJSONParserStream: <JSONPathsObject extends Partial<Record<JSONPath, StandardSchemaV1 | null | undefined>> = Record<JSONPath, never>>(jsonPaths: JSONPathsObject) => JSONParserStream<JSONPathsObject>;
+declare class JSONParserStream<JSONPathsObject extends Partial<Record<JSONPath, StandardSchemaV1 | null | undefined>>> extends TransformStream<string, {
+  jsonPath: JSONPath;
+  value: unknown;
+  wildcardKeys?: string[];
+}> {
+  _parser: JSONParserText;
+  constructor(jsonPaths: JSONPathsObject, options?: {
+    multi?: boolean;
+  });
+}
+//#endregion
+export { createJSONParserStream };

package/dist/JSONParserStream.js

@@ -0,0 +1,108 @@
+import JSONParserText_default from "./JSONParserText.js";
+import { jsonPathToQueryPath } from "./jsonPathToQueryPath.js";
+
+//#region src/JSONParserStream.ts
+const stackToQueryPath = (stack) => {
+	return stack.slice(1).map((row) => {
+		if (row.mode === "OBJECT" && row.key !== void 0) return {
+			type: "key",
+			value: row.key
+		};
+		if (row.mode === "ARRAY") return { type: "wildcard" };
+		throw new Error(`Unexpected mode "${row.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";
+};
+const createJSONParserStream = (jsonPaths) => {
+	return new JSONParserStream(jsonPaths);
+};
+var JSONParserStream = class extends TransformStream {
+	_parser;
+	constructor(jsonPaths, options) {
+		let parser;
+		const multi = options?.multi ?? false;
+		const queryInfos = /* @__PURE__ */ new Map();
+		for (const [key, schema] of Object.entries(jsonPaths)) {
+			const jsonPath = key;
+			const queryPath = jsonPathToQueryPath(jsonPath);
+			let wildcardIndexes;
+			for (const [i, component] of queryPath.entries()) if (component.type === "wildcard") {
+				if (wildcardIndexes === void 0) wildcardIndexes = [];
+				wildcardIndexes.push(i);
+			}
+			queryInfos.set(jsonPath, {
+				jsonPath,
+				queryPath,
+				schema,
+				wildcardIndexes
+			});
+		}
+		super({
+			start(controller) {
+				parser = new JSONParserText_default({
+					multi,
+					onValue: (value, stack) => {
+						const path = stackToQueryPath(stack);
+						let keep = false;
+						for (const { jsonPath, queryPath, schema, wildcardIndexes } of queryInfos.values()) if (queryPath.every((x, j) => isEqual(x, path[j]))) if (path.length === queryPath.length) {
+							let valueToEmit;
+							if (schema) {
+								const result = schema["~standard"].validate(value);
+								if (result instanceof Promise) throw new Error("async schema validation is not supported");
+								if (result.issues) throw new Error(JSON.stringify(result.issues, null, 2));
+								valueToEmit = result.value;
+							} else valueToEmit = queryInfos.size === 1 ? value : structuredClone(value);
+							console.log("valueToEmit", value, valueToEmit);
+							let wildcardKeys;
+							if (wildcardIndexes) {
+								if (wildcardIndexes) for (const index of wildcardIndexes) {
+									const pathComponent = path[index];
+									if (pathComponent?.type === "key") {
+										if (!wildcardKeys) wildcardKeys = [];
+										wildcardKeys.push(pathComponent.value);
+									}
+								}
+							}
+							if (wildcardKeys) controller.enqueue({
+								jsonPath,
+								value: valueToEmit,
+								wildcardKeys
+							});
+							else controller.enqueue({
+								jsonPath,
+								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 parser.stack) row.value = void 0;
+							if (typeof parser.value === "object" && parser.value !== null && parser.key !== void 0) delete parser.value[parser.key];
+						}
+					}
+				});
+			},
+			transform(chunk) {
+				parser.write(chunk);
+			},
+			flush(controller) {
+				parser.checkEnd();
+				controller.terminate();
+			}
+		});
+		this._parser = parser;
+	}
+};
+
+//#endregion
+export { createJSONParserStream };

package/dist/JSONParserText.d.ts

@@ -0,0 +1,47 @@
+//#region src/JSONParserText.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 Mode = "OBJECT" | "ARRAY";
+type Key = string | number;
+type Value = any;
+type Stack = {
+  key: Key | undefined;
+  value: Value | undefined;
+  mode: Mode | undefined;
+}[];
+type OnValue = (value: Value, stack: Stack) => void;
+declare class JSONParserText {
+  tokenizerState: TokenizerState;
+  state: Token | ParserState;
+  mode: Mode | undefined;
+  stack: Stack;
+  string: string | undefined;
+  key: Key | undefined;
+  value: Value;
+  position: number;
+  onValue: OnValue;
+  unicode: string | undefined;
+  highSurrogate: number | undefined;
+  seenRootObject: boolean;
+  multi: boolean;
+  multiIndex: number;
+  constructor({
+    multi,
+    onValue
+  }: {
+    multi: boolean;
+    onValue: OnValue;
+  });
+  charError(char: string, i: number): void;
+  parseError(token: Token, value: Value, i: number): void;
+  write(text: string): void;
+  push(): void;
+  pop(): void;
+  emit(value: Value): void;
+  onToken(token: Token, value: Value, i: number): void;
+  numberReviver(text: string, i: number): void;
+  checkEnd(): void;
+}
+//#endregion
+export { JSONParserText };

package/dist/JSONParserText.js

@@ -0,0 +1,261 @@
+//#region src/JSONParserText.ts
+const WHITESPACE = new Set([
+	" ",
+	"	",
+	"\n",
+	"\r"
+]);
+var JSONParserText = class {
+	tokenizerState = "START";
+	state = "VALUE";
+	mode;
+	stack = [];
+	string;
+	key;
+	value;
+	position = 0;
+	onValue;
+	unicode;
+	highSurrogate;
+	seenRootObject = false;
+	multi;
+	multiIndex = 0;
+	constructor({ multi, onValue }) {
+		this.onValue = onValue;
+		this.multi = multi;
+	}
+	charError(char, i) {
+		throw new Error(`Unexpected ${JSON.stringify(char)} at position ${this.position + i} in state ${this.tokenizerState}`);
+	}
+	parseError(token, value, i) {
+		throw new Error(`Unexpected ${token}${value ? `(${JSON.stringify(value)})` : ""} at position ${this.position + i} in state ${this.state}`);
+	}
+	write(text) {
+		for (let i = 0, 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.multi && this.stack.length === 0 && this.seenRootObject) {}
+			if (this.tokenizerState === "START") if (n === "{") this.onToken("LEFT_BRACE", "{", i);
+			else if (n === "}") this.onToken("RIGHT_BRACE", "}", i);
+			else if (n === "[") 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);
+			else if (n === "t") this.tokenizerState = "TRUE1";
+			else if (n === "f") this.tokenizerState = "FALSE1";
+			else if (n === "n") this.tokenizerState = "NULL1";
+			else if (n === "\"") {
+				this.string = "";
+				this.tokenizerState = "STRING1";
+			} else if (n === "-") {
+				this.string = "-";
+				this.tokenizerState = "NUMBER-";
+			} else if (n === "0") {
+				this.string = n;
+				this.tokenizerState = "NUMBER0";
+			} 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 (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;
+			}
+			else if (this.tokenizerState === "STRING2") if (n === "\"") {
+				this.string += "\"";
+				this.tokenizerState = "STRING1";
+			} else if (n === "\\") {
+				this.string += "\\";
+				this.tokenizerState = "STRING1";
+			} else if (n === "/") {
+				this.string += "/";
+				this.tokenizerState = "STRING1";
+			} else if (n === "b") {
+				this.string += "\b";
+				this.tokenizerState = "STRING1";
+			} else if (n === "f") {
+				this.string += "\f";
+				this.tokenizerState = "STRING1";
+			} else if (n === "n") {
+				this.string += "\n";
+				this.tokenizerState = "STRING1";
+			} else if (n === "r") {
+				this.string += "\r";
+				this.tokenizerState = "STRING1";
+			} else if (n === "t") {
+				this.string += "	";
+				this.tokenizerState = "STRING1";
+			} else if (n === "u") {
+				this.unicode = "";
+				this.tokenizerState = "STRING3";
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "STRING3" || this.tokenizerState === "STRING4" || this.tokenizerState === "STRING5" || this.tokenizerState === "STRING6") {
+				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.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 return this.charError(n, i);
+			else if (this.tokenizerState === "TRUE2") if (n === "u") this.tokenizerState = "TRUE3";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "TRUE3") if (n === "e") {
+				this.tokenizerState = "START";
+				this.onToken("TRUE", true, i);
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "FALSE1") if (n === "a") this.tokenizerState = "FALSE2";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "FALSE2") if (n === "l") this.tokenizerState = "FALSE3";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "FALSE3") if (n === "s") this.tokenizerState = "FALSE4";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "FALSE4") if (n === "e") {
+				this.tokenizerState = "START";
+				this.onToken("FALSE", false, i);
+			} else return this.charError(n, i);
+			else if (this.tokenizerState === "NULL1") if (n === "u") this.tokenizerState = "NULL2";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "NULL2") if (n === "l") this.tokenizerState = "NULL3";
+			else return this.charError(n, i);
+			else if (this.tokenizerState === "NULL3") if (n === "l") {
+				this.tokenizerState = "START";
+				this.onToken("NULL", null, i);
+			} else return this.charError(n, i);
+		}
+		this.position += text.length;
+	}
+	push() {
+		this.stack.push({
+			value: this.value,
+			key: this.key,
+			mode: this.mode
+		});
+	}
+	pop() {
+		const value = this.value;
+		const parent = this.stack.pop();
+		this.value = parent.value;
+		this.key = parent.key;
+		this.mode = parent.mode;
+		this.emit(value);
+		if (!this.mode) this.state = "VALUE";
+	}
+	emit(value) {
+		if (this.mode) this.state = "COMMA";
+		this.onValue(value, [...this.stack, {
+			value: this.value,
+			key: this.key,
+			mode: this.mode
+		}]);
+	}
+	onToken(token, value, i) {
+		if (this.stack.length === 0) {
+			if (!this.seenRootObject) this.seenRootObject = true;
+		}
+		if (this.state === "VALUE" || this.state === "VALUE_AFTER_COMMA") if (token === "STRING" || token === "NUMBER" || token === "TRUE" || token === "FALSE" || token === "NULL") {
+			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.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.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);
+		else if (token === "RIGHT_BRACKET") if (this.mode === "ARRAY" && this.state !== "VALUE_AFTER_COMMA") this.pop();
+		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.state = "COLON";
+		} else if (token === "RIGHT_BRACE" && this.state !== "KEY_AFTER_COMMA") this.pop();
+		else return this.parseError(token, value, i);
+		else if (this.state === "COLON") if (token === "COLON") this.state = "VALUE";
+		else return this.parseError(token, value, i);
+		else if (this.state === "COMMA") if (token === "COMMA") {
+			if (this.mode === "ARRAY") {
+				this.key++;
+				this.state = "VALUE_AFTER_COMMA";
+			} else if (this.mode === "OBJECT") this.state = "KEY_AFTER_COMMA";
+		} else if (token === "RIGHT_BRACKET" && this.mode === "ARRAY" || token === "RIGHT_BRACE" && this.mode === "OBJECT") this.pop();
+		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);
+		this.onToken("NUMBER", number, i);
+	}
+	checkEnd() {
+		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");
+	}
+};
+var JSONParserText_default = JSONParserText;
+
+//#endregion
+export { JSONParserText_default as default };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { JSONPath } from "./jsonPathToQueryPath.js";
+import { createJSONParserStream } from "./JSONParserStream.js";
+export { type JSONPath, createJSONParserStream };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { createJSONParserStream } from "./JSONParserStream.js";
+
+export { createJSONParserStream };

package/dist/jsonPathToQueryPath.d.ts

@@ -0,0 +1,5 @@
+//#region src/jsonPathToQueryPath.d.ts
+
+type JSONPath = "$" | `$${"." | "["}${string}`;
+//#endregion
+export { JSONPath };

package/dist/jsonPathToQueryPath.js

@@ -0,0 +1,33 @@
+import parser from "jsonpath-rfc9535/parser";
+
+//#region src/jsonPathToQueryPath.ts
+const jsonPathToQueryPath = (jsonPath) => {
+	let parsed;
+	try {
+		parsed = parser(jsonPath);
+	} catch (error) {
+		throw new Error(`Error parsing JSONPath "${jsonPath}"`, { cause: error });
+	}
+	return parsed.segments.flatMap((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) => {
+				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 throw new Error(`${segment.type} node type not supported`);
+		} else throw new Error(`${segment.type} segment type not supported`);
+	});
+};
+
+//#endregion
+export { jsonPathToQueryPath };

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "json-web-streams",
+	"version": "0.0.1",
+	"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",
+		"TransformStream",
+		"JSON"
+	],
+	"homepage": "https://github.com/zengm-games/json-web-streams",
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/zengm-games/json-web-streams.git"
+	},
+	"license": "Apache-2.0",
+	"author": "Jeremy Scheff <jeremy@zengm.com> (https://zengm.com/)",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsdown --unbundle",
+		"format": "prettier --write .",
+		"lint": "npm-run-all --parallel lint:oxlint lint:tsc",
+		"lint:oxlint": "oxlint --type-aware",
+		"lint:tsc": "tsc",
+		"prepare": "husky",
+		"test": "vitest"
+	},
+	"lint-staged": {
+		"*.{js,cjs,mjs,jsx,json,scss,ts,cts,mts,tsx,md}": "prettier --write"
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.0.0",
+		"jsonpath-rfc9535": "^1.3.0"
+	},
+	"devDependencies": {
+		"@ianvs/prettier-plugin-sort-imports": "^4.7.0",
+		"@types/node": "^24.8.1",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.2.4",
+		"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",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.4",
+		"zod": "^4.1.12"
+	},
+	"engines": {
+		"node": ">=22",
+		"pnpm": "^10.0.0"
+	}
+}