@jswalden/streaming-json/dist/stringify/stringify.d.ts

Streaming JSON parsing and stringification for JavaScript/TypeScript

/**
 * The string length at which emits of potentially unbounded length get broken
 * up.
 */
export declare const Quantum = 1024;
/**
 * A list of all properties to include in stringification of objects encountered
 * during stringification.
 */
export type ReplacerPropertyList = readonly (string | number)[];
/**
 * A replacer function, applied to each object/property name/value in the
 * overall graph created during stringification.  See `JSON.stringify`
 * documentation for precise details.
 *
 * Note that when the pertinent object is an array, keys are *strings* and not
 * numerical indexes.
 */
export type ReplacerFunction = (this: object, key: string, value: unknown) => unknown;
/** No replacer. */
export type NoReplacer = undefined | null;
/**
 * Create an iterable iterator over successive fragments of the JSON
 * stringification of a value, as if {@link 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.
 *
 * ```js
 * 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);
 * ```
 *
 * 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.)
 *
 * ```js
 * import { stringify } from "@jswalden/streaming-json";
 *
 * const cantStringify = undefined;
 * assert(JSON.stringify(cantStringify, null, 2) === undefined);
 * assert([...stringify(cantStringify, null, 2)].length === 0);
 * ```
 *
 * 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.
 *
 * @param value
 *   The value to stringify.
 * @param replacer
 *   A property list identifying the properties to include in stringification,
 *   a replacer function to call that can modify or eliminate values encoded in
 *   the ultimate stringification, or `null`/`undefined` if no replacement or
 *   limitation of properties should occur.
 * @param space
 *   If a number, contents will be pretty-printed using that many U+0020 SPACE
 *   characters as indentation.  Otherwise up to the first ten characters of a
 *   supplied string will be used as indentation.  If the requested indentation
 *   is an empty string, no pretty-printing occurs.
 */
export declare function stringify(value: unknown, replacer?: ReplacerFunction | ReplacerPropertyList | NoReplacer, space?: string | number): IterableIterator<string, void, void>;