async-streamify/esm/send/asyncObjectSerializer.js

Stream and serialize nested promises and async iterables over HTTP, workers, etc

import BufferedAsyncIterable from "../util/bufferedAsyncIterable.js";
import isAsyncIterable from "../util/isAsyncIteratable.js";
import * as errorKind from "../kinds/error.js";
/**
 * Serializes objects containing promises and async iterables into a stream of updates.
 * Handles nested promises, async iterables, and regular object properties.
 *
 * @template TSource - The type of the source object being serialized
 *
 * @example
 * ```typescript
 * const obj = {
 *   name: "test",
 *   promise: Promise.resolve(42),
 *   async *numbers() {
 *     yield 1;
 *     yield 2;
 *   }
 * };
 *
 * const serializer = new AsyncObjectSerializer(obj);
 *
 * for await (const update of serializer) {
 *   console.log(update);
 *   // Initial: { name: "test", promise: { $promise: 1 }, numbers: { $asyncIterator: 2 } }
 *   // Promise resolved: [1, 42]
 *   // Iterator values: [2, { done: false, value: 1 }], [2, { done: false, value: 2 }]
 *   // Iterator done: [2, { done: true }]
 * }
 * ```
 */
export class AsyncObjectSerializer extends BufferedAsyncIterable {
    /**
     * Schedules updates for all active async iterators
     * @returns void
     */
    scheduleIteratorUpdates() {
        for (let i = 0; i < this.activeIterators.length; i++) {
            const thisIter = this.activeIterators[i];
            const { idx, iter, nextPromise, done } = thisIter;
            if (!done && !nextPromise) {
                thisIter.nextPromise = iter[Symbol.asyncIterator]().next().then((result) => {
                    this.push([idx, {
                            done: result.done,
                            value: this.serializeValue(result.value),
                        }]);
                    if (result.done) {
                        thisIter.done = true;
                        this.decrementActiveCount();
                    }
                    thisIter.nextPromise = undefined;
                });
            }
        }
    }
    /**
     * Creates a new AsyncObjectSerializer instance
     * @param object - The source object to serialize
     */
    constructor(object) {
        super();
        Object.defineProperty(this, "sourceObject", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: void 0
        });
        Object.defineProperty(this, "serializationIdCounter", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: 1
        });
        Object.defineProperty(this, "activeAsyncOperations", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: 0
        });
        Object.defineProperty(this, "activeIterators", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: []
        });
        this.sourceObject = object;
        // Option 1) queue all next()'s only when buffer is empty
        // this.onWait = this.scheduleIteratorUpdates;
        // Option 2) queue all next()'s on every next call = faster streaming
        this.onNext = this.scheduleIteratorUpdates;
        this.push(this.serializeValue(object));
        if (this.activeAsyncOperations === 0) {
            this.close();
        }
    }
    /**
     * Gets the next unique serialization ID and increments the active operation count
     * @returns number
     */
    getNextSerializationId() {
        this.activeAsyncOperations++;
        return this.serializationIdCounter++;
    }
    /**
     * Decrements the active operation count and marks as done if no operations remain
     * @returns void
     */
    decrementActiveCount() {
        this.activeAsyncOperations--;
        if (this.activeAsyncOperations === 0) {
            this.close();
        }
    }
    /**
     * Recursively serializes a value, handling promises, async iterables, and nested objects
     * @param value - The value to serialize
     * @returns The serialized value
     */
    serializeValue(value) {
        // Return primitives as-is: null, undefined, numbers, strings, etc.
        if (typeof value !== "object" || value === null) {
            return value;
        }
        if (Array.isArray(value)) {
            return value.map((val) => this.serializeValue(val));
        }
        if (value instanceof Promise) {
            const idx = this.getNextSerializationId();
            value.then((resolved) => {
                this.push([idx, { $resolve: this.serializeValue(resolved) }]);
            }).catch((error) => {
                this.push([idx, { $reject: errorKind.maybeSerialize(error) }]);
            }).finally(() => {
                this.decrementActiveCount();
            });
            return { $promise: idx };
        }
        if (isAsyncIterable(value)) {
            const idx = this.getNextSerializationId();
            this.activeIterators.push({
                idx,
                iter: value,
            });
            return { $asyncIterator: idx };
        }
        if (value.constructor === Object) {
            return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, this.serializeValue(val)]));
        }
        return value;
    }
}
export default AsyncObjectSerializer;