stelar-time-real 2.0.4 → 3.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stelar-time-real",
-  "version": "2.0.4",
-  "description": "WebSocket liviano y rápido sin dependendas en TypeScript. Alternativa a socket.io, namespaces, ACKs y archivos binarios.",
+  "version": "3.2.0",
+  "description": "Zero-dependency production real-time library. Custom binary TCP + manual WebSocket. No ws package. Rate limiting (custom/per-event/per-client), hooks, custom IP tracker, custom health check, runtime config, rooms, ACKs, middleware, TLS/SSL.",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "type": "module",
@@ -12,11 +12,17 @@
   "keywords": [
     "websocket",
     "real-time",
-    "socket",
-    " realtime",
+    "realtime",
     "stelar",
     "chat",
-    "webserver"
+    "webserver",
+    "tcp",
+    "binary-protocol",
+    "zero-dependency",
+    "custom-protocol",
+    "production",
+    "rate-limiting",
+    "health-check"
   ],
   "author": "Stelar",
   "license": "MIT",
@@ -36,11 +42,9 @@
   "files": [
     "src"
   ],
-  "dependencies": {
-    "ws": "^8.14.0"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "@types/ws": "^8.5.10",
+    "@types/node": "^22.0.0",
     "typescript": "^5.3.0"
   }
-}
+}

package/src/client.d.ts

@@ -1,31 +1,124 @@
+/**
+ * @stelar-time-real Client
+ *
+ * Dual-environment: Browser (native WebSocket) + Node.js (manual WS or TCP binary).
+ * No external dependencies.
+ */
+import { Logger, type LogLevel } from './logger.js';
+export interface StelarClientHooks {
+    /** Return false to cancel the emit. */
+    onBeforeEmit?: (info: {
+        event: string;
+        data: unknown;
+    }) => boolean | void;
+    /** Called on every incoming message. */
+    onMessage?: (info: {
+        event: string;
+        data: unknown;
+        isBinary: boolean;
+    }) => void;
+    /** Called when connection state changes. */
+    onStateChange?: (info: {
+        from: ConnectionState;
+        to: ConnectionState;
+    }) => void;
+    /** Return a custom delay (ms) to override built-in backoff. */
+    onReconnectDelay?: (info: {
+        attempt: number;
+        defaultDelay: number;
+    }) => number | void;
+    /** Called when a message is queued while disconnected. */
+    onMessageQueued?: (info: {
+        event: string;
+        data: unknown;
+        queueSize: number;
+    }) => void;
+    /** Called after queued messages are flushed on reconnection. */
+    onQueueDrained?: (info: {
+        count: number;
+    }) => void;
+    /** Called on any client-side error. */
+    onError?: (info: {
+        error: Error;
+        context: string;
+    }) => void;
+}
 export interface StelarClientOptions {
     reconnection?: boolean;
     reconnectionAttempts?: number;
     reconnectionDelay?: number;
+    maxReconnectionDelay?: number;
     heartbeatInterval?: number;
     ackTimeout?: number;
+    mode?: 'ws' | 'tcp';
+    maxPayloadSize?: number;
+    maxFrameSize?: number;
+    messageQueueSize?: number;
+    logger?: Logger | LogLevel | false;
+    tls?: boolean;
+    rejectUnauthorized?: boolean;
+    headers?: Record<string, string>;
+    /** Custom backoff function: (attempt, baseDelay, maxDelay) => delayMs */
+    customReconnectDelay?: (attempt: number, baseDelay: number, maxDelay: number) => number;
+    hooks?: StelarClientHooks;
 }
 export interface StelarEmitOptions {
     ack?: string;
 }
 export type StelarEventHandler = (data: unknown) => void;
-export type StelarBinaryHandler = (buffer: ArrayBuffer) => void;
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 declare class StelarClient {
     private url;
     private options;
-    private ws;
     private events;
     private _wildcardHandler;
-    private connected;
-    private id;
+    private _acks;
+    private _state;
     private _reconnectAttempts;
     private _hbTimer;
     private _isManualClose;
-    private _acks;
+    private id;
+    private _messageQueue;
+    private _reconnectTimer;
+    private _messagesSent;
+    private _messagesReceived;
+    private _connectTime;
+    private _lastError;
+    private _ws;
+    private _nodeSocket;
+    private _wsParser;
+    private _tcpSocket;
+    private _tcpParser;
+    private log;
     constructor(urlOrPort?: string | number, options?: StelarClientOptions);
+    getState(): ConnectionState;
+    getId(): string | null;
+    getUrl(): string;
+    getMessagesSent(): number;
+    getMessagesReceived(): number;
+    getLastError(): Error | null;
+    getQueueSize(): number;
+    getConnectTime(): number;
     setUrl(url: string): this;
+    /** Update client options at runtime. Changes take effect immediately. */
+    updateOptions(options: Partial<StelarClientOptions>): this;
+    /** Read-only snapshot of current client options. */
+    getOptions(): Readonly<{
+        reconnection: boolean;
+        reconnectionAttempts: number;
+        reconnectionDelay: number;
+        maxReconnectionDelay: number;
+        heartbeatInterval: number;
+        ackTimeout: number;
+        mode: string;
+        maxPayloadSize: number;
+        messageQueueSize: number;
+        hasCustomReconnectDelay: boolean;
+        hooks: string[];
+    }>;
     on(event: string, handler: StelarEventHandler): this;
     off(event: string, handler: StelarEventHandler): this;
+    once(event: string, handler: StelarEventHandler): this;
     onAll(handler: (data: {
         event: string;
         data: unknown;
@@ -33,20 +126,34 @@ declare class StelarClient {
         buffer?: ArrayBuffer;
     }) => void): this;
     onAck(name: string, handler: StelarEventHandler): this;
+    removeAllListeners(event?: string): this;
     emit(event: string, data?: unknown, opts?: StelarEmitOptions): this;
     emitBinary(event: string, data: ArrayBuffer): this;
     sendFile(file: ArrayBuffer): this;
     sendImage(blob: ArrayBuffer): this;
+    /** Send a request and wait for an ACK response. Rejects on timeout. */
     request(event: string, data: unknown, ackName: string): Promise<unknown>;
     joinRoom(room: string): this;
-    leaveRoom(): this;
+    leaveRoom(room: string): this;
     private startHeartbeat;
     private stopHeartbeat;
-    private _connect;
+    private _getReconnectDelay;
+    private _drainQueue;
+    private _setState;
+    private _cleanupAcks;
+    private _fullCleanup;
     connect(callback?: () => void): this;
     disconnect(): this;
     isConnected(): boolean;
-    getUrl(): string;
+    private _connectBrowser;
+    private _handleBrowserMessage;
+    private _connectNodeWS;
+    private _processNodeWSData;
+    private _handleNodeWSFrame;
+    /** TCP mode: connects to WS port + 1 by convention. */
+    private _connectTCP;
+    private _handleTCPFrame;
+    private _tryReconnect;
 }
 export default StelarClient;
 //# sourceMappingURL=client.d.ts.map

package/src/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;AAEhE,cAAM,YAAY;IAChB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,gBAAgB,CAA6G;IACrI,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAyC;gBAE1C,SAAS,GAAE,MAAM,GAAG,MAAyB,EAAE,OAAO,GAAE,mBAAwB;IAkB5F,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAKpD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAOrD,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI;IAKhH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAKtD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,GAAG,IAAI;IAWvE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IAalD,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIjC,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B,SAAS,IAAI,IAAI;IAKjB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,QAAQ;IAgFhB,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IAapC,UAAU,IAAI,IAAI;IAOlB,WAAW,IAAI,OAAO;IAItB,MAAM,IAAI,MAAM;CAGjB;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"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"}