@sachitv/avro-typescript 0.4.0

package/esm/rpc/protocol/transports/in_memory.d.ts

@@ -0,0 +1,27 @@
+import type { BinaryDuplexLike, StatelessTransportFactory } from "./transport_helpers.js";
+/**
+ * Represents a pair of in-memory transports for client-server communication,
+ * providing a client factory and a server accept method for testing or local use.
+ */
+export interface InMemoryTransportPair {
+    /**
+     * Factory passed to emitters to establish a new client connection.
+     */
+    clientFactory: StatelessTransportFactory;
+    /**
+     * Accepts the next server-side connection created by the client factory.
+     */
+    accept(): Promise<BinaryDuplexLike>;
+}
+/**
+ * Creates a pair of in-memory transports for testing or local communication.
+ *
+ * @returns An object containing a client factory and an accept method for the server.
+ */
+export declare function createInMemoryTransportPair(): InMemoryTransportPair;
+/**
+ * Creates a simple in-memory transport factory.
+ *
+ * @returns A factory function that creates a new in-memory transport for each request.
+ */
+export declare function createInMemoryTransport(): StatelessTransportFactory;

package/esm/rpc/protocol/transports/in_memory.js

@@ -0,0 +1,125 @@
+/**
+ * Creates a pair of in-memory transports for testing or local communication.
+ *
+ * @returns An object containing a client factory and an accept method for the server.
+ */
+export function createInMemoryTransportPair() {
+    const pendingServers = [];
+    const pendingAccepts = [];
+    const clientFactory = () => {
+        const pair = createDuplexPair();
+        const resolver = pendingAccepts.shift();
+        if (resolver) {
+            resolver(pair.server);
+        }
+        else {
+            pendingServers.push(pair.server);
+        }
+        return Promise.resolve(pair.client);
+    };
+    const accept = () => {
+        const queued = pendingServers.shift();
+        if (queued) {
+            return Promise.resolve(queued);
+        }
+        return new Promise((resolve) => {
+            pendingAccepts.push(resolve);
+        });
+    };
+    return { clientFactory, accept };
+}
+/**
+ * Creates a simple in-memory transport factory.
+ *
+ * @returns A factory function that creates a new in-memory transport for each request.
+ */
+export function createInMemoryTransport() {
+    return createInMemoryTransportPair().clientFactory;
+}
+function createDuplexPair() {
+    const clientChannel = new MemoryChannel();
+    const serverChannel = new MemoryChannel();
+    const client = {
+        readable: clientChannel,
+        writable: new MemoryChannelWritable(serverChannel),
+    };
+    const server = {
+        readable: serverChannel,
+        writable: new MemoryChannelWritable(clientChannel),
+    };
+    return { client, server };
+}
+class MemoryChannel {
+    constructor() {
+        Object.defineProperty(this, "closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "pendingResolvers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+    }
+    read() {
+        if (this.queue.length > 0) {
+            const chunk = this.queue.shift();
+            return Promise.resolve(chunk);
+        }
+        if (this.closed) {
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            this.pendingResolvers.push(resolve);
+        });
+    }
+    enqueue(chunk) {
+        if (this.closed) {
+            throw new Error("Cannot write to closed channel.");
+        }
+        if (this.pendingResolvers.length > 0) {
+            const resolver = this.pendingResolvers.shift();
+            resolver(chunk);
+        }
+        else {
+            this.queue.push(chunk);
+        }
+    }
+    close() {
+        if (this.closed) {
+            return Promise.resolve();
+        }
+        this.closed = true;
+        while (this.pendingResolvers.length > 0) {
+            const resolver = this.pendingResolvers.shift();
+            resolver(null);
+        }
+        return Promise.resolve();
+    }
+}
+class MemoryChannelWritable {
+    constructor(target) {
+        Object.defineProperty(this, "target", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: target
+        });
+    }
+    write(chunk) {
+        this.target.enqueue(chunk);
+        return Promise.resolve();
+    }
+    close() {
+        return this.target.close();
+    }
+}

package/esm/rpc/protocol/transports/transport_helpers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Represents a readable stream for binary data in the transport layer.
+ * Used for asynchronously reading chunks of binary data from a transport.
+ */
+export interface BinaryReadable {
+    /**
+     * Reads the next chunk of binary data from the transport.
+     * Returns a Uint8Array if data is available, or null if the stream is ended.
+     */
+    read(): Promise<Uint8Array | null>;
+}
+/**
+ * Represents a writable stream for binary data in the transport layer.
+ * Used for asynchronously writing chunks of binary data to a transport.
+ */
+export interface BinaryWritable {
+    /**
+     * Writes a chunk of binary data to the transport.
+     * @param chunk The binary data to write.
+     */
+    write(chunk: Uint8Array): Promise<void>;
+    /**
+     * Closes the writable stream, signaling the end of data transmission.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Represents a duplex stream for binary data in the transport layer.
+ * Combines readable and writable streams for bidirectional communication.
+ */
+export interface BinaryDuplex {
+    /** The readable side of the duplex stream. */
+    readable: BinaryReadable;
+    /** The writable side of the duplex stream. */
+    writable: BinaryWritable;
+}
+/**
+ * A type that can be either a BinaryReadable interface or a standard ReadableStream.
+ * Used to accept various readable transport implementations in the transport layer.
+ */
+export type BinaryReadableLike = BinaryReadable | ReadableStream<Uint8Array>;
+/**
+ * A type that can be either a BinaryWritable interface or a standard WritableStream.
+ * Used to accept various writable transport implementations in the transport layer.
+ */
+export type BinaryWritableLike = BinaryWritable | WritableStream<Uint8Array>;
+/**
+ * Represents a duplex-like stream that can be composed of different readable and writable types.
+ * Used for flexible duplex transport configurations in the transport layer.
+ */
+export interface BinaryDuplexLike {
+    /** The readable side, which can be a BinaryReadable or ReadableStream. */
+    readable: BinaryReadableLike;
+    /** The writable side, which can be a BinaryWritable or WritableStream. */
+    writable: BinaryWritableLike;
+}
+/**
+ * A factory function for creating stateless transport duplex streams.
+ * Returns a promise that resolves to a BinaryDuplexLike for establishing connections in the transport layer.
+ */
+export type StatelessTransportFactory = () => Promise<BinaryDuplexLike>;
+/**
+ * Options for configuring fetch-based transports in the transport layer.
+ * Allows customization of HTTP requests for RPC communication.
+ */
+export interface FetchTransportOptions {
+    /** The HTTP method to use for the request (e.g., 'POST'). */
+    method?: string;
+    /** Headers to include in the request. */
+    headers?: HeadersInit;
+    /** Additional initialization options for the fetch request. */
+    init?: RequestInit;
+    /** Custom fetch function to use instead of the global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for configuring WebSocket-based transports in the transport layer.
+ * Allows customization of WebSocket connections for RPC communication.
+ */
+export interface WebSocketTransportOptions {
+    /** Subprotocols to negotiate during the WebSocket handshake. */
+    protocols?: string | string[];
+    /** The type of binary data to expect from the WebSocket (e.g., 'arraybuffer', 'blob'). */
+    binaryType?: BinaryType;
+    /** Timeout in milliseconds for establishing the WebSocket connection. */
+    connectTimeoutMs?: number;
+    /** Factory function to create a custom WebSocket instance. */
+    socketFactory?: () => WebSocket;
+}
+/**
+ * Converts a BinaryDuplexLike to a standardized BinaryDuplex.
+ * Ensures consistent interface for duplex transports in the transport layer.
+ * @param input The duplex-like object to convert.
+ * @returns A BinaryDuplex with standardized readable and writable properties.
+ */
+export declare function toBinaryDuplex(input: BinaryDuplexLike): BinaryDuplex;
+/**
+ * Converts a BinaryReadableLike to a standardized BinaryReadable.
+ * Wraps ReadableStream or returns the interface directly for consistent reading in the transport layer.
+ * @param source The readable-like object to convert.
+ * @returns A BinaryReadable interface for asynchronous binary data reading.
+ */
+export declare function toBinaryReadable(source: BinaryReadableLike): BinaryReadable;
+/**
+ * Converts a BinaryWritableLike to a standardized BinaryWritable.
+ * Wraps WritableStream or returns the interface directly for consistent writing in the transport layer.
+ * @param target The writable-like object to convert.
+ * @returns A BinaryWritable interface for asynchronous binary data writing.
+ */
+export declare function toBinaryWritable(target: BinaryWritableLike): BinaryWritable;
+/**
+ * Extracts binary data from various input types into a Uint8Array.
+ * Used in the transport layer to normalize WebSocket message data for processing.
+ * @param data The input data to extract binary from (Uint8Array, ArrayBuffer, ArrayBufferView, string, etc.).
+ * @returns A Uint8Array representation of the binary data.
+ * @throws Error if the data type is unsupported or Blob (not supported for WebSocket).
+ */
+export declare function extractBinary(data: unknown): Uint8Array;

package/esm/rpc/protocol/transports/transport_helpers.js

@@ -0,0 +1,112 @@
+const textEncoder = new TextEncoder();
+/**
+ * Converts a BinaryDuplexLike to a standardized BinaryDuplex.
+ * Ensures consistent interface for duplex transports in the transport layer.
+ * @param input The duplex-like object to convert.
+ * @returns A BinaryDuplex with standardized readable and writable properties.
+ */
+export function toBinaryDuplex(input) {
+    return {
+        readable: toBinaryReadable(input.readable),
+        writable: toBinaryWritable(input.writable),
+    };
+}
+/**
+ * Converts a BinaryReadableLike to a standardized BinaryReadable.
+ * Wraps ReadableStream or returns the interface directly for consistent reading in the transport layer.
+ * @param source The readable-like object to convert.
+ * @returns A BinaryReadable interface for asynchronous binary data reading.
+ */
+export function toBinaryReadable(source) {
+    if (isBinaryReadable(source)) {
+        return source;
+    }
+    if (!isReadableStream(source)) {
+        throw new TypeError("Unsupported readable transport.");
+    }
+    const reader = source.getReader();
+    return {
+        async read() {
+            const { value, done } = await reader.read();
+            if (done) {
+                return null;
+            }
+            else {
+                if (value === undefined) {
+                    return new Uint8Array(0);
+                }
+                else {
+                    return value;
+                }
+            }
+        },
+    };
+}
+/**
+ * Converts a BinaryWritableLike to a standardized BinaryWritable.
+ * Wraps WritableStream or returns the interface directly for consistent writing in the transport layer.
+ * @param target The writable-like object to convert.
+ * @returns A BinaryWritable interface for asynchronous binary data writing.
+ */
+export function toBinaryWritable(target) {
+    if (isBinaryWritable(target)) {
+        return target;
+    }
+    if (!isWritableStream(target)) {
+        throw new TypeError("Unsupported writable transport.");
+    }
+    const writer = target.getWriter();
+    return {
+        async write(chunk) {
+            await writer.write(chunk);
+        },
+        async close() {
+            await writer.close();
+        },
+    };
+}
+/**
+ * Extracts binary data from various input types into a Uint8Array.
+ * Used in the transport layer to normalize WebSocket message data for processing.
+ * @param data The input data to extract binary from (Uint8Array, ArrayBuffer, ArrayBufferView, string, etc.).
+ * @returns A Uint8Array representation of the binary data.
+ * @throws Error if the data type is unsupported or Blob (not supported for WebSocket).
+ */
+export function extractBinary(data) {
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return new Uint8Array(view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength));
+    }
+    if (typeof Blob !== "undefined" && data instanceof Blob) {
+        throw new Error("Blob WebSocket messages are not supported.");
+    }
+    if (typeof data === "string") {
+        return textEncoder.encode(data);
+    }
+    throw new Error("Unsupported WebSocket message data.");
+}
+function isBinaryReadable(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        typeof value.read === "function";
+}
+function isBinaryWritable(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        typeof value.write === "function" &&
+        typeof value.close === "function";
+}
+function isReadableStream(value) {
+    return typeof ReadableStream !== "undefined" &&
+        value instanceof ReadableStream;
+}
+function isWritableStream(value) {
+    return typeof WritableStream !== "undefined" &&
+        value instanceof WritableStream;
+}

package/esm/rpc/protocol/transports/websocket.d.ts

@@ -0,0 +1,9 @@
+import type { StatelessTransportFactory, WebSocketTransportOptions } from "./transport_helpers.js";
+/**
+ * Creates a stateless transport factory using WebSockets.
+ *
+ * @param endpoint The WebSocket URL to connect to.
+ * @param options Configuration options for the WebSocket transport.
+ * @returns A factory function that creates a new transport for each request.
+ */
+export declare function createWebSocketTransport(endpoint: string | URL, options?: WebSocketTransportOptions): StatelessTransportFactory;

package/esm/rpc/protocol/transports/websocket.js

@@ -0,0 +1,102 @@
+import { extractBinary } from "./transport_helpers.js";
+/**
+ * Creates a stateless transport factory using WebSockets.
+ *
+ * @param endpoint The WebSocket URL to connect to.
+ * @param options Configuration options for the WebSocket transport.
+ * @returns A factory function that creates a new transport for each request.
+ */
+export function createWebSocketTransport(endpoint, options = {}) {
+    return async () => {
+        const socket = options.socketFactory
+            ? options.socketFactory()
+            : new WebSocket(typeof endpoint === "string" ? endpoint : endpoint.toString(), options.protocols);
+        socket.binaryType = options.binaryType ?? "arraybuffer";
+        await waitForOpen(socket, options.connectTimeoutMs);
+        return {
+            readable: websocketReadable(socket),
+            writable: websocketWritable(socket),
+        };
+    };
+}
+function waitForOpen(socket, timeout) {
+    if (socket.readyState === WebSocket.OPEN) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        let timer;
+        const cleanup = () => {
+            socket.removeEventListener("open", handleOpen);
+            socket.removeEventListener("error", handleError);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        };
+        const handleOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const handleError = () => {
+            cleanup();
+            reject(new Error("WebSocket connection failed."));
+        };
+        socket.addEventListener("open", handleOpen, { once: true });
+        socket.addEventListener("error", handleError, { once: true });
+        if (timeout !== undefined) {
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("WebSocket connection timed out."));
+            }, timeout);
+        }
+    });
+}
+class WebSocketReadableStream extends ReadableStream {
+    constructor(socket) {
+        let cleanup;
+        const start = (controller) => {
+            const handleMessage = (event) => {
+                try {
+                    controller.enqueue(extractBinary(event.data));
+                }
+                catch (err) {
+                    controller.error(err);
+                }
+            };
+            const handleClose = () => controller.close();
+            const handleError = () => controller.error(new Error("WebSocket error."));
+            socket.addEventListener("message", handleMessage);
+            socket.addEventListener("close", handleClose, { once: true });
+            socket.addEventListener("error", handleError, { once: true });
+            cleanup = () => {
+                socket.removeEventListener("message", handleMessage);
+                socket.removeEventListener("close", handleClose);
+                socket.removeEventListener("error", handleError);
+            };
+        };
+        const cancel = () => {
+            cleanup?.();
+            socket.close();
+            return Promise.resolve();
+        };
+        super({ start, cancel });
+    }
+}
+function websocketReadable(socket) {
+    return new WebSocketReadableStream(socket);
+}
+function websocketWritable(socket) {
+    return new WritableStream({
+        write(chunk) {
+            if (socket.readyState !== WebSocket.OPEN) {
+                throw new Error("WebSocket is not open.");
+            }
+            socket.send(chunk);
+        },
+        close() {
+            socket.close();
+        },
+        abort() {
+            socket.close();
+        },
+    });
+}

package/esm/rpc/protocol/wire_format/framing.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options for framing a message, specifying the frame size.
+ */
+export interface FrameMessageOptions {
+    /**
+     * The maximum size in bytes for each frame. Defaults to 8192.
+     */
+    frameSize?: number;
+}
+/**
+ * Options for decoding a framed message, specifying the starting offset.
+ */
+export interface DecodeFramedMessageOptions {
+    /**
+     * The byte offset in the buffer to start decoding from. Defaults to 0.
+     */
+    offset?: number;
+}
+/**
+ * Result of decoding a framed message, containing the payload and next offset.
+ */
+export interface DecodeFramedMessageResult {
+    /**
+     * The reassembled message payload as a Uint8Array.
+     */
+    payload: Uint8Array;
+    /**
+     * The byte offset in the buffer after the decoded message.
+     */
+    nextOffset: number;
+}
+/**
+ * Frames a message payload into a sequence of frames with size headers and a terminator frame.
+ * Splits the payload into frames of up to the specified frameSize bytes, each prefixed with a 4-byte
+ * big-endian length header, and appends a zero-length terminator frame.
+ */
+export declare function frameMessage(payload: ArrayBuffer | Uint8Array, options?: FrameMessageOptions): Uint8Array;
+/**
+ * Decodes a framed message from a buffer, reassembling the payload from frames.
+ * Reads frames starting from the specified offset, each consisting of a 4-byte big-endian length
+ * header followed by the frame data, until a zero-length frame (terminator) is encountered.
+ * Concatenates the frame data into the payload.
+ */
+export declare function decodeFramedMessage(buffer: ArrayBuffer, options?: DecodeFramedMessageOptions): DecodeFramedMessageResult;

package/esm/rpc/protocol/wire_format/framing.js

@@ -0,0 +1,74 @@
+import { concatUint8Arrays, toUint8Array, } from "../../../internal/collections/array_utils.js";
+const DEFAULT_FRAME_SIZE = 8 * 1024;
+const FRAME_HEADER_SIZE = 4;
+function normalizeFrameSize(frameSize) {
+    if (frameSize === undefined) {
+        return DEFAULT_FRAME_SIZE;
+    }
+    if (!Number.isInteger(frameSize) || frameSize <= 0) {
+        throw new RangeError("frameSize must be a positive integer.");
+    }
+    return frameSize;
+}
+/**
+ * Frames a message payload into a sequence of frames with size headers and a terminator frame.
+ * Splits the payload into frames of up to the specified frameSize bytes, each prefixed with a 4-byte
+ * big-endian length header, and appends a zero-length terminator frame.
+ */
+export function frameMessage(payload, options) {
+    const bytes = toUint8Array(payload);
+    const frameSize = normalizeFrameSize(options?.frameSize);
+    const frames = [];
+    let offset = 0;
+    while (offset < bytes.length) {
+        const chunkSize = Math.min(frameSize, bytes.length - offset);
+        const header = new Uint8Array(FRAME_HEADER_SIZE);
+        // Write big-endian uint32 frame length
+        new DataView(header.buffer).setUint32(0, chunkSize, false);
+        frames.push(header);
+        frames.push(bytes.subarray(offset, offset + chunkSize));
+        offset += chunkSize;
+    }
+    frames.push(new Uint8Array(FRAME_HEADER_SIZE));
+    return frames.length === 1 ? frames[0] : concatUint8Arrays(frames);
+}
+/**
+ * Decodes a framed message from a buffer, reassembling the payload from frames.
+ * Reads frames starting from the specified offset, each consisting of a 4-byte big-endian length
+ * header followed by the frame data, until a zero-length frame (terminator) is encountered.
+ * Concatenates the frame data into the payload.
+ */
+export function decodeFramedMessage(buffer, options = {}) {
+    const { offset = 0 } = options;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new RangeError("offset must be a non-negative integer.");
+    }
+    const bytes = new Uint8Array(buffer);
+    if (offset > bytes.length) {
+        throw new RangeError("offset exceeds buffer length.");
+    }
+    const frames = [];
+    const view = new DataView(buffer);
+    let cursor = offset;
+    let foundTerminator = false;
+    while (cursor + FRAME_HEADER_SIZE <= bytes.length) {
+        const frameLength = view.getUint32(cursor, false);
+        cursor += FRAME_HEADER_SIZE;
+        if (frameLength === 0) {
+            foundTerminator = true;
+            break;
+        }
+        if (cursor + frameLength > bytes.length) {
+            throw new Error("Incomplete frame data.");
+        }
+        frames.push(bytes.subarray(cursor, cursor + frameLength));
+        cursor += frameLength;
+    }
+    if (!foundTerminator) {
+        throw new Error("Message terminator not found.");
+    }
+    return {
+        payload: concatUint8Arrays(frames),
+        nextOffset: cursor,
+    };
+}