Function stringify

Create an iterable iterator over successive fragments of the JSON stringification of a value, as if JSON.stringify had been passed value, replacer, and space and then were returning successive slices of the result. Fragments are iterated until the entire stringification has been returned. Where fragment boundaries occur is explicitly not defined: do not attempt to infer or rely upon boundary locations.

If the incremental stringification operations performed to iterate the next fragment throw an exception, that exception will propagate to the caller.

import { stringify } from "@jswalden/streaming-json";

const iter = stringify([1, { toJSON() { throw 42; } }, 3], null, 0);

let result;

// These fragment boundaries are not guaranteed.  This example merely
// demonstrates the exception propagation behavior.
result = iter.next();
assert(!result.done && result.value === "[");

result = iter.next();
assert(!result.done && result.value === "1");

result = iter.next();
assert(!result.done && result.value === ",");

assertThrows(() => iter.next(), 42);
Copy

If value itself is not stringifiable (e.g. it's undefined, a symbol, or is callable) or if replacer doesn't preserve value, iteration produces no fragments. (Note that in this case JSON.stringify returns undefined, not a string.)

import { stringify } from "@jswalden/streaming-json";

const cantStringify = undefined;
assert(JSON.stringify(cantStringify, null, 2) === undefined);
assert([...stringify(cantStringify, null, 2)].length === 0);
Copy

Therefore if you use this function on insufficiently-restricted values expecting it to produce a concatenated stringification, you must be sure to verify that it actually iterates a fragment.