Add returnValue and currentRootValue properties to the state object passed to onChunk and onRootValue callbacks of parseChunked

Author: lahmatiy

CHANGELOG.md

@@ -1,3 +1,8 @@
+## next
+
+- `parseChunked()`:
+    - Added `returnValue` and `currentRootValue` properties to the state object passed to `onChunk` and `onRootValue` callbacks
+
 ## 1.0.0 (2026-03-09)
 
 - `parseChunked()`:

README.md

@@ -46,20 +46,22 @@ Functions like [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/Jav
 
 ```ts
 function parseChunked(input: Iterable<Chunk> | AsyncIterable<Chunk>, reviver?: Reviver): Promise<any>;
-function parseChunked(input: Iterable<Chunk> | AsyncIterable<Chunk>, options?: ParseChunkedOptions): Promise<any>;
+function parseChunked(input: Iterable<Chunk> | AsyncIterable<Chunk>, options?: ParseOptions): Promise<any>;
 function parseChunked(input: () => (Iterable<Chunk> | AsyncIterable<Chunk>), reviver?: Reviver): Promise<any>;
-function parseChunked(input: () => (Iterable<Chunk> | AsyncIterable<Chunk>), options?: ParseChunkedOptions): Promise<any>;
+function parseChunked(input: () => (Iterable<Chunk> | AsyncIterable<Chunk>), options?: ParseOptions): Promise<any>;
 
 type Chunk = string | Buffer | Uint8Array;
 type Reviver = (this: any, key: string, value: any) => any;
-type ParseChunkedOptions = {
+type ParseOptions = {
     reviver?: Reviver;
     mode?: 'json' | 'jsonl' | 'auto';
-    onRootValue?: (value: any, state: ParseChunkState) => void;
-    onChunk?: (chunkParsed: number, chunk: string | null, pending: string | null, state: ParseChunkState) => void;
+    onRootValue?: (value: any, state: ParseChunkedState) => void;
+    onChunk?: (chunkParsed: number, chunk: string | null, pending: string | null, state: ParseChunkedState) => void;
 };
-type ParseChunkState = {
+type ParseChunkedState = {
     mode: 'json' | 'jsonl';
+    returnValue: any;
+    currentRootValue: any;
     rootValuesCount: number;
     consumed: number;
     parsed: number;
@@ -88,7 +90,15 @@ You can pass `reviver` either as the second argument (`parseChunked(input, reviv
 
 `options.onRootValue` is called when a root value is parsed and finalized. When `onRootValue` is specified, `parseChunked()` resolves to the number of processed root values (instead of returning parsed value(s)), which allows processing huge or infinite streams without accumulating all values in memory.
 
-`options.onChunk` is called after each input chunk is processed and once at the end with `chunk = null`. It provides parsing progress and parser state (`consumed`, `parsed`, current mode and root values count).
+`options.onChunk` is called after each input chunk is processed and once at the end with `chunk = null`. It provides parsing progress and parser state as chunks are processed.
+
+The `state` object passed to `onRootValue` and `onChunk` callbacks has the following properties:
+    - `consumed` – number of characters consumed so far
+    - `parsed` – number of characters parsed so far (not necessarily the same when a chunk ends in the middle of a token)
+    - `mode` – current parsing mode (`json` or `jsonl`)
+    - `rootValuesCount` – number of root values parsed so far
+    - `currentRootValue` – current root value being parsed
+    - `returnValue` – current return value state, i.e. what `parseChunked()` will return when finished (either the parsed value or the number of root values, depending on whether `onRootValue` is specified)
 
 Examples:
 

index.d.ts

@@ -2,14 +2,16 @@ declare module '@discoveryjs/json-ext' {
     type Chunk = string | Uint8Array | Buffer;
 
     type Reviver = (this: any, key: string, value: any) => any;
-    type ParseChunkState = {
+    type ParseChunkedState = {
         readonly mode: 'json' | 'jsonl';
+        readonly returnValue: any;
+        readonly currentRootValue: any;
         readonly rootValuesCount: number;
         readonly consumed: number;
         readonly parsed: number;
     };
-    type OnRootValue = (value: any, state: ParseChunkState) => void;
-    type OnChunk = (chunkParsed: number, chunk: string | null, pending: string | null, state: ParseChunkState) => void;
+    type OnRootValue = (value: any, state: ParseChunkedState) => void;
+    type OnChunk = (chunkParsed: number, chunk: string | null, pending: string | null, state: ParseChunkedState) => void;
     type ParseOptions = {
         reviver?: Reviver;
         mode?: 'json' | 'jsonl' | 'auto';

src/parse-chunked.js

@@ -132,6 +132,18 @@ function createChunkParser(parseMode, reviver, onRootValue, onChunk) {
         get mode() {
             return parseMode === MODE_JSONL ? 'jsonl' : 'json';
         },
+        get returnValue() {
+            return typeof onRootValue === 'function'
+                ? rootValuesCount
+                : rootValues !== null
+                    ? rootValues
+                    : currentRootValue !== NO_VALUE
+                        ? currentRootValue
+                        : undefined;
+        },
+        get currentRootValue() {
+            return currentRootValue !== NO_VALUE ? currentRootValue : undefined;
+        },
         get rootValuesCount() {
             return rootValuesCount;
         },
@@ -547,10 +559,11 @@ function createChunkParser(parseMode, reviver, onRootValue, onChunk) {
             onChunk(0, null, null, state);
         }
 
-        if (typeof onRootValue === 'function') {
-            return rootValuesCount;
-        }
+        const result = state.returnValue;
+
+        rootValues = null;
+        currentRootValue = NO_VALUE;
 
-        return rootValues !== null ? rootValues : currentRootValue;
+        return result;
     }
 }

src/parse-chunked.test.js

@@ -8,6 +8,10 @@ function parse(chunks, options) {
     return parseChunked(() => chunks, options);
 }
 
+function clone(value) {
+    return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
 function split(str, chunkLen = 1) {
     const chunks = [];
 
@@ -579,72 +583,81 @@ describe('parseChunked()', () => {
         it('should report chunk progress when onChunk is used', async () => {
             const chunks = [];
             const actual = await parse(['{"a":', '1,', ' "b"', ':2,', '"c":3 }\n'], {
-                onChunk(chunkParsed, chunk, pending, { consumed, parsed }) {
+                onChunk(chunkParsed, chunk, pending, { mode, consumed, parsed, returnValue, currentRootValue }) {
                     chunks.push({
+                        mode,
                         chunkParsed,
                         chunk,
                         pending,
                         consumed,
-                        parsed
+                        parsed,
+                        returnValue: clone(returnValue), // clone to avoid mutation in later chunks
+                        currentRootValue: clone(currentRootValue) // clone to avoid mutation in later chunks
                     });
                 }
             });
             assert.deepStrictEqual(actual, { a: 1, b: 2, c: 3 });
             assert.deepStrictEqual(chunks, [
-                { chunkParsed: 1, chunk: '{"a":', pending: '"a":', consumed: 5, parsed: 1 },
-                { chunkParsed: 5, chunk: '1,', pending: ',', consumed: 7, parsed: 6 },
-                { chunkParsed: 0, chunk: ' "b"', pending: ', "b"', consumed: 11, parsed: 6 },
-                { chunkParsed: 7, chunk: ':2,', pending: ',', consumed: 14, parsed: 13 },
-                { chunkParsed: 9, chunk: '"c":3 }\n', pending: null, consumed: 22, parsed: 22 },
-                { chunkParsed: 0, chunk: null, pending: null, consumed: 22, parsed: 22 }
+                { mode: 'json', chunkParsed: 1, chunk: '{"a":', pending: '"a":', consumed: 5, parsed: 1, returnValue: {}, currentRootValue: {} },
+                { mode: 'json', chunkParsed: 5, chunk: '1,', pending: ',', consumed: 7, parsed: 6, returnValue: { a: 1 }, currentRootValue: { a: 1 } },
+                { mode: 'json', chunkParsed: 0, chunk: ' "b"', pending: ', "b"', consumed: 11, parsed: 6, returnValue: { a: 1 }, currentRootValue: { a: 1 } },
+                { mode: 'json', chunkParsed: 7, chunk: ':2,', pending: ',', consumed: 14, parsed: 13, returnValue: { a: 1, b: 2 }, currentRootValue: { a: 1, b: 2 } },
+                { mode: 'json', chunkParsed: 9, chunk: '"c":3 }\n', pending: null, consumed: 22, parsed: 22, returnValue: { a: 1, b: 2, c: 3 }, currentRootValue: { a: 1, b: 2, c: 3 } },
+                { mode: 'json', chunkParsed: 0, chunk: null, pending: null, consumed: 22, parsed: 22, returnValue: { a: 1, b: 2, c: 3 }, currentRootValue: { a: 1, b: 2, c: 3 } }
             ]);
         });
 
         it('jsonl', async () => {
             const chunks = [];
             const actual = await parse(['{"a":1', '}\n', '2\n[', '3]'], {
                 mode: 'jsonl',
-                onChunk(chunkParsed, chunk, pending, { consumed, parsed }) {
+                onChunk(chunkParsed, chunk, pending, { mode, consumed, parsed, returnValue, currentRootValue }) {
                     chunks.push({
+                        mode,
                         chunkParsed,
                         chunk,
                         pending,
                         consumed,
-                        parsed
+                        parsed,
+                        returnValue: clone(returnValue), // clone to avoid mutation in later chunks
+                        currentRootValue: clone(currentRootValue) // clone to avoid mutation in later chunks
                     });
                 }
             });
             assert.deepStrictEqual(actual, [{ a: 1 }, 2, [3]]);
             assert.deepStrictEqual(chunks, [
-                { chunkParsed: 1, chunk: '{"a":1', pending: '"a":1', consumed: 6, parsed: 1 },
-                { chunkParsed: 7, chunk: '}\n', pending: null, consumed: 8, parsed: 8 },
-                { chunkParsed: 3, chunk: '2\n[', pending: null, consumed: 11, parsed: 11 },
-                { chunkParsed: 2, chunk: '3]', pending: null, consumed: 13, parsed: 13 },
-                { chunkParsed: 0, chunk: null, pending: null, consumed: 13, parsed: 13 }
+                { mode: 'jsonl', chunkParsed: 1, chunk: '{"a":1', pending: '"a":1', consumed: 6, parsed: 1, returnValue: [], currentRootValue: {} },
+                { mode: 'jsonl', chunkParsed: 7, chunk: '}\n', pending: null, consumed: 8, parsed: 8, returnValue: [{ a: 1 }], currentRootValue: { a: 1 } },
+                { mode: 'jsonl', chunkParsed: 3, chunk: '2\n[', pending: null, consumed: 11, parsed: 11, returnValue: [{ a: 1 }, 2], currentRootValue: [] },
+                { mode: 'jsonl', chunkParsed: 2, chunk: '3]', pending: null, consumed: 13, parsed: 13, returnValue: [{ a: 1 }, 2, [3]], currentRootValue: [3] },
+                { mode: 'jsonl', chunkParsed: 0, chunk: null, pending: null, consumed: 13, parsed: 13, returnValue: [{ a: 1 }, 2, [3]], currentRootValue: [3] }
             ]);
         });
 
         it('auto', async () => {
             const chunks = [];
             const actual = await parse(['{"a":1', '}\n', '2\n[', '3]'], {
                 mode: 'auto',
-                onChunk(chunkParsed, chunk, pending, { consumed, parsed }) {
+                onChunk(chunkParsed, chunk, pending, { mode, consumed, parsed, returnValue, currentRootValue }) {
                     chunks.push({
+                        mode,
                         chunkParsed,
                         chunk,
                         pending,
                         consumed,
-                        parsed
+                        parsed,
+                        returnValue: clone(returnValue), // clone to avoid mutation in later chunks
+                        currentRootValue: clone(currentRootValue) // clone to avoid mutation in later chunks
                     });
                 }
             });
             assert.deepStrictEqual(actual, [{ a: 1 }, 2, [3]]);
             assert.deepStrictEqual(chunks, [
-                { chunkParsed: 1, chunk: '{"a":1', pending: '"a":1', consumed: 6, parsed: 1 },
-                { chunkParsed: 7, chunk: '}\n', pending: null, consumed: 8, parsed: 8 },
-                { chunkParsed: 3, chunk: '2\n[', pending: null, consumed: 11, parsed: 11 },
-                { chunkParsed: 2, chunk: '3]', pending: null, consumed: 13, parsed: 13 },
-                { chunkParsed: 0, chunk: null, pending: null, consumed: 13, parsed: 13 }
+                { mode: 'json', chunkParsed: 1, chunk: '{"a":1', pending: '"a":1', consumed: 6, parsed: 1, returnValue: {}, currentRootValue: {} },
+                { mode: 'json', chunkParsed: 7, chunk: '}\n', pending: null, consumed: 8, parsed: 8, returnValue: { a: 1 }, currentRootValue: { a: 1 } },
+                { mode: 'jsonl', chunkParsed: 3, chunk: '2\n[', pending: null, consumed: 11, parsed: 11, returnValue: [{ a: 1 }, 2], currentRootValue: [] },
+                { mode: 'jsonl', chunkParsed: 2, chunk: '3]', pending: null, consumed: 13, parsed: 13, returnValue: [{ a: 1 }, 2, [3]], currentRootValue: [3] },
+                { mode: 'jsonl', chunkParsed: 0, chunk: null, pending: null, consumed: 13, parsed: 13, returnValue: [{ a: 1 }, 2, [3]], currentRootValue: [3] }
             ]);
         });
     });