@qsocket/protocol/dist/index.d.cts

QSocket Protocol: A versatile protocol for transmitting messages of any type in buffer format, designed exclusively for the QSocket ecosystem. Enables efficient, high-speed data transfer between processes and across client-server connections.

/**
 * Message type options.
 * Defines the primary message type: data transfer or control.
 */
declare enum EQSocketProtocolMessageType {
    /**
     * Data transfer protocol. Message carries a payload with data.
     * Binary value: 00
     */
    DATA = 0,
    /**
     * Control protocol. Message is intended for connection management.
     * Binary value: 01
     */
    CONTROL = 1,
    /**
     * Acknowledgment protocol.
     * Confirms delivery of a message.
     * Binary value: 10
     */
    ACK = 2
}
/**
 * Payload content format.
 * Used to specify the type of content in the QSOCKET protocol.
 */
declare enum EQSocketProtocolContentType {
    /**
     * No data. Used when payload is not required.
     * Binary value: 000
     */
    UNDEFINED = 0,
    /**
     * Null data. Explicitly indicates no value in payload.
     * Binary value: 001
     */
    NULL = 1,
    /**
     * Boolean value. Payload is interpreted as a boolean.
     * Binary value: 010
     */
    BOOLEAN = 2,
    /**
     * Numeric value. Payload is interpreted as a number.
     * Binary value: 011
     */
    NUMBER = 3,
    /**
     * String. Payload is interpreted as a UTF-8 encoded string.
     * Binary value: 100
     */
    STRING = 4,
    /**
     * Object. Payload represents a serialized JSON object.
     * Binary value: 101
     */
    JSON = 5,
    /**
     * Buffer. Payload is transmitted as binary data (Buffer).
     * Binary value: 110
     */
    BUFFER = 6
}

/**
 * @description Data types that can be transmitted through the Q-SOCKET protocol.
 * Includes primitives, a universal JSON type, and Buffer.
 *
 * - `undefined/void`: Absence of value.
 * - `null`: Explicit indication of no value.
 * - `boolean`: Logical `true` or `false`.
 * - `number`: Numeric value.
 * - `string`: Text value.
 * - `IJSON`: Universal JSON type, including primitives, arrays, and objects.
 * - `Buffer`: Binary data.
 */
type TQSocketProtocolPayloadData = undefined | void | null | boolean | number | string | object | Array<undefined | null | boolean | number | string | object> | Buffer;
/**
 * @description Payload Interface
 * Contains data as well as information for further processing
 */
interface IQSocketProtocolPayload<T extends TQSocketProtocolPayloadData = TQSocketProtocolPayloadData> {
    /**
     * Data to be transmitted.
     */
    data: T;
    /**
     * Specifies the data format of the payload.
     * Defines the type of data in the `payload` field, such as `STRING`, `JSON`, or `BUFFER`.
     */
    'Content-Type': EQSocketProtocolContentType;
}
/**
 * @description Base metadata interface for messages in the Q-SOCKET protocol.
 */
interface IQSocketProtocolMessageMetaBase {
    /**
     * Type of the message.
     */
    type: EQSocketProtocolMessageType;
    /**
     * Unique identifier for the message.
     * Used for tracking messages and linking responses to requests.
     */
    uuid: string;
}
/**
 * @description Metadata for data messages.
 * Extends the base metadata interface to include specific details for data messages.
 */
interface IQSocketProtocolMessageMetaData extends IQSocketProtocolMessageMetaBase {
    /**
     * Specifies that this is a data message type.
     */
    type: EQSocketProtocolMessageType.DATA;
    /**
     * Namespace associated with the event.
     * Provides a logical separation of events, e.g., separating chat rooms.
     */
    namespace: string;
    /**
     * Event identifier within the namespace.
     */
    event: string;
}
/**
 * @description Metadata for acknowledgment messages.
 * Used to confirm message receipt or processing.
 */
interface IQSocketProtocolMessageMetaAck extends IQSocketProtocolMessageMetaBase {
    /**
     * Specifies that this is an acknowledgment message type.
     */
    type: EQSocketProtocolMessageType.ACK;
}
/**
 * @description Metadata for control messages.
 * Used for managing connections, session states, or other control operations.
 */
interface IQSocketProtocolMessageMetaControl extends IQSocketProtocolMessageMetaBase {
    /**
     * Specifies that this is a control message type.
     */
    type: EQSocketProtocolMessageType.CONTROL;
}
type IQSocketProtocolMessageMeta = IQSocketProtocolMessageMetaData | IQSocketProtocolMessageMetaAck | IQSocketProtocolMessageMetaControl;
/**
 * @description General interface for all QSOCKET protocol variants.
 *
 * Represents the essential properties that all messages in the QSOCKET protocol must have.
 */
interface IQSocketProtocolChunk<M extends IQSocketProtocolMessageMeta = IQSocketProtocolMessageMeta, P extends IQSocketProtocolPayload = IQSocketProtocolPayload> {
    /**
     * Contains metadata for the message.
     * Provides necessary information like namespace, event name, timestamps, etc.
     */
    meta: M;
    /**
     * Payload data of the message.
     */
    payload: P;
}
/**
 * @description A complete Q-SOCKET protocol message, represented as an array of chunks.
 */
type IQSocketProtocolMessage<T extends IQSocketProtocolMessageMeta = IQSocketProtocolMessageMeta, P extends IQSocketProtocolPayload = IQSocketProtocolPayload> = IQSocketProtocolChunk<T, P>[];

/**
 * Represents an error that occurred during the encoding process in the QSocketProtocol.
 * Extends the base `Error` class to provide more context specific to encoding issues.
 */
declare class QSocketProtocolEncodeError extends Error {
    originalError?: Error | undefined;
    /**
     * Creates an instance of QSocketProtocolEncodeError.
     *
     * @param message - A descriptive error message.
     * @param originalError - (Optional) The original error that caused this encoding error, if any.
     */
    constructor(message: string, originalError?: Error | undefined);
}
/**
 * Represents an error that occurred during the decoding process in the QSocketProtocol.
 * Extends the base `Error` class to provide more context specific to decoding issues.
 */
declare class QSocketProtocolDecodeError extends Error {
    originalError?: Error | undefined;
    /**
     * Creates an instance of QSocketProtocolDecodeError.
     *
     * @param message - A descriptive error message.
     * @param originalError - (Optional) The original error that caused this decoding error, if any.
     */
    constructor(message: string, originalError?: Error | undefined);
}

/**
 * Serializes an IQSocketProtocolMessage into a single Uint8Array.
 *
 * @param {IQSocketProtocolMessage} message - The message to serialize.
 * @returns {Uint8Array} The serialized binary representation of the message.
 * @throws {QSocketProtocolEncodeError} If an encoding error occurs.
 */
declare function to(message: IQSocketProtocolMessage): Uint8Array;
/**
 * Deserializes a Uint8Array into an IQSocketProtocolMessage.
 *
 * @param {Uint8Array} buffer - The binary data to deserialize.
 * @returns {IQSocketProtocolMessage} The deserialized message.
 * @throws {QSocketProtocolDecodeError} If a decoding error occurs.
 */
declare function from(buffer: Uint8Array): IQSocketProtocolMessage;

export { EQSocketProtocolContentType, EQSocketProtocolMessageType, type IQSocketProtocolChunk, type IQSocketProtocolMessage, type IQSocketProtocolMessageMetaAck, type IQSocketProtocolMessageMetaControl, type IQSocketProtocolMessageMetaData, type IQSocketProtocolPayload, QSocketProtocolDecodeError, QSocketProtocolEncodeError, type TQSocketProtocolPayloadData, from, to };