stelar-time-real 2.0.4 → 3.2.1

package/src/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @stelar-time-real Logger
+ * Zero-dependency structured logger with levels. Works in Node.js and browser.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface LoggerOptions {
+    level?: LogLevel;
+    timestamp?: boolean;
+    prefix?: string;
+    colorize?: boolean;
+}
+export declare class Logger {
+    private level;
+    private timestamp;
+    private prefix;
+    private colorize;
+    constructor(options?: LoggerOptions);
+    setLevel(level: LogLevel): this;
+    private shouldLog;
+    private format;
+    private _write;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** No-op logger for zero overhead when logging is disabled */
+export declare const NULL_LOGGER: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAUtE,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAU;gBAEd,OAAO,GAAE,aAAkB;IAOvC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAK/B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,MAAM;IA2Bd,OAAO,CAAC,MAAM;IAed,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAG7D;AAED,8DAA8D;AAC9D,eAAO,MAAM,WAAW,EAAE,MAAwC,CAAC"}

package/src/logger.js

@@ -0,0 +1,98 @@
+/**
+ * @stelar-time-real Logger
+ * Zero-dependency structured logger with levels. Works in Node.js and browser.
+ */
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+const COLORS = {
+    debug: '\x1b[36m',
+    info: '\x1b[32m',
+    warn: '\x1b[33m',
+    error: '\x1b[31m',
+    reset: '\x1b[0m',
+};
+const isBrowser = typeof window !== 'undefined' && typeof process === 'undefined';
+export class Logger {
+    constructor(options = {}) {
+        this.level = options.level || 'info';
+        this.timestamp = options.timestamp !== false;
+        this.prefix = options.prefix || 'stelar';
+        this.colorize = isBrowser ? false : (options.colorize !== false);
+    }
+    setLevel(level) {
+        this.level = level;
+        return this;
+    }
+    shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+    }
+    format(level, message, meta) {
+        const parts = [];
+        if (this.timestamp) {
+            parts.push(new Date().toISOString());
+        }
+        if (this.colorize) {
+            const c = COLORS[level] || '';
+            parts.push(`${c}[${this.prefix}:${level}]${COLORS.reset}`);
+        }
+        else {
+            parts.push(`[${this.prefix}:${level}]`);
+        }
+        parts.push(message);
+        if (meta && Object.keys(meta).length > 0) {
+            try {
+                parts.push(JSON.stringify(meta));
+            }
+            catch {
+                parts.push('[meta: circular]');
+            }
+        }
+        return parts.join(' ');
+    }
+    _write(level, target, message, meta) {
+        const formatted = this.format(level, message, meta);
+        if (isBrowser) {
+            switch (level) {
+                case 'debug':
+                    console.debug(formatted);
+                    break;
+                case 'info':
+                    console.info(formatted);
+                    break;
+                case 'warn':
+                    console.warn(formatted);
+                    break;
+                case 'error':
+                    console.error(formatted);
+                    break;
+            }
+        }
+        else {
+            const stream = target === 'stderr' ? process.stderr : process.stdout;
+            stream.write(formatted + '\n');
+        }
+    }
+    debug(message, meta) {
+        if (this.shouldLog('debug'))
+            this._write('debug', 'stdout', message, meta);
+    }
+    info(message, meta) {
+        if (this.shouldLog('info'))
+            this._write('info', 'stdout', message, meta);
+    }
+    warn(message, meta) {
+        if (this.shouldLog('warn'))
+            this._write('warn', 'stderr', message, meta);
+    }
+    error(message, meta) {
+        if (this.shouldLog('error'))
+            this._write('error', 'stderr', message, meta);
+    }
+}
+/** No-op logger for zero overhead when logging is disabled */
+export const NULL_LOGGER = new Logger({ level: 'silent' });

package/src/logger.ts

@@ -0,0 +1,115 @@
+/**
+ * @stelar-time-real Logger
+ * Zero-dependency structured logger with levels. Works in Node.js and browser.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  timestamp?: boolean;
+  prefix?: string;
+  colorize?: boolean;
+}
+
+const COLORS: Record<string, string> = {
+  debug: '\x1b[36m',
+  info: '\x1b[32m',
+  warn: '\x1b[33m',
+  error: '\x1b[31m',
+  reset: '\x1b[0m',
+};
+
+const isBrowser = typeof window !== 'undefined' && typeof process === 'undefined';
+
+export class Logger {
+  private level: LogLevel;
+  private timestamp: boolean;
+  private prefix: string;
+  private colorize: boolean;
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level || 'info';
+    this.timestamp = options.timestamp !== false;
+    this.prefix = options.prefix || 'stelar';
+    this.colorize = isBrowser ? false : (options.colorize !== false);
+  }
+
+  setLevel(level: LogLevel): this {
+    this.level = level;
+    return this;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+  }
+
+  private format(level: string, message: string, meta?: Record<string, unknown>): string {
+    const parts: string[] = [];
+
+    if (this.timestamp) {
+      parts.push(new Date().toISOString());
+    }
+
+    if (this.colorize) {
+      const c = COLORS[level] || '';
+      parts.push(`${c}[${this.prefix}:${level}]${COLORS.reset}`);
+    } else {
+      parts.push(`[${this.prefix}:${level}]`);
+    }
+
+    parts.push(message);
+
+    if (meta && Object.keys(meta).length > 0) {
+      try {
+        parts.push(JSON.stringify(meta));
+      } catch {
+        parts.push('[meta: circular]');
+      }
+    }
+
+    return parts.join(' ');
+  }
+
+  private _write(level: string, target: 'stdout' | 'stderr', message: string, meta?: Record<string, unknown>): void {
+    const formatted = this.format(level, message, meta);
+    if (isBrowser) {
+      switch (level) {
+        case 'debug': console.debug(formatted); break;
+        case 'info': console.info(formatted); break;
+        case 'warn': console.warn(formatted); break;
+        case 'error': console.error(formatted); break;
+      }
+    } else {
+      const stream = target === 'stderr' ? process.stderr : process.stdout;
+      stream.write(formatted + '\n');
+    }
+  }
+
+  debug(message: string, meta?: Record<string, unknown>): void {
+    if (this.shouldLog('debug')) this._write('debug', 'stdout', message, meta);
+  }
+
+  info(message: string, meta?: Record<string, unknown>): void {
+    if (this.shouldLog('info')) this._write('info', 'stdout', message, meta);
+  }
+
+  warn(message: string, meta?: Record<string, unknown>): void {
+    if (this.shouldLog('warn')) this._write('warn', 'stderr', message, meta);
+  }
+
+  error(message: string, meta?: Record<string, unknown>): void {
+    if (this.shouldLog('error')) this._write('error', 'stderr', message, meta);
+  }
+}
+
+/** No-op logger for zero overhead when logging is disabled */
+export const NULL_LOGGER: Logger = new Logger({ level: 'silent' });

package/src/protocol.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @stelar-time-real Binary Protocol
+ *
+ * Frame format:
+ * [4B totalLen BE][1B type][2B eventLen BE][eventLen bytes event][payload]
+ *
+ * Min frame: 7 bytes (header only). Max event name: 256 bytes.
+ */
+export declare const FRAME_JSON = 1;
+export declare const FRAME_BINARY = 2;
+export declare const FRAME_PING = 3;
+export declare const FRAME_PONG = 4;
+export declare const FRAME_ACK_REQ = 5;
+export declare const FRAME_ACK_RES = 6;
+export declare const FRAME_CONNECT = 7;
+export declare const FRAME_DISCONNECT = 8;
+export declare const FRAME_JOIN = 9;
+export declare const FRAME_LEAVE = 10;
+export declare const FRAME_ERROR = 11;
+/** Max event name length in bytes */
+export declare const MAX_EVENT_LENGTH = 256;
+/** Default max frame size: 10 MB */
+export declare const DEFAULT_MAX_FRAME_SIZE: number;
+export declare const HEADER_SIZE = 7;
+export interface ParsedFrame {
+    type: number;
+    event: string;
+    payload: Buffer;
+}
+export declare class ProtocolError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+/** Validates event name format. Throws ProtocolError on invalid input. */
+export declare function validateEventName(event: string): void;
+export declare function encodeJsonFrame(event: string, data: unknown, maxFrameSize?: number): Buffer;
+export declare function encodeBinaryFrame(event: string, data: Uint8Array | Buffer, maxFrameSize?: number): Buffer;
+export declare function encodePingFrame(): Buffer;
+export declare function encodePongFrame(): Buffer;
+export declare function encodeAckReqFrame(ackName: string, data: unknown, maxFrameSize?: number): Buffer;
+export declare function encodeAckResFrame(ackName: string, data: unknown, maxFrameSize?: number): Buffer;
+export declare function encodeConnectFrame(clientId: string): Buffer;
+export declare function encodeDisconnectFrame(): Buffer;
+export declare function encodeJoinFrame(room: string, maxFrameSize?: number): Buffer;
+export declare function encodeLeaveFrame(room: string): Buffer;
+export declare function encodeErrorFrame(message: string): Buffer;
+/** Streaming frame parser for TCP connections. Buffers partial data and emits complete frames. */
+export declare class FrameParser {
+    private buf;
+    private maxFrameSize;
+    private totalBytesReceived;
+    constructor(maxFrameSize?: number);
+    feed(data: Buffer): ParsedFrame[];
+    reset(): void;
+    getBytesReceived(): number;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/src/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,IAAa,CAAC;AACrC,eAAO,MAAM,YAAY,IAAW,CAAC;AACrC,eAAO,MAAM,UAAU,IAAa,CAAC;AACrC,eAAO,MAAM,UAAU,IAAa,CAAC;AACrC,eAAO,MAAM,aAAa,IAAU,CAAC;AACrC,eAAO,MAAM,aAAa,IAAU,CAAC;AACrC,eAAO,MAAM,aAAa,IAAU,CAAC;AACrC,eAAO,MAAM,gBAAgB,IAAO,CAAC;AACrC,eAAO,MAAM,UAAU,IAAa,CAAC;AACrC,eAAO,MAAM,WAAW,KAAY,CAAC;AACrC,eAAO,MAAM,WAAW,KAAY,CAAC;AAErC,qCAAqC;AACrC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,oCAAoC;AACpC,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AACvD,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAC/B,IAAI,EAAE,MAAM,CAAC;gBACR,OAAO,EAAE,MAAM,EAAE,IAAI,SAAmB;CAKrD;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAgBrD;AA6BD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3F;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzG;AAED,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/F;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/F;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,kGAAkG;AAClG,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAA2B;IACtC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,YAAY,SAAyB;IAIjD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE;IA8DjC,KAAK,IAAI,IAAI;IAKb,gBAAgB,IAAI,MAAM;CAG3B"}

package/src/protocol.js

@@ -0,0 +1,193 @@
+/**
+ * @stelar-time-real Binary Protocol
+ *
+ * Frame format:
+ * [4B totalLen BE][1B type][2B eventLen BE][eventLen bytes event][payload]
+ *
+ * Min frame: 7 bytes (header only). Max event name: 256 bytes.
+ */
+export const FRAME_JSON = 0x01;
+export const FRAME_BINARY = 0x02;
+export const FRAME_PING = 0x03;
+export const FRAME_PONG = 0x04;
+export const FRAME_ACK_REQ = 0x05;
+export const FRAME_ACK_RES = 0x06;
+export const FRAME_CONNECT = 0x07;
+export const FRAME_DISCONNECT = 0x08;
+export const FRAME_JOIN = 0x09;
+export const FRAME_LEAVE = 0x0A;
+export const FRAME_ERROR = 0x0B;
+/** Max event name length in bytes */
+export const MAX_EVENT_LENGTH = 256;
+/** Default max frame size: 10 MB */
+export const DEFAULT_MAX_FRAME_SIZE = 10 * 1024 * 1024;
+export const HEADER_SIZE = 7;
+export class ProtocolError extends Error {
+    constructor(message, code = 'PROTOCOL_ERROR') {
+        super(message);
+        this.name = 'ProtocolError';
+        this.code = code;
+    }
+}
+/** Validates event name format. Throws ProtocolError on invalid input. */
+export function validateEventName(event) {
+    if (typeof event !== 'string') {
+        throw new ProtocolError('Event name must be a string', 'INVALID_EVENT');
+    }
+    if (event.length === 0) {
+        throw new ProtocolError('Event name cannot be empty', 'EMPTY_EVENT');
+    }
+    if (event.length > MAX_EVENT_LENGTH) {
+        throw new ProtocolError(`Event name exceeds ${MAX_EVENT_LENGTH} bytes`, 'EVENT_TOO_LONG');
+    }
+    if (!/^[\w\-./:]+$/.test(event)) {
+        throw new ProtocolError('Event name contains invalid characters', 'INVALID_EVENT_CHARS');
+    }
+    if (['ping', 'pong', 'connect', 'disconnect', 'error'].includes(event)) {
+        throw new ProtocolError(`Event "${event}" is reserved`, 'RESERVED_EVENT');
+    }
+}
+function validatePayloadSize(payload, maxSize) {
+    if (payload.length > maxSize) {
+        throw new ProtocolError(`Payload exceeds max size (${maxSize} bytes)`, 'PAYLOAD_TOO_LARGE');
+    }
+}
+function encodeFrame(type, event, payload, maxFrameSize = DEFAULT_MAX_FRAME_SIZE) {
+    if (event.length > MAX_EVENT_LENGTH) {
+        throw new ProtocolError(`Event name exceeds ${MAX_EVENT_LENGTH} bytes`, 'EVENT_TOO_LONG');
+    }
+    const eventBuf = Buffer.from(event, 'utf8');
+    const totalLen = HEADER_SIZE + eventBuf.length + payload.length;
+    if (totalLen > maxFrameSize) {
+        throw new ProtocolError(`Frame exceeds max size (${maxFrameSize} bytes)`, 'FRAME_TOO_LARGE');
+    }
+    const frame = Buffer.alloc(totalLen);
+    frame.writeUInt32BE(totalLen, 0);
+    frame[4] = type;
+    frame.writeUInt16BE(eventBuf.length, 5);
+    if (eventBuf.length > 0)
+        eventBuf.copy(frame, HEADER_SIZE);
+    if (payload.length > 0)
+        payload.copy(frame, HEADER_SIZE + eventBuf.length);
+    return frame;
+}
+export function encodeJsonFrame(event, data, maxFrameSize) {
+    validateEventName(event);
+    const payload = Buffer.from(JSON.stringify(data), 'utf8');
+    if (maxFrameSize)
+        validatePayloadSize(payload, maxFrameSize);
+    return encodeFrame(FRAME_JSON, event, payload, maxFrameSize);
+}
+export function encodeBinaryFrame(event, data, maxFrameSize) {
+    validateEventName(event);
+    const payload = Buffer.from(data);
+    if (maxFrameSize)
+        validatePayloadSize(payload, maxFrameSize);
+    return encodeFrame(FRAME_BINARY, event, payload, maxFrameSize);
+}
+export function encodePingFrame() {
+    const f = Buffer.alloc(HEADER_SIZE);
+    f.writeUInt32BE(HEADER_SIZE, 0);
+    f[4] = FRAME_PING;
+    f.writeUInt16BE(0, 5);
+    return f;
+}
+export function encodePongFrame() {
+    const f = Buffer.alloc(HEADER_SIZE);
+    f.writeUInt32BE(HEADER_SIZE, 0);
+    f[4] = FRAME_PONG;
+    f.writeUInt16BE(0, 5);
+    return f;
+}
+export function encodeAckReqFrame(ackName, data, maxFrameSize) {
+    const payload = Buffer.from(JSON.stringify(data), 'utf8');
+    if (maxFrameSize)
+        validatePayloadSize(payload, maxFrameSize);
+    return encodeFrame(FRAME_ACK_REQ, ackName, payload, maxFrameSize);
+}
+export function encodeAckResFrame(ackName, data, maxFrameSize) {
+    const payload = Buffer.from(JSON.stringify(data), 'utf8');
+    if (maxFrameSize)
+        validatePayloadSize(payload, maxFrameSize);
+    return encodeFrame(FRAME_ACK_RES, ackName, payload, maxFrameSize);
+}
+export function encodeConnectFrame(clientId) {
+    return encodeFrame(FRAME_CONNECT, 'connect', Buffer.from(clientId, 'utf8'));
+}
+export function encodeDisconnectFrame() {
+    const f = Buffer.alloc(HEADER_SIZE);
+    f.writeUInt32BE(HEADER_SIZE, 0);
+    f[4] = FRAME_DISCONNECT;
+    f.writeUInt16BE(0, 5);
+    return f;
+}
+export function encodeJoinFrame(room, maxFrameSize) {
+    const payload = Buffer.from(room, 'utf8');
+    return encodeFrame(FRAME_JOIN, 'join-room', payload, maxFrameSize);
+}
+export function encodeLeaveFrame(room) {
+    const payload = room ? Buffer.from(room, 'utf8') : Buffer.alloc(0);
+    return encodeFrame(FRAME_LEAVE, 'leave-room', payload);
+}
+export function encodeErrorFrame(message) {
+    return encodeFrame(FRAME_ERROR, 'error', Buffer.from(message, 'utf8'));
+}
+/** Streaming frame parser for TCP connections. Buffers partial data and emits complete frames. */
+export class FrameParser {
+    constructor(maxFrameSize = DEFAULT_MAX_FRAME_SIZE) {
+        this.buf = Buffer.alloc(0);
+        this.totalBytesReceived = 0;
+        this.maxFrameSize = maxFrameSize;
+    }
+    feed(data) {
+        this.totalBytesReceived += data.length;
+        this.buf = Buffer.concat([this.buf, data]);
+        if (this.buf.length > this.maxFrameSize * 2) {
+            this.buf = Buffer.alloc(0);
+            throw new ProtocolError(`Input buffer exceeded limit (${this.maxFrameSize * 2} bytes)`, 'BUFFER_OVERFLOW');
+        }
+        const frames = [];
+        while (this.buf.length >= HEADER_SIZE) {
+            const totalLen = this.buf.readUInt32BE(0);
+            if (totalLen < HEADER_SIZE) {
+                this.buf = Buffer.alloc(0);
+                throw new ProtocolError(`Invalid frame size: ${totalLen}`, 'INVALID_FRAME_SIZE');
+            }
+            if (totalLen > this.maxFrameSize) {
+                this.buf = Buffer.alloc(0);
+                throw new ProtocolError(`Frame exceeds max size (${this.maxFrameSize} bytes)`, 'FRAME_TOO_LARGE');
+            }
+            if (this.buf.length < totalLen)
+                break;
+            const type = this.buf[4];
+            const eventLen = this.buf.readUInt16BE(5);
+            if (HEADER_SIZE + eventLen > totalLen) {
+                this.buf = Buffer.alloc(0);
+                throw new ProtocolError('Event length exceeds frame bounds', 'INVALID_EVENT_LENGTH');
+            }
+            if (eventLen > MAX_EVENT_LENGTH) {
+                this.buf = Buffer.alloc(0);
+                throw new ProtocolError(`Event name exceeds ${MAX_EVENT_LENGTH} bytes`, 'EVENT_TOO_LONG');
+            }
+            const event = eventLen > 0
+                ? this.buf.subarray(HEADER_SIZE, HEADER_SIZE + eventLen).toString('utf8')
+                : '';
+            const payloadStart = HEADER_SIZE + eventLen;
+            const payload = totalLen > payloadStart
+                ? Buffer.from(this.buf.subarray(payloadStart, totalLen))
+                : Buffer.alloc(0);
+            frames.push({ type, event, payload });
+            this.buf = totalLen < this.buf.length
+                ? Buffer.from(this.buf.subarray(totalLen))
+                : Buffer.alloc(0);
+        }
+        return frames;
+    }
+    reset() {
+        this.buf = Buffer.alloc(0);
+        this.totalBytesReceived = 0;
+    }
+    getBytesReceived() {
+        return this.totalBytesReceived;
+    }
+}