vortez-io 1.0.0

package/src/RequestManager.ts

@@ -0,0 +1,114 @@
+import { Events } from "@netfeez/common";
+
+import UUID from "./support/UUID.js";
+import VIOError from "./VIOError.js";
+
+import type Frame from "./Frame.js";
+import type Isomorphic from "./Isomorphic.js";
+
+export class RequestManager<T extends any> extends Events<RequestManager.EventMap> {
+    protected pending: Map<string, RequestManager.PendingEntry<T>> = new Map();
+
+    protected setTimeout: Isomorphic.setTimeout<T>;
+    protected clearTimeout: Isomorphic.clearTimeout<T>;
+    protected createUUID: Isomorphic.createUUID;
+
+    public constructor(dependencies: RequestManager.DEPENDENCIES<T>) { 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.
+     */
+    public send(data: any, options: RequestManager.SendOptions = {}): Promise<RequestManager.Response> {
+        const { timeoutMs = 30000 } = options;
+        const uuid = this.createUUID();
+        return new Promise((resolve, reject) => {
+            const timeout: T = 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.
+     */
+    public handle(uuid: string, data?: RequestManager.Response, error?: VIOError): void {
+        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 namespace RequestManager {
+    export interface DEPENDENCIES<T extends any> {
+        setTimeout: Isomorphic.setTimeout<T>;
+        clearTimeout: Isomorphic.clearTimeout<T>;
+        createUUID?: Isomorphic.createUUID;
+    }
+    export namespace Response {
+        export type Base = { mode: Frame.Mode };
+        export interface Binary extends Base {
+            mode: 'BINARY' | 'CUSTOM';
+            data: Uint8Array;
+        }
+        export interface Json extends Base {
+            mode: 'JSON';
+            data: any;
+        }
+        export interface Line extends Base {
+            mode: 'LINE';
+            data: Record<string, string>;
+        }
+    }
+    export type Response = Response.Binary | Response.Json | Response.Line;
+    export 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).
+     */
+    export interface PendingEntry<T> {
+        resolve: (value: Response) => void;
+        reject: (reason: VIOError) => void;
+        timeout: T;
+    }
+
+    export interface SendOptions {
+        timeoutMs?: number;
+    }
+
+    export type Done<T> = (data: T) => void;
+    export type Fail = (error: VIOError) => void;
+}
+export default RequestManager;

package/src/VIO.ts

@@ -0,0 +1,194 @@
+import { Events } from "@netfeez/common";
+
+import RequestManager from "./RequestManager.js";
+import VIOError from "./VIOError.js";
+import Frame from "./Frame.js";
+import UTF8Codec from "./support/UTF8Codec.js";
+import LineCodec from "./support/LineParser.js";
+
+export class VIO<T extends any> extends Events<VIO.EventMap> {
+    protected mRequest: RequestManager<T>;
+    public vTransport: Events.Emitter<VIO.TransportEventMap>;
+
+    public constructor(dependencies: RequestManager.DEPENDENCIES<T>) {super();
+        this.mRequest = new RequestManager(dependencies);
+        this.mRequest.on('error', (error) => this.emit('error', error));
+        this.mRequest.on('send', this.sendRequest.bind(this));
+        this.vTransport = new Events.Emitter();
+    }
+    public get transport(): Events<VIO.TransportEventMap> { return this.vTransport; }
+    public async request(data: any, options?: RequestManager.SendOptions): Promise<RequestManager.Response> {
+        return this.mRequest.send(data, options);
+    }
+    public event(name: string, data: any): void {
+        this.sendEvent(name, data);
+    }
+    public handle(data: ArrayBuffer | Uint8Array): void {
+        try {
+            const frame = Frame.decode(data);
+            switch (frame.type) {
+                case 'RAW': this.handleRaw(frame); break;
+                case 'EVENT': this.handleEvent(frame); break;
+                case 'REQUEST': this.handleRequest(frame); break;
+                case 'RESPONSE': this.handleResponse(frame); break;
+                case 'ERROR': this.handleError(frame); break;
+                default: this.sendError(new VIOError(VIOError.Code.INVALID_DATA, 'Unknown frame type')); break;
+            }
+        } catch (error) {
+            this.emit('error', error instanceof VIOError ? error : new VIOError(VIOError.Code.INVALID_DATA, 'Failed to decode frame'));
+        }
+    }
+    protected async handleRaw(frame: Frame): Promise<void> {
+        this.emit('raw', frame);
+    }
+    protected async handleEvent(frame: Frame<'EVENT'>): Promise<void> {
+        try {
+            if (frame.mode == 'BINARY' || frame.mode == 'CUSTOM') {
+                const data = new Uint8Array(frame.data);
+                this.emit('event', frame.identifier.id, frame.mode, data);
+            } else if (frame.mode == 'JSON') {
+                const json = UTF8Codec.decode(new Uint8Array(frame.data));
+                const data = JSON.parse(json);
+                this.emit('event', frame.identifier.id, frame.mode, data);
+            } else if (frame.mode == 'LINE') {
+                const data = LineCodec.decode(frame.data);
+                this.emit('event', frame.identifier.id, frame.mode, data);
+            } else this.sendError(new VIOError(VIOError.Code.UNKNOWN_MODE, `Unknown mode: ${frame.mode}`));
+        } catch (error) { this.emit('error', error instanceof VIOError ? error : new VIOError(VIOError.Code.INVALID_DATA, 'Failed to process event data')); }
+    }
+    protected async handleRequest(frame: Frame<'REQUEST'>): Promise<void> {
+        if (!frame.identifier.id) return this.sendError(new VIOError(VIOError.Code.INVALID_HEADER, 'Request frame missing UUID'));
+        const uuid = frame.identifier.id;
+        try {
+            if (frame.mode == 'BINARY' || frame.mode == 'CUSTOM') {
+                const data = new Uint8Array(frame.data);
+                const done = (data: Uint8Array) => this.sendResponse(uuid, data);
+                const fail = (error: VIOError) => this.sendError(error, uuid);
+                this.emit('request', frame.mode, data, done, fail);
+            } else if (frame.mode == 'JSON') {
+                const json = UTF8Codec.decode(new Uint8Array(frame.data));
+                const data = JSON.parse(json);
+                const done = (data: any) => this.sendResponse(uuid, data);
+                const fail = (error: VIOError) => this.sendError(error, uuid);
+                this.emit('request', frame.mode, data, done, fail);
+            } else if (frame.mode == 'LINE') {
+                const data = LineCodec.decode(frame.data);
+                const done = (data: Record<string, string>) => this.sendResponse(uuid, data);
+                const fail = (error: VIOError) => this.sendError(error, uuid);
+                this.emit('request', frame.mode, data, done, fail);
+            } else this.sendError(new VIOError(VIOError.Code.UNKNOWN_MODE, `Unknown mode: ${frame.mode}`), uuid);
+        } catch (error) { this.sendError(new VIOError(VIOError.Code.INVALID_DATA, 'Failed to process request data'), uuid); }
+    }
+    protected async handleResponse(frame: Frame<'RESPONSE'>): Promise<void> {
+        if (!frame.identifier.id) return this.sendError(new VIOError(VIOError.Code.INVALID_HEADER, 'Response frame missing UUID'));
+        try {
+            if (frame.mode == 'BINARY' || frame.mode == 'CUSTOM') {
+                const data = new Uint8Array(frame.data);
+                this.mRequest.handle(frame.identifier.id, { mode: frame.mode, data });
+            } else if (frame.mode == 'JSON') {
+                const json = UTF8Codec.decode(new Uint8Array(frame.data));
+                const data = JSON.parse(json);
+                this.mRequest.handle(frame.identifier.id, { mode: 'JSON', data });
+            } else if (frame.mode == 'LINE') {
+                const data = LineCodec.decode(frame.data);
+                this.mRequest.handle(frame.identifier.id, { mode: 'LINE', data });
+            } else this.mRequest.handle(frame.identifier.id, undefined, new VIOError(VIOError.Code.UNKNOWN_MODE, `Unknown mode: ${frame.mode}`));
+        } catch (error) { this.mRequest.handle(frame.identifier.id, undefined, new VIOError(VIOError.Code.INVALID_DATA, 'Failed to process response data')); }
+    }
+    protected async handleError(frame: Frame<'ERROR'>): Promise<void> {
+        try {
+            if (frame.identifier.type === 'NONE') {
+                const error = new VIOError(VIOError.Code.INVALID_DATA, 'Unknown error');
+                return this.emit('error', error);
+            }
+            if (frame.mode == 'BINARY' || frame.mode == 'CUSTOM') {
+                const data = new Uint8Array(frame.data);
+                const error = new VIOError(VIOError.Code.INVALID_DATA, `Error response with binary data: ${data.length} bytes`);
+                this.mRequest.handle(frame.identifier.id, undefined, error);
+            } else if (frame.mode == 'JSON') {
+                const json = UTF8Codec.decode(new Uint8Array(frame.data));
+                const data = JSON.parse(json);
+                const error = new VIOError(VIOError.Code.INVALID_DATA, data.error || 'Unknown error');
+                this.mRequest.handle(frame.identifier.id, undefined, error);
+            } else if (frame.mode == 'LINE') {
+                const data = LineCodec.decode(frame.data);
+                const error = new VIOError(VIOError.Code.INVALID_DATA, `Error response with line data: ${JSON.stringify(data)}`);
+                this.mRequest.handle(frame.identifier.id, undefined, error);
+            } else {
+                const error = new VIOError(VIOError.Code.UNKNOWN_MODE, `Unknown mode: ${frame.mode}`);
+                this.mRequest.handle(frame.identifier.id, undefined, error);
+            }
+        } catch (error) {
+            const vioError = new VIOError(VIOError.Code.INVALID_DATA, 'Failed to process error data');
+            if (frame.identifier.type === 'UUID') this.mRequest.handle(frame.identifier.id, undefined, vioError);
+            this.emit('error', vioError);
+        }
+    }
+    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 sendEvent(name: string, data: any, mode?: 'LINE'): void {
+        const { content, finalMode } = this.serialize(data, mode);
+        const frame = Frame.encode('EVENT', finalMode, content, { type: 'STRING', id: name });
+        try { this.vTransport.emit('send', frame); }
+        catch (err) { this.vTransport.emit('transport:error', err instanceof Error ? err : new Error(String(err)), { stage: 'send', frameType: 'EVENT', info: { name } }); }
+    }
+
+    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 sendRequest(uuid: string, data?: any, mode?: 'LINE'): void {
+        const { content, finalMode } = this.serialize(data, mode);
+        const frame = Frame.encode('REQUEST', finalMode, content, { type: 'UUID', id: uuid });
+        try { this.vTransport.emit('send', frame); }
+        catch (err) { this.vTransport.emit('transport:error', err instanceof Error ? err : new Error(String(err)), { stage: 'send', frameType: 'REQUEST', uuid, info: {} }); }
+    }
+
+    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 sendResponse(uuid: string, data?: any, mode?: 'LINE'): void {
+        const { content, finalMode } = this.serialize(data, mode);
+        const frame = Frame.encode('RESPONSE', finalMode, content, { type: 'UUID', id: uuid });
+        try { this.vTransport.emit('send', frame); }
+        catch (err) { this.vTransport.emit('transport:error', err instanceof Error ? err : new Error(String(err)), { stage: 'send', frameType: 'RESPONSE', uuid, info: {} }); }
+    }
+    protected sendError(error: VIOError, uuid?: string): void {
+        const json = JSON.stringify({ error: error.message, code: error.code });
+        const content = UTF8Codec.encode(json);
+        const frame = Frame.encode('ERROR', 'JSON', content, uuid ? { type: 'UUID', id: uuid } : { type: 'NONE' });
+        try { this.vTransport.emit('send', frame); }
+        catch (err) { this.vTransport.emit('transport:error', err instanceof Error ? err : new Error(String(err)), { stage: 'send', frameType: 'ERROR', uuid, info: {} }); }
+    }
+    protected serialize(data: any, mode?: 'LINE'): { content: Uint8Array, finalMode: Frame.Mode } {
+        if (data instanceof Uint8Array) return { content: data, finalMode: 'BINARY' };
+        if (data instanceof ArrayBuffer) return { content: new Uint8Array(data), finalMode: 'BINARY' };
+        if (mode === 'LINE') return { content: LineCodec.encode(data), finalMode: 'LINE' };
+        const json = JSON.stringify(data ?? {});
+        return { content: UTF8Codec.encode(json), finalMode: 'JSON' };
+    }
+}
+export 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 default VIO;

package/src/VIOError.ts

@@ -0,0 +1,22 @@
+export class VIOError extends Error {
+    public name: string = 'VIOError';
+    public code: VIOError.Code;
+    public constructor(code: VIOError.Code, message: string) { super(message);
+        this.name = 'VIOError';
+        this.code = code;
+    }
+    public toString(): string {
+        return `${this.name} [${this.code}]: ${this.message}`;
+    }
+}
+export namespace VIOError {
+    export enum Code {
+        INVALID_HEADER = 'INVALID_HEADER',
+        INVALID_UUID = 'INVALID_UUID',
+        INVALID_DATA = 'INVALID_DATA',
+        UNKNOWN_TYPE = 'UNKNOWN_TYPE',
+        UNKNOWN_MODE = 'UNKNOWN_MODE',
+        BUFFER_TOO_SHORT = 'BUFFER_TOO_SHORT'
+    }
+}
+export default VIOError;

package/src/VIOStrict.ts

@@ -0,0 +1,123 @@
+import { Events, Schema } from "@netfeez/common";
+import RequestManager from "./RequestManager.js";
+import VIO from "./VIO.js";
+import VIOError from "./VIOError.js";
+import { Frame } from "./Frame.js";
+
+export const RRSchema = Schema.fromObject({
+    name: { type: 'string', required: true },
+    content: { type: 'object', required: true }
+});
+
+export class VIOStrict<
+    const T extends any,
+    const IEMap extends VIOStrict.EMap,
+    const OEMap extends VIOStrict.EMap,
+    const IRRMap extends VIOStrict.RRMap,
+    const ORRMap extends VIOStrict.RRMap
+> {
+    protected readonly VIO: VIO<T>;
+
+    protected readonly vioEmitter: Events.Emitter<VIOStrict.VIOEventMap>;
+    protected readonly eventEmitter: Events.Emitter<VIOStrict.EventMap<IEMap>>;
+    protected readonly requestEmitter: Events.Emitter<VIOStrict.ReqEventMap<IRRMap>>;
+
+    public constructor(
+        dependencies: RequestManager.DEPENDENCIES<T>,
+        protected inEMap: IEMap,
+        protected outEMap: OEMap,
+        protected inRRMap: IRRMap,
+        protected outRRMap: ORRMap
+    ) {
+        this.VIO = new VIO(dependencies);
+        this.vioEmitter = new Events.Emitter();
+        this.eventEmitter = new Events.Emitter();
+        this.requestEmitter = new Events.Emitter();
+
+        this.VIO.on('event', this.eventHandler.bind(this));
+        this.VIO.on('request', this.requestHandler.bind(this));
+        this.VIO.on('raw', (frame) => this.vioEmitter.emit('raw', frame));
+        this.VIO.on('error', (error) => this.vioEmitter.emit('error', error));
+    }
+
+    public get trp() { return this.VIO.transport; }
+    public get vio(): Events<VIOStrict.VIOEventMap> { return this.vioEmitter; }
+    public get evt(): Events<VIOStrict.EventMap<IEMap>> { return this.eventEmitter; }
+    public get rqt(): Events<VIOStrict.ReqEventMap<IRRMap>> { return this.requestEmitter; }
+
+    public event<Name extends string & keyof OEMap>(name: Name, data: OEMap[Name]['infer']): void {
+        const schema = this.outEMap[name];
+        if (!schema) throw new VIOError(VIOError.Code.UNKNOWN_TYPE, `Unknown event type: ${String(name)}`);
+        const processedData = schema.processData(data);
+        this.VIO.event(name, processedData);
+    }
+    public async request<id extends string & keyof ORRMap>(action: id, data: ORRMap[id]['request']['inferToProcess'], options?: RequestManager.SendOptions): Promise<ORRMap[id]['response']['infer']> {
+        const { request: RQS, response: RSS } = this.outRRMap[action];
+        if (!RQS) throw new VIOError(VIOError.Code.UNKNOWN_TYPE, `Unknown request type: ${String(action)}`);
+        if (!RSS) throw new VIOError(VIOError.Code.UNKNOWN_TYPE, `Unknown response type: ${String(action)}`);
+        const readyData = RQS.processData(data);
+        const toSend = RRSchema.processData({ name: action, content: readyData });
+        const response = await this.VIO.request(toSend, options);
+        if (response.mode !== 'JSON') throw new VIOError(VIOError.Code.INVALID_DATA, `Invalid response mode: ${response.mode}`);
+        const parsed = RRSchema.processData(response.data);
+        if (parsed.name !== action) throw new VIOError(VIOError.Code.INVALID_DATA, `Response action mismatch: expected ${action}, got ${parsed.name}`);
+        return RSS.processData(parsed.content);
+    }
+    public handle(data: ArrayBuffer | Uint8Array): void {
+        this.VIO.handle(data);
+    }
+    protected eventHandler(name: string, _mode: Frame.Mode, data: any): void {
+        const schema = this.inEMap[name];
+        if (!schema) throw new VIOError(VIOError.Code.UNKNOWN_TYPE, `Unknown event type: ${String(name)}`);
+        const processedData = schema.processData(data);
+        this.eventEmitter.emit(name, processedData);
+    }
+    protected requestHandler(mode: Frame.Mode, data: any, done: (data: any) => void, fail: (error: VIOError) => void): void {
+        if (mode !== 'JSON') return fail(new VIOError(VIOError.Code.INVALID_DATA, `Invalid request mode: ${mode}`));
+        const parsed = RRSchema.processData(data);
+        const { name, content } = parsed;
+        const rrEntry = this.inRRMap[name];
+        if (!rrEntry) return fail(new VIOError(VIOError.Code.UNKNOWN_TYPE, `Unknown request type: ${String(name)}`));
+        const {request: RQS, response: RSS } = rrEntry;
+        if (!RQS) return fail(new VIOError(VIOError.Code.UNKNOWN_TYPE, `Missing request schema for type: ${String(name)}`));
+        if (!RSS) return fail(new VIOError(VIOError.Code.UNKNOWN_TYPE, `Missing response schema for type: ${String(name)}`));
+        let processedRequest: typeof RQS.infer;
+        try { processedRequest = RQS.processData(content); }
+        catch (error) { return fail(new VIOError(VIOError.Code.INVALID_DATA, `Failed to process request data for type ${String(name)}: ${(error as Error).message}`)); }
+        const respond = (responseData: typeof RSS.inferToProcess) => {
+            let readyResponse: any;
+            try { readyResponse = RSS.processData(responseData); }
+            catch (error) { return fail(new VIOError(VIOError.Code.INVALID_DATA, `Failed to process response data for type ${String(name)}: ${(error as Error).message}`)); }
+            const toSend = RRSchema.processData({ name, content: readyResponse });
+            done(toSend);
+        };
+        this.requestEmitter.emit(name, processedRequest, respond, fail);
+    }
+}
+export namespace VIOStrict {
+    export interface EMap {
+        [name: string]: Schema<Schema.Property>;
+    }
+    export interface RREntry {
+        request: Schema<Schema.Definition.Object>;
+        response: Schema<Schema.Definition.Object>;
+    }
+    export interface RRMap {
+        [name: string]: RREntry;
+    }
+    export type VIOEventMap = {
+        error: [error: VIOError];
+        raw: [frame: Frame];
+    }
+    export type ReqEventMap<RRMap extends VIOStrict.RRMap> = {
+        [Name in string & keyof RRMap]: [
+            data: RRMap[Name]['request']['infer'],
+            respond: (data: RRMap[Name]['response']['inferToProcess']) => void,
+            reject: (error: VIOError) => void
+        ];
+    }
+    export type EventMap<EMap extends VIOStrict.EMap> = {
+        [Name in string & keyof EMap]: [data: EMap[Name]['infer']];
+    }
+}
+export default VIOStrict;

package/src/index.ts

@@ -0,0 +1,4 @@
+export { VIO, VIO as default } from "./VIO.js";
+export { VIOStrict } from "./VIOStrict.js";
+export { VIOError } from "./VIOError.js";
+export { Frame } from "./Frame.js";

package/src/support/LineParser.ts

@@ -0,0 +1,55 @@
+/**
+ * @module vortez-io
+ * @author NetFeez <netfeez.dev@gemail.com>
+ * @license Apache-2.0
+ * @description Provides encoding and decoding functionality for line-based content used in the Vortez IO protocol.
+ *              The LineCodec class allows for converting between a ContentMap (a mapping of string keys to string values) and a line-based text format where each key-value pair is represented as a block of text with specific formatting rules.
+ *              This is useful for encoding structured data in a human-readable format that can be easily transmitted and parsed within the Vortez IO protocol.
+ */
+import UTF8Codec from "./UTF8Codec.js";
+
+export class LineCodec {
+    /**
+     * Encodes a ContentMap into a Uint8Array containing line-based content.
+     * Each key-value pair in the ContentMap is converted into a block of text where the key is on the first line, followed by the value on subsequent lines. 
+     * Lines are separated by \r\n, and key-value pairs are separated by \r\n\r\n.
+     * If a value contains multiple lines, each subsequent line after the first will start with a space character to indicate that it is a continuation of the previous line.
+     * @param data A ContentMap object where each key is a string and each value is the corresponding string value to be encoded.
+     * @returns A Uint8Array containing the UTF-8 encoded line-based content representing the input ContentMap.
+     */
+    public static encode(data: LineCodec.ContentMap): Uint8Array {
+        let content = '';
+        for (const [key, value] of Object.entries(data)) {
+            const valueProcessed = value.replace(/\r\n/g, '\r\n ');
+            content += `${key}\r\n${valueProcessed}\r\n\r\n`;
+        }
+        return UTF8Codec.encode(content);
+    }
+    /**
+     * Decodes a Uint8Array containing line-based content into a ContentMap.
+     * The input is expected to be UTF-8 encoded and formatted with lines separated by \r\n, and key-value pairs separated by \r\n\r\n.
+     * Values that span multiple lines should have subsequent lines starting with a space character.
+     * @param content A Uint8Array containing the UTF-8 encoded line-based content.
+     * @returns A ContentMap object where each key is a string and each value is the corresponding string value from the input, with multi-line values properly concatenated.
+     */
+    public static decode(content: ArrayBuffer | Uint8Array): LineCodec.ContentMap {
+        const view = content instanceof ArrayBuffer ? new Uint8Array(content) : content;
+        const decodedContent = UTF8Codec.decode(view);
+        const lines = decodedContent.split('\r\n\r\n');
+        const result: LineCodec.ContentMap = {};
+        
+        for (const line of lines) {
+            const [key, ...valueParts] = line.split('\r\n');
+            if (!key) continue;
+            const value = valueParts.join('\r\n').replace(/\r\n /g, '\r\n');
+            result[key] = value;
+        }
+        return result;
+    }
+}
+export namespace LineCodec {
+    export interface ContentMap {
+        [key: string]: string;
+    }
+}
+export default LineCodec;