vortez-io 1.0.0

package/build/Frame.js

@@ -0,0 +1,241 @@
+/**
+ * @module vortez-io
+ * @author NetFeez <netfeez.dev@gemail.com>
+ * @license Apache-2.0
+ * @description Implements the core Frame structure of the Vortez IO protocol, including encoding and decoding logic for binary frames.
+ *              The Frame class provides static methods to encode and decode frames according to the protocol specification, handling various frame types, modes, and identifier formats.
+ *              It also includes validation to ensure that frames adhere to the protocol rules regarding type and identifier combinations.
+ *              This module is essential for constructing and interpreting the binary messages exchanged in the Vortez IO protocol.
+ *              The Frame structure consists of a header byte that encodes the frame type and mode, followed by an optional identifier (which can be a UUID or a string), and the payload data.
+ *              The encoding and decoding processes involve careful parsing of the header and identifier fields, as well as proper handling of the payload data to ensure compliance with the protocol.
+ *              The Frame class also defines the various types, modes, and identifier formats supported by the protocol, along with utility methods for converting between different representations (e.g., UUID to binary).
+ *              The implementation emphasizes robustness and error handling, throwing VIOError exceptions when encountering invalid input or protocol violations during encoding and decoding operations.
+ *              This module is a critical component of the Vortez IO protocol implementation, enabling the construction and interpretation of the binary frames that form the basis of communication within the protocol.
+ *              The Frame class is designed to be flexible and extensible, allowing for future additions of frame types, modes, and identifier formats as the protocol evolves.
+ *              The encoding and decoding logic is optimized for performance while maintaining strict adherence to the protocol specification, ensuring efficient processing of frames in real-world applications.
+ *              Overall, this module serves as the foundation for handling the binary communication aspects of the Vortez IO protocol, providing a clear and robust implementation of the Frame structure and its associated encoding and decoding mechanisms.
+ *
+ *             ⚠️ IMPORTANT: This module assumes that the input data for decoding is well-formed according to the protocol specification.
+ *              It performs basic validations but does not attempt to recover from malformed frames.
+ *              Users of this module should ensure that they are providing valid input to avoid unexpected errors during decoding.
+ *
+ * @see https://github.com/NetFeez/Vortez-IO-Protocol/blob/main/PROTOCOL.md for the full protocol specification and documentation.
+ */
+import UTF8Codec from "./support/UTF8Codec.js";
+import UUID from "./support/UUID.js";
+import Varint from "./support/Varint.js";
+import VIOError from "./VIOError.js";
+const MAX_ID_LENGTH = 1024;
+export class Frame {
+    type;
+    mode;
+    identifier;
+    data;
+    reservedRaw;
+    static TYPE_TO_BITS = {
+        RAW: 0x0, EVENT: 0x1, REQUEST: 0x2, RESPONSE: 0x3, ERROR: 0x4
+    };
+    static TYPE_MAP = {
+        0x0: 'RAW', 0x1: 'EVENT', 0x2: 'REQUEST', 0x3: 'RESPONSE', 0x4: 'ERROR'
+    };
+    static MODE_TO_BITS = {
+        BINARY: 0x0, JSON: 0x1, LINE: 0x2, CUSTOM: 0x3
+    };
+    static MODE_MAP = {
+        0x0: 'BINARY', 0x1: 'JSON', 0x2: 'LINE', 0x3: 'CUSTOM'
+    };
+    static ID_TYPE_TO_BITS = {
+        NONE: 0x0, UUID: 0x1, STRING: 0x2
+    };
+    static ID_TYPE_MAP = {
+        0x0: 'NONE', 0x1: 'UUID', 0x2: 'STRING',
+    };
+    constructor(type, mode, identifier, data, reservedRaw) {
+        this.type = type;
+        this.mode = mode;
+        this.identifier = identifier;
+        this.data = data;
+        this.reservedRaw = reservedRaw;
+    }
+    /**
+     * Decodes a binary frame from the given ArrayBuffer or Uint8Array according to the protocol specification.
+     * The method parses the frame header to determine the type, mode, and identifier, and then extracts the payload data.
+     * It performs various validations to ensure the frame adheres to the protocol rules, such as checking reserved bits and validating identifier types based on frame type.
+     * @param buffer The input buffer containing the binary frame data to decode.
+     * @returns A Frame object representing the decoded frame with its components (type, mode, identifier, data).
+     * @throws VIOError if the buffer is too short, contains invalid header values, or violates protocol rules regarding type and identifier combinations.
+     */
+    static decode(buffer) {
+        const view = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+        if (view.length < 3)
+            throw new VIOError(VIOError.Code.BUFFER_TOO_SHORT, 'Frame too short');
+        const head = view[0];
+        const typeBits = head & 0x0F;
+        const modeBits = (head >> 4) & 0x0F;
+        const type = this.assertDefined(this.TYPE_MAP[typeBits], VIOError.Code.INVALID_HEADER, `Invalid type: ${typeBits}`);
+        const mode = this.assertDefined(this.MODE_MAP[modeBits], VIOError.Code.INVALID_HEADER, `Invalid mode: ${modeBits}`);
+        const reserved = view[1];
+        if (reserved !== 0)
+            throw new VIOError(VIOError.Code.INVALID_HEADER, `Reserved byte must be 0 (got ${reserved})`);
+        const idMeta = view[2];
+        const idTypeBits = idMeta & 0x03;
+        const idReservedBits = idMeta >> 2;
+        if (idReservedBits !== 0)
+            throw new VIOError(VIOError.Code.INVALID_HEADER, 'ID_META reserved bits must be 0');
+        const idType = this.assertDefined(this.ID_TYPE_MAP[idTypeBits], VIOError.Code.INVALID_HEADER, `Invalid ID_TYPE: ${idTypeBits}`);
+        let identifier;
+        let offset = 3;
+        switch (idType) {
+            case 'NONE':
+                identifier = { type: 'NONE' };
+                break;
+            case 'UUID':
+                if (view.length < offset + 16)
+                    throw new VIOError(VIOError.Code.BUFFER_TOO_SHORT, 'UUID missing');
+                const raw = view.slice(offset, offset + 16);
+                identifier = {
+                    type: 'UUID',
+                    id: UUID.binToUuid(raw),
+                    idRaw: raw
+                };
+                offset += 16;
+                break;
+            case 'STRING': {
+                const { value: len, offset: next } = Varint.readVarint(view, offset);
+                if (len < 0 || len > MAX_ID_LENGTH)
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `Invalid String ID length: ${len}`);
+                offset = next;
+                if (view.length < offset + len)
+                    throw new VIOError(VIOError.Code.BUFFER_TOO_SHORT, 'String ID truncated');
+                const raw = view.slice(offset, offset + len);
+                identifier = {
+                    type: 'STRING',
+                    id: UTF8Codec.decode(raw),
+                    idRaw: raw
+                };
+                offset += len;
+                break;
+            }
+        }
+        const data = this.toArrayBuffer(view.slice(offset));
+        return this.assemble({ type, mode, identifier, data, reservedRaw: reserved });
+    }
+    /**
+     * Assembles a Frame object from the given components, performing additional validation to ensure that the combination of type and identifier adheres to protocol rules.
+     * This method is called after decoding the raw components of a frame to construct the final Frame object with proper typing and validation.
+     * It checks that REQUEST and RESPONSE frames use UUID identifiers, EVENT frames use STRING identifiers, and ERROR frames can use either NONE or UUID identifiers.
+     * If the components are valid, it returns a new Frame object; otherwise, it throws a VIOError indicating the specific protocol violation.
+     * @param parts An object containing the decoded components of the frame (type, mode, identifier, data, reservedRaw) to be assembled into a Frame object.
+     * @returns A Frame object representing the assembled frame with its components.
+     * @throws VIOError if the combination of type and identifier is invalid according to protocol rules.
+     */
+    static assemble(parts) {
+        const { type, mode, identifier, data, reservedRaw } = parts;
+        let frame;
+        switch (type) {
+            case 'REQUEST':
+            case 'RESPONSE':
+                if (identifier.type !== 'UUID')
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `${type} MUST use UUID`);
+                frame = new Frame(type, mode, identifier, data, reservedRaw);
+                break;
+            case 'EVENT':
+                if (identifier.type !== 'STRING')
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `EVENT MUST use STRING`);
+                frame = new Frame(type, mode, identifier, data, reservedRaw);
+                break;
+            case 'ERROR':
+                if (identifier.type !== 'NONE' && identifier.type !== 'UUID')
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `ERROR MUST use NONE or UUID`);
+                frame = new Frame(type, mode, identifier, data, reservedRaw);
+                break;
+            case 'RAW':
+                frame = new Frame(type, mode, identifier, data, reservedRaw);
+                break;
+        }
+        return frame;
+    }
+    static encode(type, mode, data, identifier = { type: 'NONE' }) {
+        const typeBits = this.assertDefined(this.TYPE_TO_BITS[type], VIOError.Code.UNKNOWN_TYPE, `Unknown type: ${type}`);
+        const modeBits = this.assertDefined(this.MODE_TO_BITS[mode], VIOError.Code.UNKNOWN_MODE, `Unknown mode: ${mode}`);
+        const idTypeBits = this.assertDefined(this.ID_TYPE_TO_BITS[identifier.type], VIOError.Code.INVALID_HEADER, `Unknown ID_TYPE: ${identifier.type}`);
+        this.validate(type, identifier.type);
+        let idBytes = new Uint8Array(0);
+        if (identifier.type === 'UUID') {
+            if (!UUID.isValid(identifier.id))
+                throw new VIOError(VIOError.Code.INVALID_HEADER, `Invalid UUID: ${identifier.id}`);
+            idBytes = UUID.uuidToBin(identifier.id);
+        }
+        else if (identifier.type === 'STRING') {
+            const encoded = UTF8Codec.encode(identifier.id);
+            const varint = Varint.writeVarint(encoded.length);
+            if (encoded.length > MAX_ID_LENGTH)
+                throw new VIOError(VIOError.Code.INVALID_HEADER, `String ID too long (max ${MAX_ID_LENGTH} bytes)`);
+            idBytes = new Uint8Array(varint.length + encoded.length);
+            idBytes.set(varint, 0);
+            idBytes.set(encoded, varint.length);
+        }
+        const payload = data instanceof Uint8Array ? data : new Uint8Array(data);
+        const totalLength = 3 + idBytes.length + payload.length;
+        const buffer = new Uint8Array(totalLength);
+        buffer[0] = (modeBits << 4) | typeBits;
+        buffer[1] = 0;
+        buffer[2] = idTypeBits & 0x03;
+        let offset = 3;
+        buffer.set(idBytes, offset);
+        offset += idBytes.length;
+        buffer.set(payload, offset);
+        return this.toArrayBuffer(buffer);
+    }
+    /**
+     * Validates the combination of frame type and identifier type according to protocol rules:
+     * - REQUEST and RESPONSE frames MUST use UUID identifiers.
+     * - EVENT frames MUST NOT use UUID identifiers (they can use STRING or NONE).
+     * - ERROR and RAW frames have no restrictions on identifier type.
+     * @param type The frame type to validate.
+     * @param idType The identifier type to validate against the frame type.
+     * @throws VIOError if the combination of type and idType is invalid according to the protocol rules.
+     */
+    static validate(type, idType) {
+        switch (type) {
+            case 'REQUEST':
+            case 'RESPONSE':
+                if (idType !== 'UUID')
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `${type} MUST use UUID`);
+                break;
+            case 'EVENT':
+                if (idType !== 'STRING')
+                    throw new VIOError(VIOError.Code.INVALID_HEADER, `EVENT MUST use STRING`);
+                break;
+            case 'ERROR': break;
+            case 'RAW': break;
+        }
+    }
+    /**
+     * Creates a copy of the ArrayBuffer from a Uint8Array view, ensuring it is not a shared buffer.
+     * This is necessary because the input Uint8Array may be a view into a larger buffer, and we want to ensure that the Frame's data is isolated and immutable.
+     * @param view The Uint8Array view to convert into an ArrayBuffer.
+     * @returns A new ArrayBuffer containing the data from the view.
+     */
+    static toArrayBuffer(view) {
+        const out = new Uint8Array(view.byteLength);
+        out.set(view);
+        return out.buffer;
+    }
+    /**
+     * Utility method to assert that a value is defined (not undefined) and throw a VIOError with the provided message if it is not.
+     * This is used to ensure that required values are present during decoding and validation processes.
+     * @param value The value to check for being defined.
+     * @param code The VIOError code to use if the value is undefined.
+     * @param msg The error message to include in the VIOError if the value is undefined.
+     * @returns The input value if it is defined, otherwise throws a VIOError.
+     * @throws VIOError if the value is undefined, with the provided message.
+     */
+    static assertDefined(value, code, msg) {
+        if (value === undefined)
+            throw new VIOError(code, msg);
+        return value;
+    }
+}
+export default Frame;
+//# sourceMappingURL=Frame.js.map

package/build/Frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Frame.js","sourceRoot":"","sources":["../src/Frame.ts"],"names":[],"mappings":"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"}

package/build/Isomorphic.d.ts

@@ -0,0 +1,7 @@
+export declare namespace Isomorphic {
+    type TimeoutHandler = () => void | Promise<void>;
+    type setTimeout<T> = (handler: TimeoutHandler, timeout: number) => T;
+    type clearTimeout<T> = (id: T) => void;
+    type createUUID = () => string;
+}
+export default Isomorphic;

package/build/Isomorphic.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Isomorphic.js.map

package/build/Isomorphic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Isomorphic.js","sourceRoot":"","sources":["../src/Isomorphic.ts"],"names":[],"mappings":""}

package/build/RequestManager.d.ts

@@ -0,0 +1,74 @@
+import { Events } from "@netfeez/common";
+import VIOError from "./VIOError.js";
+import type Frame from "./Frame.js";
+import type Isomorphic from "./Isomorphic.js";
+export declare class RequestManager<T extends any> extends Events<RequestManager.EventMap> {
+    protected pending: Map<string, RequestManager.PendingEntry<T>>;
+    protected setTimeout: Isomorphic.setTimeout<T>;
+    protected clearTimeout: Isomorphic.clearTimeout<T>;
+    protected createUUID: Isomorphic.createUUID;
+    constructor(dependencies: RequestManager.DEPENDENCIES<T>);
+    /**
+     * Send a request with the given data and return a Promise that resolves with the response or rejects with an error.
+     * The method generates a unique UUID for the request, stores the resolve and reject functions in the pending map, and emits a 'send' event with the UUID and data.
+     * The handler method should be called when a response or error is received, which will look up the corresponding entry in the pending map and resolve or reject the Promise accordingly.
+     * @param data The data to be sent with the request. This can be of any type depending on the application's needs.
+     * @param options The options for the request, including a timeout duration.
+     */
+    send(data: any, options?: RequestManager.SendOptions): Promise<RequestManager.Response>;
+    /**
+     * Handle a response or error for a request identified by the given UUID. This method should be called when a response or error is received for a previously sent request.
+     * It looks up the corresponding entry in the pending map using the UUID. If an entry is found, it resolves the Promise with the provided data if there is no error, or rejects it with the provided error if there is one. Finally, it removes the entry from the pending map to clean up resources.
+     * @param uuid The unique identifier for the request, which should match the UUID generated when the request was sent.
+     * @param data The response data to resolve the Promise with if there is no error.
+     * @param error The error to reject the Promise with if an error occurred.
+     */
+    handle(uuid: string, data?: RequestManager.Response, error?: VIOError): void;
+}
+export declare namespace RequestManager {
+    interface DEPENDENCIES<T extends any> {
+        setTimeout: Isomorphic.setTimeout<T>;
+        clearTimeout: Isomorphic.clearTimeout<T>;
+        createUUID?: Isomorphic.createUUID;
+    }
+    namespace Response {
+        type Base = {
+            mode: Frame.Mode;
+        };
+        interface Binary extends Base {
+            mode: 'BINARY' | 'CUSTOM';
+            data: Uint8Array;
+        }
+        interface Json extends Base {
+            mode: 'JSON';
+            data: any;
+        }
+        interface Line extends Base {
+            mode: 'LINE';
+            data: Record<string, string>;
+        }
+    }
+    type Response = Response.Binary | Response.Json | Response.Line;
+    type EventMap = {
+        send: [uuid: string, data?: any];
+        error: [error: VIOError];
+    };
+    /**
+     * Represents a pending request entry in the RequestManager.
+     * Each entry contains the resolve and reject functions for the Promise associated with the request, as well as a timeout identifier if a timeout mechanism is implemented.
+     * The resolve function is called with the response data when a successful response is received, while the reject function is called with an error if an error occurs or if a timeout is reached.
+     * The timeout field can be used to store the identifier returned by a setTimeout function, allowing for the implementation of request timeouts where the Promise is rejected if a response is not received within a certain timeframe.
+     * @template T The type of the timeout identifier, which can vary depending on the environment (e.g., NodeJS.Timeout in Node.js or number in browsers).
+     */
+    interface PendingEntry<T> {
+        resolve: (value: Response) => void;
+        reject: (reason: VIOError) => void;
+        timeout: T;
+    }
+    interface SendOptions {
+        timeoutMs?: number;
+    }
+    type Done<T> = (data: T) => void;
+    type Fail = (error: VIOError) => void;
+}
+export default RequestManager;

package/build/RequestManager.js

@@ -0,0 +1,61 @@
+import { Events } from "@netfeez/common";
+import UUID from "./support/UUID.js";
+import VIOError from "./VIOError.js";
+export class RequestManager extends Events {
+    pending = new Map();
+    setTimeout;
+    clearTimeout;
+    createUUID;
+    constructor(dependencies) {
+        super();
+        this.setTimeout = dependencies.setTimeout;
+        this.clearTimeout = dependencies.clearTimeout;
+        this.createUUID = dependencies.createUUID || UUID.create;
+    }
+    /**
+     * Send a request with the given data and return a Promise that resolves with the response or rejects with an error.
+     * The method generates a unique UUID for the request, stores the resolve and reject functions in the pending map, and emits a 'send' event with the UUID and data.
+     * The handler method should be called when a response or error is received, which will look up the corresponding entry in the pending map and resolve or reject the Promise accordingly.
+     * @param data The data to be sent with the request. This can be of any type depending on the application's needs.
+     * @param options The options for the request, including a timeout duration.
+     */
+    send(data, options = {}) {
+        const { timeoutMs = 30000 } = options;
+        const uuid = this.createUUID();
+        return new Promise((resolve, reject) => {
+            const timeout = this.setTimeout(() => {
+                this.pending.delete(uuid);
+                reject(new VIOError(VIOError.Code.INVALID_DATA, 'Request timed out'));
+            }, timeoutMs);
+            this.pending.set(uuid, { resolve, reject, timeout });
+            try {
+                this.emit('send', uuid, data);
+            }
+            catch (error) {
+                this.clearTimeout(timeout);
+                this.pending.delete(uuid);
+                reject(error instanceof VIOError ? error : new VIOError(VIOError.Code.INVALID_DATA, 'Failed to queue request'));
+            }
+        });
+    }
+    /**
+     * Handle a response or error for a request identified by the given UUID. This method should be called when a response or error is received for a previously sent request.
+     * It looks up the corresponding entry in the pending map using the UUID. If an entry is found, it resolves the Promise with the provided data if there is no error, or rejects it with the provided error if there is one. Finally, it removes the entry from the pending map to clean up resources.
+     * @param uuid The unique identifier for the request, which should match the UUID generated when the request was sent.
+     * @param data The response data to resolve the Promise with if there is no error.
+     * @param error The error to reject the Promise with if an error occurred.
+     */
+    handle(uuid, data, error) {
+        const entry = this.pending.get(uuid);
+        if (!entry)
+            return;
+        this.clearTimeout(entry.timeout);
+        if (error)
+            entry.reject(error);
+        else
+            entry.resolve(data ?? { mode: 'BINARY', data: new Uint8Array(0) });
+        this.pending.delete(uuid);
+    }
+}
+export default RequestManager;
+//# sourceMappingURL=RequestManager.js.map

package/build/RequestManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestManager.js","sourceRoot":"","sources":["../src/RequestManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,IAAI,MAAM,mBAAmB,CAAC;AACrC,OAAO,QAAQ,MAAM,eAAe,CAAC;AAKrC,MAAM,OAAO,cAA8B,SAAQ,MAA+B;IACpE,OAAO,GAAgD,IAAI,GAAG,EAAE,CAAC;IAEjE,UAAU,CAA2B;IACrC,YAAY,CAA6B;IACzC,UAAU,CAAwB;IAE5C,YAAmB,YAA4C;QAAI,KAAK,EAAE,CAAC;QACvE,IAAI,CAAC,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC;QAC1C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC,YAAY,CAAC;QAC9C,IAAI,CAAC,UAAU,GAAG,YAAY,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC;IAC7D,CAAC;IACD;;;;;;OAMG;IACI,IAAI,CAAC,IAAS,EAAE,UAAsC,EAAE;QAC3D,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,MAAM,OAAO,GAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE;gBACpC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC1B,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC,CAAC;YAC1E,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAErD,IAAI,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;gBAC3B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC1B,MAAM,CAAC,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC,CAAC;YACpH,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IACD;;;;;;OAMG;IACI,MAAM,CAAC,IAAY,EAAE,IAA8B,EAAE,KAAgB;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEjC,IAAI,KAAK;YAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;;YAC1B,KAAK,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAExE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACJ;AAgDD,eAAe,cAAc,CAAC"}

package/build/VIO.d.ts

@@ -0,0 +1,82 @@
+import { Events } from "@netfeez/common";
+import RequestManager from "./RequestManager.js";
+import VIOError from "./VIOError.js";
+import Frame from "./Frame.js";
+import LineCodec from "./support/LineParser.js";
+export declare class VIO<T extends any> extends Events<VIO.EventMap> {
+    protected mRequest: RequestManager<T>;
+    vTransport: Events.Emitter<VIO.TransportEventMap>;
+    constructor(dependencies: RequestManager.DEPENDENCIES<T>);
+    get transport(): Events<VIO.TransportEventMap>;
+    request(data: any, options?: RequestManager.SendOptions): Promise<RequestManager.Response>;
+    event(name: string, data: any): void;
+    handle(data: ArrayBuffer | Uint8Array): void;
+    protected handleRaw(frame: Frame): Promise<void>;
+    protected handleEvent(frame: Frame<'EVENT'>): Promise<void>;
+    protected handleRequest(frame: Frame<'REQUEST'>): Promise<void>;
+    protected handleResponse(frame: Frame<'RESPONSE'>): Promise<void>;
+    protected handleError(frame: Frame<'ERROR'>): Promise<void>;
+    protected sendEvent(name: string, data: Uint8Array | ArrayBuffer): void;
+    protected sendEvent(name: string, data: LineCodec.ContentMap, mode: 'LINE'): void;
+    protected sendEvent(name: string, data: any): void;
+    protected sendRequest(uuid: string, data: Uint8Array | ArrayBuffer): void;
+    protected sendRequest(uuid: string, data: LineCodec.ContentMap, mode: 'LINE'): void;
+    protected sendRequest(uuid: string, data: any): void;
+    protected sendResponse(uuid: string, data: Uint8Array | ArrayBuffer): void;
+    protected sendResponse(uuid: string, data: LineCodec.ContentMap, mode: 'LINE'): void;
+    protected sendResponse(uuid: string, data: any): void;
+    protected sendError(error: VIOError, uuid?: string): void;
+    protected serialize(data: any, mode?: 'LINE'): {
+        content: Uint8Array;
+        finalMode: Frame.Mode;
+    };
+}
+export declare namespace VIO {
+    export type TransportEventMap = {
+        send: [data: ArrayBuffer];
+        'transport:error': [err: Error, ctx?: {
+            stage: 'send' | 'recv' | 'connect';
+            frameType?: Frame.Type | string;
+            uuid?: string;
+            info?: any;
+        }];
+    };
+    type EventTuple = ([
+        name: string,
+        type: 'BINARY' | 'CUSTOM',
+        data: Uint8Array
+    ] | [
+        name: string,
+        type: 'JSON',
+        data: any
+    ] | [
+        name: string,
+        type: 'LINE',
+        data: Record<string, string>
+    ]);
+    type requestTuple = ([
+        type: 'BINARY' | 'CUSTOM',
+        data: Uint8Array,
+        done: RequestManager.Done<Uint8Array>,
+        fail: RequestManager.Fail
+    ] | [
+        type: 'JSON',
+        data: any,
+        done: RequestManager.Done<any>,
+        fail: RequestManager.Fail
+    ] | [
+        type: 'LINE',
+        data: Record<string, string>,
+        done: RequestManager.Done<Record<string, string>>,
+        fail: RequestManager.Fail
+    ]);
+    export type EventMap = {
+        request: requestTuple;
+        event: EventTuple;
+        error: [error: VIOError];
+        raw: [data: Frame];
+        response: [uuid: string, response: RequestManager.Response];
+    };
+    export {};
+}
+export default VIO;