nexabase-console 2.1.2 → 2.1.3

package/dist/transport/WebSocketClient.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport/WebSocketClient.test.js

@@ -0,0 +1,454 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const WebSocketClient_1 = require("./WebSocketClient");
+// Mock Socket.IO Socket implementation
+class MockSocket {
+    constructor() {
+        this.id = `mock_socket_${Math.random().toString(36).substring(2, 7)}`;
+        this.connected = false;
+        this.auth = null;
+        this.eventHandlers = new Map();
+        this.emittedEvents = [];
+    }
+    on(event, handler) {
+        if (!this.eventHandlers.has(event)) {
+            this.eventHandlers.set(event, new Set());
+        }
+        this.eventHandlers.get(event).add(handler);
+        return this;
+    }
+    removeAllListeners() {
+        this.eventHandlers.clear();
+        return this;
+    }
+    emit(event, ...args) {
+        this.emittedEvents.push({ event, args });
+        // Check if last arg is an acknowledgement callback
+        const lastArg = args[args.length - 1];
+        if (typeof lastArg === 'function') {
+            // simulate default server ack
+            setTimeout(() => {
+                lastArg({ success: true, event });
+            }, 5);
+        }
+        return this;
+    }
+    trigger(event, ...args) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers) {
+            handlers.forEach((h) => h(...args));
+        }
+    }
+    connect() {
+        this.connected = true;
+        this.trigger('connect');
+        return this;
+    }
+    disconnect() {
+        this.connected = false;
+        this.trigger('disconnect', 'io client disconnect');
+        return this;
+    }
+}
+// Mock BroadcastChannel implementation
+class MockBroadcastChannel {
+    constructor(name) {
+        this.closed = false;
+        this.onmessage = null;
+        this.postedMessages = [];
+        this.shouldFailPost = false;
+        this.name = name;
+        if (!MockBroadcastChannel.channels.has(name)) {
+            MockBroadcastChannel.channels.set(name, new Set());
+        }
+        MockBroadcastChannel.channels.get(name).add(this);
+    }
+    postMessage(message) {
+        if (this.closed)
+            throw new Error('BroadcastChannel is closed');
+        if (this.shouldFailPost)
+            throw new Error('Simulated BroadcastChannel failure');
+        this.postedMessages.push(message);
+        const peers = MockBroadcastChannel.channels.get(this.name);
+        if (peers) {
+            peers.forEach((peer) => {
+                if (peer !== this && !peer.closed && typeof peer.onmessage === 'function') {
+                    queueMicrotask(() => {
+                        if (!peer.closed && typeof peer.onmessage === 'function') {
+                            peer.onmessage(new MessageEvent('message', { data: message }));
+                        }
+                    });
+                }
+            });
+        }
+    }
+    close() {
+        this.closed = true;
+        const peers = MockBroadcastChannel.channels.get(this.name);
+        if (peers) {
+            peers.delete(this);
+        }
+    }
+    static reset() {
+        MockBroadcastChannel.channels.clear();
+    }
+}
+MockBroadcastChannel.channels = new Map();
+// Mock Web Lock Manager
+class MockLockManager {
+    constructor() {
+        this.activeLocks = new Map();
+        this.queues = new Map();
+    }
+    request(name, optionsOrCallback, callback) {
+        const cb = typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
+        const signal = optionsOrCallback?.signal;
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                return reject(new DOMException('The request was aborted', 'AbortError'));
+            }
+            const executeLock = async () => {
+                if (signal?.aborted) {
+                    const next = this.queues.get(name)?.shift();
+                    if (next)
+                        next();
+                    return reject(new DOMException('The request was aborted', 'AbortError'));
+                }
+                let lockReleased = false;
+                const release = () => {
+                    if (lockReleased)
+                        return;
+                    lockReleased = true;
+                    this.activeLocks.delete(name);
+                    const next = this.queues.get(name)?.shift();
+                    if (next) {
+                        next();
+                    }
+                };
+                this.activeLocks.set(name, { release });
+                if (signal) {
+                    signal.addEventListener('abort', () => {
+                        release();
+                        reject(new DOMException('The request was aborted', 'AbortError'));
+                    });
+                }
+                try {
+                    const result = await cb({ name });
+                    release();
+                    resolve(result);
+                }
+                catch (err) {
+                    release();
+                    reject(err);
+                }
+            };
+            if (!this.activeLocks.has(name)) {
+                executeLock();
+            }
+            else {
+                if (!this.queues.has(name)) {
+                    this.queues.set(name, []);
+                }
+                this.queues.get(name).push(executeLock);
+            }
+        });
+    }
+    reset() {
+        this.activeLocks.clear();
+        this.queues.clear();
+    }
+}
+(0, node_test_1.describe)('WebSocketClient Production Hardening Test Suite', () => {
+    let mockLocks;
+    let activeSockets;
+    (0, node_test_1.beforeEach)(() => {
+        MockBroadcastChannel.reset();
+        mockLocks = new MockLockManager();
+        activeSockets = [];
+        // Polyfill window & global environment for Node.js test runner
+        globalThis.window = {
+            location: { origin: 'http://localhost:3000' },
+            addEventListener: () => { },
+            removeEventListener: () => { },
+        };
+        globalThis.document = {
+            visibilityState: 'visible',
+            addEventListener: () => { },
+            removeEventListener: () => { },
+        };
+    });
+    (0, node_test_1.afterEach)(() => {
+        MockBroadcastChannel.reset();
+        mockLocks.reset();
+    });
+    const createTestClient = (projectId = 'test-proj', serverUrl = 'http://localhost:3000', options = {}) => {
+        const socket = new MockSocket();
+        activeSockets.push(socket);
+        const client = new WebSocketClient_1.WebSocketClient(projectId, serverUrl, {
+            socketFactory: (url, opts) => {
+                socket.auth = opts?.auth || null;
+                return socket;
+            },
+            broadcastChannelFactory: (name) => new MockBroadcastChannel(name),
+            locks: mockLocks,
+            followerTtlMs: 1000,
+            heartbeatIntervalMs: 200,
+            pruneIntervalMs: 500,
+            leaderLeaseIntervalMs: 500,
+            ...options,
+        });
+        return { client, socket };
+    };
+    (0, node_test_1.describe)('1. Argument Validation & Construction', () => {
+        (0, node_test_1.it)('throws invalid-argument error for empty projectId', () => {
+            strict_1.default.throws(() => new WebSocketClient_1.WebSocketClient('', 'http://localhost:3000'), {
+                name: 'NexaWebSocketError',
+                code: 'invalid-argument',
+            });
+        });
+        (0, node_test_1.it)('throws invalid-argument error for empty serverUrl', () => {
+            strict_1.default.throws(() => new WebSocketClient_1.WebSocketClient('test-proj', ''), {
+                name: 'NexaWebSocketError',
+                code: 'invalid-argument',
+            });
+        });
+        (0, node_test_1.it)('derives stable coordination keys without exposing tokens', () => {
+            const key1 = WebSocketClient_1.WebSocketClient.deriveCoordinationKey('proj', 'http://localhost:3000', 'scopeA');
+            const key2 = WebSocketClient_1.WebSocketClient.deriveCoordinationKey('proj', 'http://localhost:3000', 'scopeA');
+            const key3 = WebSocketClient_1.WebSocketClient.deriveCoordinationKey('proj', 'http://localhost:3000', 'scopeB');
+            strict_1.default.equal(key1, key2);
+            strict_1.default.notEqual(key1, key3);
+            strict_1.default.equal(key1.length, 16);
+        });
+    });
+    (0, node_test_1.describe)('2. Tri-state Path Extraction & Strict Segment Matching', () => {
+        (0, node_test_1.it)('validates segment-aware path matching correctly', () => {
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('users/12', 'users/12'), true);
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('users/12/profile', 'users/12'), true);
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('users/12', 'users/12/profile'), true);
+            // Boundary check: users/12 MUST NOT match users/123 or users/1
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('users/123', 'users/12'), false);
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('users/1', 'users/12'), false);
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.isPathMatch('posts/10', 'posts/1'), false);
+        });
+        (0, node_test_1.it)('extracts tri-state status (none, valid, invalid)', () => {
+            strict_1.default.deepEqual(WebSocketClient_1.WebSocketClient.extractPayloadPathTriState({}), { status: 'none' });
+            strict_1.default.deepEqual(WebSocketClient_1.WebSocketClient.extractPayloadPathTriState({ path: 'users/alice' }), {
+                status: 'valid',
+                path: 'users/alice',
+            });
+            strict_1.default.deepEqual(WebSocketClient_1.WebSocketClient.extractPayloadPathTriState({ docPath: '/posts/123/' }), {
+                status: 'valid',
+                path: 'posts/123',
+            });
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.extractPayloadPathTriState({ path: 'users//alice' }).status, 'invalid');
+            strict_1.default.equal(WebSocketClient_1.WebSocketClient.extractPayloadPathTriState({ path: '' }).status, 'invalid');
+        });
+        (0, node_test_1.it)('quarantines malformed paths from becoming global events in handleSocketDataEvent', async () => {
+            const { client, socket } = createTestClient();
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            socket.connect();
+            let receivedCount = 0;
+            client.addListener('data_changed', () => {
+                receivedCount++;
+            });
+            // Emit malformed path
+            socket.trigger('data_changed', { path: 'users//invalid' });
+            strict_1.default.equal(receivedCount, 0);
+            // Emit valid untargeted without explicit isGlobal flag -> ignored
+            socket.trigger('data_changed', { value: 123 });
+            strict_1.default.equal(receivedCount, 0);
+            // Emit valid with proper path matching subscription
+            client.subscribe('users/alice');
+            socket.trigger('data_changed', { path: 'users/alice', value: 456 });
+            strict_1.default.equal(receivedCount, 1);
+            client.close();
+        });
+    });
+    (0, node_test_1.describe)('3. Request Counter Invariants in send()', () => {
+        (0, node_test_1.it)('increments and decrements counter safely on successful execution', async () => {
+            const { client, socket } = createTestClient();
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            socket.connect();
+            const sendPromise = client.send('save_data', { foo: 'bar' });
+            strict_1.default.equal(client.activeLocalSendsCount, 1);
+            const res = await sendPromise;
+            strict_1.default.deepEqual(res, { success: true, event: 'save_data' });
+            strict_1.default.equal(client.activeLocalSendsCount, 0);
+            client.close();
+        });
+        (0, node_test_1.it)('decrements counter on timeout without leaking state', async () => {
+            const { client, socket } = createTestClient();
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            // Socket connected but no ack sent
+            socket.emit = function (event, ...args) {
+                this.emittedEvents.push({ event, args });
+                return this; // no ack
+            };
+            socket.connect();
+            await strict_1.default.rejects(async () => {
+                await client.send('query_data', { q: 1 }, 50);
+            }, {
+                name: 'NexaWebSocketError',
+                code: 'timeout',
+            });
+            strict_1.default.equal(client.activeLocalSendsCount, 0);
+            client.close();
+        });
+        (0, node_test_1.it)('rejects reserved send events with invalid-argument', async () => {
+            const { client } = createTestClient();
+            await strict_1.default.rejects(async () => {
+                await client.send('connect', {});
+            }, {
+                name: 'NexaWebSocketError',
+                code: 'invalid-argument',
+            });
+            strict_1.default.equal(client.activeLocalSendsCount, 0);
+            client.close();
+        });
+    });
+    (0, node_test_1.describe)('4. Multi-tab Leader/Follower Coordination & Term Fencing', () => {
+        (0, node_test_1.it)('elects first tab as leader and second tab as follower', async () => {
+            const tabA = createTestClient('shared-proj');
+            const tabB = createTestClient('shared-proj');
+            tabA.client.ensureConnected();
+            tabB.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 50));
+            strict_1.default.equal(tabA.client.isLeader, true);
+            strict_1.default.equal(tabA.client.state, 'leader');
+            strict_1.default.equal(tabB.client.isLeader, false);
+            strict_1.default.equal(tabB.client.state, 'follower');
+            strict_1.default.equal(tabB.client.currentLeaderId, tabA.client.tabId);
+            strict_1.default.equal(tabB.client.currentElectionId, tabA.client.electionId);
+            tabA.client.close();
+            tabB.client.close();
+        });
+        (0, node_test_1.it)('forwards follower send to leader and receives response', async () => {
+            const tabA = createTestClient('shared-proj');
+            const tabB = createTestClient('shared-proj');
+            tabA.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            tabA.socket.connect();
+            tabB.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 50));
+            const res = await tabB.client.send('fetch_doc', { id: 'doc123' }, 2000);
+            strict_1.default.deepEqual(res, { success: true, event: 'fetch_doc' });
+            tabA.client.close();
+            tabB.client.close();
+        });
+        (0, node_test_1.it)('deduplicates duplicate follower send requests at leader', async () => {
+            const tabA = createTestClient('shared-proj');
+            const tabB = createTestClient('shared-proj');
+            tabA.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            tabA.socket.connect();
+            tabB.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 50));
+            let socketEmitCount = 0;
+            const originalEmit = tabA.socket.emit.bind(tabA.socket);
+            tabA.socket.emit = function (event, ...args) {
+                socketEmitCount++;
+                return originalEmit(event, ...args);
+            };
+            const res1 = await tabB.client.send('fetch_user', { uid: 'u1' });
+            strict_1.default.ok(res1);
+            strict_1.default.equal(socketEmitCount, 1);
+            tabA.client.close();
+            tabB.client.close();
+        });
+        (0, node_test_1.it)('returns ambiguous-outcome error when mutating send is disrupted during election change', async () => {
+            const tabA = createTestClient('shared-proj');
+            const tabB = createTestClient('shared-proj');
+            tabA.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            tabA.socket.connect();
+            tabB.client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 50));
+            // Override tabA.socket.emit so it does not ack immediately
+            tabA.socket.emit = function (event, ...args) {
+                this.emittedEvents.push({ event, args });
+                return this;
+            };
+            const mutatingPromise = tabB.client.send('write_document', { data: 'test' }, 2000);
+            // Wait for follower message to reach leader
+            await new Promise((r) => setTimeout(r, 30));
+            // Close leader abruptly
+            tabA.client.close();
+            await strict_1.default.rejects(mutatingPromise, (err) => {
+                strict_1.default.equal(err.name, 'NexaWebSocketError');
+                strict_1.default.equal(err.isAmbiguous, true);
+                return true;
+            });
+            tabB.client.close();
+        });
+    });
+    (0, node_test_1.describe)('5. Independent Coordination Mode Fallback', () => {
+        (0, node_test_1.it)('runs in independent mode when coordinationMode option is set to independent', async () => {
+            const { client, socket } = createTestClient('proj', 'http://localhost:3000', {
+                coordinationMode: 'independent',
+            });
+            strict_1.default.equal(client.isIndependent, true);
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            strict_1.default.equal(client.state, 'leader');
+            socket.connect();
+            strict_1.default.equal(client.isConnected, true);
+            client.close();
+        });
+    });
+    (0, node_test_1.describe)('6. Dynamic Auth Refresh', () => {
+        (0, node_test_1.it)('retrieves fresh auth payload on socket startup and updateAuth', async () => {
+            let currentToken = 'token_v1';
+            const { client, socket } = createTestClient('proj', 'http://localhost:3000', {
+                getAuthPayload: async () => ({ token: currentToken }),
+            });
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 30));
+            strict_1.default.deepEqual(socket.auth, { token: 'token_v1' });
+            client.updateAuth({ token: 'token_v2' });
+            strict_1.default.deepEqual(socket.auth, { token: 'token_v2' });
+            client.close();
+        });
+    });
+    (0, node_test_1.describe)('7. Defensive Listener Dispatch & Reference Counting', () => {
+        (0, node_test_1.it)('allows listeners to unsubscribe safely during dispatch without skipping peers', async () => {
+            const { client, socket } = createTestClient();
+            client.ensureConnected();
+            await new Promise((r) => setTimeout(r, 20));
+            socket.connect();
+            let order = [];
+            let unsubA;
+            unsubA = client.addListener('custom_event', () => {
+                order.push('A');
+                unsubA(); // unregister self inside callback
+            });
+            client.addListener('custom_event', () => {
+                order.push('B');
+            });
+            client.dispatch('custom_event', { foo: 'bar' });
+            strict_1.default.deepEqual(order, ['A', 'B']);
+            // Second dispatch: only B should fire
+            order = [];
+            client.dispatch('custom_event', { foo: 'bar' });
+            strict_1.default.deepEqual(order, ['B']);
+            client.close();
+        });
+    });
+    (0, node_test_1.describe)('8. Safe and Idempotent close() Teardown', () => {
+        (0, node_test_1.it)('can be called multiple times safely without throwing', () => {
+            const { client } = createTestClient();
+            client.ensureConnected();
+            strict_1.default.doesNotThrow(() => client.close());
+            strict_1.default.doesNotThrow(() => client.close());
+            strict_1.default.equal(client.state, 'disposed');
+        });
+    });
+});

package/dist/types/index.d.ts

@@ -22,6 +22,7 @@ export interface QueryConstraint {
     directionStr?: 'asc' | 'desc';
     limitValue?: number;
     docSnapshot?: any;
+    cursorValues?: any[];
 }
 export interface SnapshotMetadata {
     readonly hasPendingWrites: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexabase-console",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "SDK Client resmi untuk NexaBase: Platform Sinkronisasi NoSQL, Realtime, File Storage, & Autentikasi Offline-First.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",