@sachitv/avro-typescript 0.4.0

package/esm/rpc/protocol_core.js

@@ -0,0 +1,285 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Protocol_name, _Protocol_namespace, _Protocol_messages, _Protocol_types, _Protocol_parent, _Protocol_handlers, _Protocol_hashBytes, _Protocol_hashKey, _Protocol_emitterResolvers, _Protocol_listenerResolvers;
+import { createType } from "../type/create_type.js";
+import { NamedType } from "../schemas/complex/named_type.js";
+import { md5FromString } from "../internal/crypto/md5.js";
+import { Message } from "./definitions/message_definition.js";
+import { bytesToHex, normalizeProtocolName, stringifyProtocol, } from "./protocol/protocol_helpers.js";
+import { StatelessListener } from "./message_endpoint/listener.js";
+import { StatelessEmitter } from "./message_endpoint/emitter.js";
+/**
+ * Core Avro RPC protocol representation that validates schemas, hashes the
+ * protocol definition, and coordinates message handlers and transports.
+ */
+export class Protocol {
+    constructor(name, namespace, messages, types, parent) {
+        _Protocol_name.set(this, void 0);
+        _Protocol_namespace.set(this, void 0);
+        _Protocol_messages.set(this, void 0);
+        _Protocol_types.set(this, void 0);
+        _Protocol_parent.set(this, void 0);
+        _Protocol_handlers.set(this, new Map());
+        _Protocol_hashBytes.set(this, void 0);
+        _Protocol_hashKey.set(this, void 0);
+        _Protocol_emitterResolvers.set(this, new Map());
+        _Protocol_listenerResolvers.set(this, new Map());
+        __classPrivateFieldSet(this, _Protocol_name, name, "f");
+        __classPrivateFieldSet(this, _Protocol_namespace, namespace, "f");
+        __classPrivateFieldSet(this, _Protocol_messages, messages, "f");
+        __classPrivateFieldSet(this, _Protocol_types, types, "f");
+        __classPrivateFieldSet(this, _Protocol_parent, parent, "f");
+        const canonical = stringifyProtocol(this);
+        __classPrivateFieldSet(this, _Protocol_hashBytes, md5FromString(canonical), "f");
+        __classPrivateFieldSet(this, _Protocol_hashKey, bytesToHex(__classPrivateFieldGet(this, _Protocol_hashBytes, "f")), "f");
+    }
+    /**
+     * Creates a new Protocol instance from a definition.
+     * @param attrs The protocol definition object.
+     * @param opts Protocol creation options.
+     * @returns A new Protocol instance.
+     */
+    static create(attrs, opts = {}) {
+        const name = normalizeProtocolName(attrs.protocol, attrs.namespace ?? opts.namespace);
+        const registry = opts.registry ?? new Map();
+        const createOpts = {
+            namespace: attrs.namespace ?? opts.namespace,
+            registry,
+        };
+        if (attrs.types) {
+            for (const schema of attrs.types) {
+                createType(schema, createOpts);
+            }
+        }
+        const messages = new Map();
+        if (attrs.messages) {
+            for (const [messageName, definition] of Object.entries(attrs.messages)) {
+                messages.set(messageName, new Message(messageName, definition, createOpts));
+            }
+        }
+        return new Protocol(name, attrs.namespace ?? opts.namespace, messages, registry);
+    }
+    /**
+     * Creates a subprotocol sharing the same context but without a parent reference.
+     * @returns A new Protocol instance.
+     */
+    subprotocol() {
+        return new Protocol(__classPrivateFieldGet(this, _Protocol_name, "f"), __classPrivateFieldGet(this, _Protocol_namespace, "f"), __classPrivateFieldGet(this, _Protocol_messages, "f"), __classPrivateFieldGet(this, _Protocol_types, "f"), this);
+    }
+    /**
+     * Gets the protocol name.
+     */
+    getName() {
+        return __classPrivateFieldGet(this, _Protocol_name, "f");
+    }
+    /**
+     * Returns the string representation of the protocol (JSON).
+     */
+    toString() {
+        return stringifyProtocol(this);
+    }
+    /**
+     * Gets the MD5 hash of the protocol as a hex string.
+     */
+    get hashKey() {
+        return __classPrivateFieldGet(this, _Protocol_hashKey, "f");
+    }
+    /**
+     * Gets the MD5 hash of the protocol as bytes.
+     */
+    getHashBytes() {
+        return __classPrivateFieldGet(this, _Protocol_hashBytes, "f").slice();
+    }
+    /**
+     * Gets all messages defined in the protocol.
+     */
+    getMessages() {
+        return __classPrivateFieldGet(this, _Protocol_messages, "f");
+    }
+    /**
+     * Gets all named types defined in the protocol.
+     */
+    getNamedTypes() {
+        const named = [];
+        for (const type of __classPrivateFieldGet(this, _Protocol_types, "f").values()) {
+            if (type instanceof NamedType) {
+                named.push(type);
+            }
+        }
+        return named;
+    }
+    /**
+     * Gets a specific message by name.
+     */
+    getMessage(name) {
+        return __classPrivateFieldGet(this, _Protocol_messages, "f").get(name);
+    }
+    /**
+     * Gets the names of all messages in the protocol.
+     */
+    getMessageNames() {
+        return Array.from(__classPrivateFieldGet(this, _Protocol_messages, "f").keys());
+    }
+    /**
+     * Gets the definition of a specific message.
+     */
+    getMessageDefinition(name) {
+        const message = __classPrivateFieldGet(this, _Protocol_messages, "f").get(name);
+        if (!message) {
+            return undefined;
+        }
+        const json = message.toJSON();
+        // Type assertion is safe here since Message.toJSON() returns a structure
+        // compatible with MessageDefinition
+        return json;
+    }
+    /**
+     * Gets summary information about the protocol.
+     */
+    getProtocolInfo() {
+        return {
+            name: __classPrivateFieldGet(this, _Protocol_name, "f"),
+            namespace: __classPrivateFieldGet(this, _Protocol_namespace, "f"),
+            hashKey: __classPrivateFieldGet(this, _Protocol_hashKey, "f"),
+            hashBytes: __classPrivateFieldGet(this, _Protocol_hashBytes, "f"),
+            messageNames: this.getMessageNames(),
+        };
+    }
+    /**
+     * Gets a type definition by name.
+     */
+    getType(name) {
+        return __classPrivateFieldGet(this, _Protocol_types, "f").get(name);
+    }
+    /**
+     * Registers a message handler for a specific message name.
+     */
+    on(name, handler) {
+        if (!__classPrivateFieldGet(this, _Protocol_messages, "f").has(name)) {
+            throw new Error(`unknown message: ${name}`);
+        }
+        __classPrivateFieldGet(this, _Protocol_handlers, "f").set(name, handler);
+        return this;
+    }
+    /**
+     * Emits a message using the provided emitter.
+     * @param name The name of the message to emit.
+     * @param request The request payload.
+     * @param emitter The emitter to use.
+     */
+    async emit(name, request, emitter) {
+        const message = __classPrivateFieldGet(this, _Protocol_messages, "f").get(name);
+        if (!message) {
+            throw new Error(`unknown message: ${name}`);
+        }
+        if (emitter.protocol.hashKey !== this.hashKey) {
+            throw new Error("invalid emitter");
+        }
+        return await emitter.send(message, request);
+    }
+    /**
+     * Creates a new message emitter for this protocol.
+     * @param transport The transport factory or instance.
+     * @param opts Transport options.
+     */
+    createEmitter(transport, opts = {}) {
+        if (typeof transport === "function") {
+            return new StatelessEmitter(this, transport, opts, Protocol.create);
+        }
+        throw new Error("Stateful transports are not supported yet.");
+    }
+    /**
+     * Creates a new message listener for this protocol.
+     * @param transport The transport instance.
+     * @param opts Transport options.
+     */
+    createListener(transport, opts = {}) {
+        if (opts.mode && opts.mode !== "stateless") {
+            throw new Error("Stateful listeners are not supported yet.");
+        }
+        return new StatelessListener(this, transport, opts, Protocol.create);
+    }
+    /**
+     * Gets the handler registered for a specific message.
+     */
+    getHandler(name) {
+        const handler = __classPrivateFieldGet(this, _Protocol_handlers, "f").get(name);
+        if (handler) {
+            return handler;
+        }
+        return __classPrivateFieldGet(this, _Protocol_parent, "f")?.getHandler(name);
+    }
+    /**
+     * Gets schema resolvers for an emitter (client) given a server hash.
+     */
+    getEmitterResolvers(hashKey, messageName) {
+        return __classPrivateFieldGet(this, _Protocol_emitterResolvers, "f").get(hashKey)?.get(messageName);
+    }
+    /**
+     * Gets schema resolvers for a listener (server) given a client hash.
+     */
+    getListenerResolvers(hashKey, messageName) {
+        return __classPrivateFieldGet(this, _Protocol_listenerResolvers, "f").get(hashKey)?.get(messageName);
+    }
+    /**
+     * Checks if resolvers exist for a given client hash.
+     */
+    hasListenerResolvers(hashKey) {
+        return __classPrivateFieldGet(this, _Protocol_listenerResolvers, "f").has(hashKey);
+    }
+    /**
+     * Checks if resolvers exist for a given server hash.
+     */
+    hasEmitterResolvers(hashKey) {
+        return __classPrivateFieldGet(this, _Protocol_emitterResolvers, "f").has(hashKey);
+    }
+    /**
+     * Ensures resolvers exist for communicating with a remote protocol (client-side).
+     */
+    ensureEmitterResolvers(hashKey, remote) {
+        if (__classPrivateFieldGet(this, _Protocol_emitterResolvers, "f").has(hashKey)) {
+            return;
+        }
+        const resolvers = new Map();
+        for (const [name, localMessage] of __classPrivateFieldGet(this, _Protocol_messages, "f").entries()) {
+            const remoteMessage = remote.getMessages().get(name);
+            if (!remoteMessage) {
+                throw new Error(`missing server message: ${name}`);
+            }
+            resolvers.set(name, {
+                response: localMessage.responseType.createResolver(remoteMessage.responseType),
+                error: localMessage.errorType.createResolver(remoteMessage.errorType),
+            });
+        }
+        __classPrivateFieldGet(this, _Protocol_emitterResolvers, "f").set(hashKey, resolvers);
+    }
+    /**
+     * Ensures resolvers exist for communicating with a remote protocol (server-side).
+     */
+    ensureListenerResolvers(hashKey, emitterProtocol) {
+        if (__classPrivateFieldGet(this, _Protocol_listenerResolvers, "f").has(hashKey)) {
+            return;
+        }
+        const resolvers = new Map();
+        for (const [name, serverMessage] of __classPrivateFieldGet(this, _Protocol_messages, "f").entries()) {
+            const clientMessage = emitterProtocol.getMessages().get(name);
+            if (!clientMessage) {
+                throw new Error(`missing client message: ${name}`);
+            }
+            resolvers.set(name, {
+                request: serverMessage.requestType.createResolver(clientMessage.requestType),
+            });
+        }
+        __classPrivateFieldGet(this, _Protocol_listenerResolvers, "f").set(hashKey, resolvers);
+    }
+}
+_Protocol_name = new WeakMap(), _Protocol_namespace = new WeakMap(), _Protocol_messages = new WeakMap(), _Protocol_types = new WeakMap(), _Protocol_parent = new WeakMap(), _Protocol_handlers = new WeakMap(), _Protocol_hashBytes = new WeakMap(), _Protocol_hashKey = new WeakMap(), _Protocol_emitterResolvers = new WeakMap(), _Protocol_listenerResolvers = new WeakMap();

package/esm/schemas/base_type.d.ts

@@ -0,0 +1,41 @@
+import { Type } from "./type.js";
+import { Resolver } from "./resolver.js";
+/**
+ * A callback function invoked when a validation error occurs.
+ * @param path - The path to the invalid value in the schema.
+ * @param invalidValue - The value that failed validation.
+ * @param schemaType - The schema type that the value was validated against.
+ */
+export type ErrorHook = (path: string[], invalidValue: unknown, schemaType: Type) => void;
+/**
+ * Options for the `isValid` method.
+ * @property {ErrorHook} [errorHook] - Optional callback to handle validation errors.
+ */
+export type IsValidOptions = {
+    errorHook?: ErrorHook;
+};
+/**
+ * Base implementation of Type<T> providing common serialization operations.
+ * Subclasses must implement the remaining abstract methods.
+ */
+export declare abstract class BaseType<T = unknown> extends Type<T> {
+    /**
+     * Deserializes an ArrayBuffer into a value using the schema.
+     * @param buffer The ArrayBuffer to deserialize.
+     * @returns The deserialized value.
+     */
+    fromBuffer(buffer: ArrayBuffer): Promise<T>;
+    /**
+     * Validates if a value conforms to the schema.
+     * @param value The value to validate.
+     * @param opts Optional validation options.
+     * @returns True if valid, false otherwise.
+     */
+    isValid(value: unknown, opts?: IsValidOptions): boolean;
+    /**
+     * Creates a resolver for schema evolution from a writer type to this reader type.
+     * @param writerType The writer schema type.
+     * @returns A resolver for reading the writer type as this type.
+     */
+    createResolver(writerType: Type): Resolver;
+}

package/esm/schemas/base_type.js

@@ -0,0 +1,49 @@
+import { ReadableTap } from "../serialization/tap.js";
+import { Type } from "./type.js";
+import { Resolver } from "./resolver.js";
+import { safeStringify } from "./json.js";
+/**
+ * Base implementation of Type<T> providing common serialization operations.
+ * Subclasses must implement the remaining abstract methods.
+ */
+export class BaseType extends Type {
+    /**
+     * Deserializes an ArrayBuffer into a value using the schema.
+     * @param buffer The ArrayBuffer to deserialize.
+     * @returns The deserialized value.
+     */
+    async fromBuffer(buffer) {
+        const tap = new ReadableTap(buffer);
+        const value = await this.read(tap);
+        if (!await tap.isValid() || tap.getPos() !== buffer.byteLength) {
+            throw new Error("Insufficient data for type");
+        }
+        return value;
+    }
+    /**
+     * Validates if a value conforms to the schema.
+     * @param value The value to validate.
+     * @param opts Optional validation options.
+     * @returns True if valid, false otherwise.
+     */
+    isValid(value, opts) {
+        return this.check(value, opts?.errorHook, []);
+    }
+    /**
+     * Creates a resolver for schema evolution from a writer type to this reader type.
+     * @param writerType The writer schema type.
+     * @returns A resolver for reading the writer type as this type.
+     */
+    createResolver(writerType) {
+        if (this.constructor === writerType.constructor) {
+            return new class extends Resolver {
+                async read(tap) {
+                    return await this.readerType.read(tap);
+                }
+            }(this);
+        }
+        else {
+            throw new Error(`Schema evolution not supported from writer type: ${safeStringify(writerType.toJSON())} to reader type: ${safeStringify(this.toJSON())}`);
+        }
+    }
+}

package/esm/schemas/complex/array_type.d.ts

@@ -0,0 +1,100 @@
+import { type ReadableTapLike, type WritableTapLike } from "../../serialization/tap.js";
+import { BaseType } from "../base_type.js";
+import { Resolver } from "../resolver.js";
+import type { JSONType, Type } from "../type.js";
+import { type ErrorHook } from "../error.js";
+/**
+ * Helper function to read an array from a tap.
+ * @param tap The tap to read from.
+ * @param readElement Function to read a single element.
+ * @param collect Function to collect each read element.
+ */
+export declare function readArrayInto<T>(tap: ReadableTapLike, readElement: (tap: ReadableTapLike) => Promise<T>, collect: (value: T) => void): Promise<void>;
+/**
+ * Parameters for creating an ArrayType.
+ */
+export interface ArrayTypeParams<T> {
+    /** The type of items in the array. */
+    items: Type<T>;
+}
+/**
+ * Avro `array` type for homogeneous collections of items described by a schema.
+ */
+export declare class ArrayType<T = unknown> extends BaseType<T[]> {
+    #private;
+    /**
+     * Creates a new ArrayType.
+     * @param params The array type parameters.
+     */
+    constructor(params: ArrayTypeParams<T>);
+    /**
+     * Gets the type of items in the array.
+     */
+    getItemsType(): Type<T>;
+    /**
+     * Overrides the base check method to validate array values.
+     * @param value The value to check.
+     * @param errorHook Optional error hook for validation errors.
+     * @param path The current path in the schema.
+     * @returns True if the value is a valid array of items, false otherwise.
+     */
+    check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /**
+     * Overrides the base write method to serialize an array.
+     * @param tap The tap to write to.
+     * @param value The array to write.
+     */
+    write(tap: WritableTapLike, value: T[]): Promise<void>;
+    /**
+     * Overrides the base skip method to skip over an array in the tap.
+     * @param tap The tap to skip from.
+     */
+    skip(tap: ReadableTapLike): Promise<void>;
+    /**
+     * Overrides the base read method to deserialize an array.
+     * @param tap The tap to read from.
+     * @returns The deserialized array.
+     */
+    read(tap: ReadableTapLike): Promise<T[]>;
+    /**
+     * Overrides the base toBuffer method to serialize an array to a buffer.
+     * @param value The array to serialize.
+     * @returns The serialized buffer.
+     */
+    toBuffer(value: T[]): Promise<ArrayBuffer>;
+    /**
+     * Overrides the base cloneFromValue method to clone an array.
+     * @param value The value to clone.
+     * @returns The cloned array.
+     */
+    cloneFromValue(value: unknown): T[];
+    /**
+     * Overrides the base compare method to compare two arrays.
+     * @param val1 The first array.
+     * @param val2 The second array.
+     * @returns Negative if val1 < val2, 0 if equal, positive if val1 > val2.
+     */
+    compare(val1: T[], val2: T[]): number;
+    /**
+     * Overrides the base random method to generate a random array.
+     * @returns A randomly generated array.
+     */
+    random(): T[];
+    /**
+     * Returns the JSON schema representation of this array type.
+     */
+    toJSON(): JSONType;
+    /**
+     * Compares two serialized arrays for ordering.
+     * @param tap1 The first tap to compare.
+     * @param tap2 The second tap to compare.
+     * @returns A negative number if tap1 < tap2, zero if equal, positive if tap1 > tap2.
+     */
+    match(tap1: ReadableTapLike, tap2: ReadableTapLike): Promise<number>;
+    /**
+     * Creates a resolver for schema evolution between array types.
+     * @param writerType The writer's array type.
+     * @returns A resolver for reading data written with the writer type.
+     */
+    createResolver(writerType: Type): Resolver;
+}