@novasamatech/host-substrate-chain-connection 0.6.7

package/dist/branchedProvider.spec.js

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createBranchedProvider } from './branchedProvider.js';
+const createMockProvider = () => {
+    const send = vi.fn();
+    const disconnect = vi.fn();
+    let onMessage = null;
+    const provider = cb => {
+        onMessage = cb;
+        return { send, disconnect };
+    };
+    return {
+        provider,
+        send,
+        disconnect,
+        simulateMessage: (msg) => onMessage?.(msg),
+    };
+};
+describe('createBranchedProvider', () => {
+    it('creates underlying connection on first branch', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const onMessage = vi.fn();
+        branched.branch()(onMessage);
+        mock.simulateMessage('{"id":1}');
+        expect(onMessage).toHaveBeenCalledWith('{"id":1}');
+    });
+    it('reuses connection for multiple branches', () => {
+        const mock = createMockProvider();
+        const providerSpy = vi.fn(mock.provider);
+        const branched = createBranchedProvider(providerSpy);
+        branched.branch()(vi.fn());
+        branched.branch()(vi.fn());
+        expect(providerSpy).toHaveBeenCalledTimes(1);
+    });
+    it('broadcasts messages to all active branches', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const cb1 = vi.fn();
+        const cb2 = vi.fn();
+        branched.branch()(cb1);
+        branched.branch()(cb2);
+        mock.simulateMessage('{"id":1}');
+        expect(cb1).toHaveBeenCalledWith('{"id":1}');
+        expect(cb2).toHaveBeenCalledWith('{"id":1}');
+    });
+    it('disconnected branch stops receiving messages', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const cb1 = vi.fn();
+        const conn1 = branched.branch()(cb1);
+        branched.branch()(vi.fn()); // keep connection alive
+        conn1.disconnect();
+        mock.simulateMessage('{"id":1}');
+        expect(cb1).not.toHaveBeenCalled();
+    });
+    it('disconnecting one branch does not affect others', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const conn1 = branched.branch()(vi.fn());
+        const cb2 = vi.fn();
+        branched.branch()(cb2);
+        conn1.disconnect();
+        mock.simulateMessage('{"id":1}');
+        expect(cb2).toHaveBeenCalledWith('{"id":1}');
+        expect(mock.disconnect).not.toHaveBeenCalled();
+    });
+    it('disconnecting last branch tears down underlying connection', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const conn1 = branched.branch()(vi.fn());
+        const conn2 = branched.branch()(vi.fn());
+        conn1.disconnect();
+        expect(mock.disconnect).not.toHaveBeenCalled();
+        conn2.disconnect();
+        expect(mock.disconnect).toHaveBeenCalledTimes(1);
+    });
+    it('calls onDisconnect callback on branch disconnect', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const onDisconnect = vi.fn();
+        const conn = branched.branch(onDisconnect)(vi.fn());
+        conn.disconnect();
+        expect(onDisconnect).toHaveBeenCalledTimes(1);
+    });
+    it('new branch after full teardown creates fresh connection', () => {
+        const mock = createMockProvider();
+        const providerSpy = vi.fn(mock.provider);
+        const branched = createBranchedProvider(providerSpy);
+        const conn = branched.branch()(vi.fn());
+        conn.disconnect();
+        expect(providerSpy).toHaveBeenCalledTimes(1);
+        branched.branch()(vi.fn());
+        expect(providerSpy).toHaveBeenCalledTimes(2);
+    });
+    it('branch.send delegates to underlying connection', () => {
+        const mock = createMockProvider();
+        const branched = createBranchedProvider(mock.provider);
+        const conn = branched.branch()(vi.fn());
+        conn.send('{"method":"test"}');
+        expect(mock.send).toHaveBeenCalledWith('{"method":"test"}');
+    });
+});

package/dist/connectionManager.d.ts

@@ -0,0 +1,6 @@
+import type { ConnectionStatus } from './types.js';
+export declare const createConnectionManager: () => {
+    getConnectionStatus(chainId: string): ConnectionStatus;
+    update(chainId: string, status: ConnectionStatus): void;
+    onStatusChange(chainId: string, callback: (status: ConnectionStatus) => void): import("nanoevents").Unsubscribe;
+};

package/dist/connectionManager.js

@@ -0,0 +1,24 @@
+import { createNanoEvents } from 'nanoevents';
+export const createConnectionManager = () => {
+    const events = createNanoEvents();
+    const connectionStatuses = new Map();
+    events.on('status', ({ chainId, status }) => {
+        connectionStatuses.set(chainId, status);
+    });
+    return {
+        getConnectionStatus(chainId) {
+            return connectionStatuses.get(chainId) ?? 'disconnected';
+        },
+        update(chainId, status) {
+            events.emit('status', { chainId, status });
+        },
+        onStatusChange(chainId, callback) {
+            const handler = (event) => {
+                if (event.chainId === chainId) {
+                    callback(event.status);
+                }
+            };
+            return events.on('status', handler);
+        },
+    };
+};

package/dist/connectionManager.spec.d.ts

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

package/dist/connectionManager.spec.js

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createConnectionManager } from './connectionManager.js';
+describe('createConnectionManager', () => {
+    it('returns disconnected for unknown chainId', () => {
+        const manager = createConnectionManager();
+        expect(manager.getConnectionStatus('unknown')).toBe('disconnected');
+    });
+    it('returns current status after update', () => {
+        const manager = createConnectionManager();
+        manager.update('chain-a', 'connecting');
+        expect(manager.getConnectionStatus('chain-a')).toBe('connecting');
+        manager.update('chain-a', 'connected');
+        expect(manager.getConnectionStatus('chain-a')).toBe('connected');
+    });
+    it('fires onStatusChange callbacks', () => {
+        const manager = createConnectionManager();
+        const callback = vi.fn();
+        manager.onStatusChange('chain-a', callback);
+        manager.update('chain-a', 'connected');
+        expect(callback).toHaveBeenCalledWith('connected');
+    });
+    it('only fires for matching chainId', () => {
+        const manager = createConnectionManager();
+        const callback = vi.fn();
+        manager.onStatusChange('chain-a', callback);
+        manager.update('chain-b', 'connected');
+        expect(callback).not.toHaveBeenCalled();
+    });
+    it('supports multiple subscribers', () => {
+        const manager = createConnectionManager();
+        const cb1 = vi.fn();
+        const cb2 = vi.fn();
+        manager.onStatusChange('chain-a', cb1);
+        manager.onStatusChange('chain-a', cb2);
+        manager.update('chain-a', 'connected');
+        expect(cb1).toHaveBeenCalledWith('connected');
+        expect(cb2).toHaveBeenCalledWith('connected');
+    });
+    it('unsubscribe stops notifications', () => {
+        const manager = createConnectionManager();
+        const callback = vi.fn();
+        const unsub = manager.onStatusChange('chain-a', callback);
+        unsub();
+        manager.update('chain-a', 'connected');
+        expect(callback).not.toHaveBeenCalled();
+    });
+});

package/dist/connectionPool.d.ts

@@ -0,0 +1,20 @@
+import type { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
+import type { PolkadotClient } from 'polkadot-api';
+import { createClient } from 'polkadot-api';
+import type { ChainConfig, ConnectionStatus } from './types.js';
+export type ChainConnectionConfig<C extends ChainConfig, T = PolkadotClient> = {
+    createProvider: (chain: C, onStatusChanged: (status: ConnectionStatus) => void) => JsonRpcProvider;
+    clientOptions?: (chain: C) => Parameters<typeof createClient>[1];
+    resolve?: (chain: C, client: PolkadotClient) => Promise<T>;
+};
+export type ChainConnection<C extends ChainConfig, T = PolkadotClient> = {
+    lockApi(chain: C): Promise<{
+        api: T;
+        unlock: VoidFunction;
+    }>;
+    requestApi<Return>(chain: C, callback: (api: T) => Return): Promise<Awaited<Return>>;
+    getProvider(chain: C): JsonRpcProvider;
+    status(chainId: string): ConnectionStatus;
+    onStatusChanged(chainId: string, callback: (status: ConnectionStatus) => void): VoidFunction;
+};
+export declare const createChainConnection: <C extends ChainConfig, T = PolkadotClient>(config: ChainConnectionConfig<C, T>) => ChainConnection<C, T>;

package/dist/connectionPool.js

@@ -0,0 +1,109 @@
+import { getSyncProvider } from '@polkadot-api/json-rpc-provider-proxy';
+import { createClient } from 'polkadot-api';
+import { createBranchedProvider } from './branchedProvider.js';
+import { createConnectionManager } from './connectionManager.js';
+import { createRefCounter } from './refCounter.js';
+export const createChainConnection = (config) => {
+    const connections = createConnectionManager();
+    const refCounter = createRefCounter();
+    const existingClients = new Map();
+    // Resolve cache (when config.resolve is provided)
+    const resolvedApis = new Map();
+    const pendingResolutions = new Map();
+    const getOrCreateClient = (chain) => {
+        const existing = existingClients.get(chain.chainId);
+        if (existing)
+            return existing;
+        const provider = config.createProvider(chain, status => connections.update(chain.chainId, status));
+        const branchedProvider = createBranchedProvider(provider);
+        const client = createClient(branchedProvider.branch(), config.clientOptions?.(chain));
+        const pooled = { client, provider: branchedProvider };
+        existingClients.set(chain.chainId, pooled);
+        return pooled;
+    };
+    const destroyClient = (chainId) => {
+        const pooled = existingClients.get(chainId);
+        if (pooled) {
+            existingClients.delete(chainId);
+            connections.update(chainId, 'disconnected');
+            pooled.client.destroy();
+        }
+        resolvedApis.delete(chainId);
+        pendingResolutions.delete(chainId);
+    };
+    const rawAcquire = async (chain) => {
+        try {
+            refCounter.increment(chain.chainId);
+            const pooled = getOrCreateClient(chain);
+            await pooled.client.getBestBlocks();
+            return {
+                pooled,
+                unlock() {
+                    refCounter.decrement(chain.chainId);
+                },
+            };
+        }
+        catch (error) {
+            if (refCounter.decrement(chain.chainId) === 0) {
+                destroyClient(chain.chainId);
+            }
+            throw error;
+        }
+    };
+    const resolveApi = async (chain, polkadotClient) => {
+        if (!config.resolve)
+            return polkadotClient;
+        const existing = resolvedApis.get(chain.chainId);
+        if (existing && existing.polkadotClient === polkadotClient)
+            return existing.resolved;
+        const pending = pendingResolutions.get(chain.chainId);
+        if (pending && pending.polkadotClient === polkadotClient)
+            return pending.promise;
+        const promise = (async () => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by early return above
+            const resolved = await config.resolve(chain, polkadotClient);
+            resolvedApis.set(chain.chainId, { resolved, polkadotClient });
+            return resolved;
+        })();
+        pendingResolutions.set(chain.chainId, { promise, polkadotClient });
+        promise.finally(() => pendingResolutions.delete(chain.chainId));
+        return promise;
+    };
+    const connection = {
+        async lockApi(chain) {
+            const { pooled, unlock } = await rawAcquire(chain);
+            try {
+                const api = await resolveApi(chain, pooled.client);
+                return { api, unlock };
+            }
+            catch (error) {
+                unlock();
+                resolvedApis.delete(chain.chainId);
+                pendingResolutions.delete(chain.chainId);
+                throw error;
+            }
+        },
+        requestApi: (async (chain, callback) => {
+            const { api, unlock } = await connection.lockApi(chain);
+            try {
+                return await callback(api);
+            }
+            finally {
+                unlock();
+            }
+        }),
+        getProvider(chain) {
+            return getSyncProvider(async () => {
+                const { pooled, unlock } = await rawAcquire(chain);
+                return pooled.provider.branch(unlock);
+            });
+        },
+        status(chainId) {
+            return connections.getConnectionStatus(chainId);
+        },
+        onStatusChanged(chainId, callback) {
+            return connections.onStatusChange(chainId, callback);
+        },
+    };
+    return connection;
+};

package/dist/connectionPool.spec.d.ts

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

package/dist/connectionPool.spec.js

@@ -0,0 +1,192 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createChainConnection } from './connectionPool.js';
+vi.mock('polkadot-api', () => ({
+    createClient: vi.fn((_provider, _options) => createMockClient()),
+}));
+const createMockClient = () => ({
+    getBestBlocks: vi.fn().mockResolvedValue([]),
+    destroy: vi.fn(),
+});
+const createMockProvider = () => {
+    const send = vi.fn();
+    const disconnect = vi.fn();
+    let onMessage = null;
+    const provider = cb => {
+        onMessage = cb;
+        return { send, disconnect };
+    };
+    return { provider, send, disconnect, simulateMessage: (msg) => onMessage?.(msg) };
+};
+const testChain = (id) => ({ chainId: id, nodes: [{ url: 'wss://test' }] });
+const createTestConnection = (overrides) => {
+    const mockProvider = createMockProvider();
+    const connection = createChainConnection({
+        createProvider: () => mockProvider.provider,
+        ...overrides,
+    });
+    return { connection, mockProvider };
+};
+describe('createChainConnection', () => {
+    describe('lockApi', () => {
+        it('returns api and unlock function', async () => {
+            const { connection } = createTestConnection();
+            const { api, unlock } = await connection.lockApi(testChain('a'));
+            expect(api).toBeDefined();
+            expect(typeof unlock).toBe('function');
+            unlock();
+        });
+        it('reuses client for same chainId', async () => {
+            const { connection } = createTestConnection();
+            const chain = testChain('a');
+            const { api: api1, unlock: u1 } = await connection.lockApi(chain);
+            const { api: api2, unlock: u2 } = await connection.lockApi(chain);
+            expect(api1).toBe(api2);
+            u1();
+            u2();
+        });
+        it('creates separate clients for different chains', async () => {
+            const { connection } = createTestConnection();
+            const { api: api1, unlock: u1 } = await connection.lockApi(testChain('a'));
+            const { api: api2, unlock: u2 } = await connection.lockApi(testChain('b'));
+            expect(api1).not.toBe(api2);
+            u1();
+            u2();
+        });
+        it('calls getBestBlocks to verify connectivity', async () => {
+            const { connection } = createTestConnection();
+            const { api, unlock } = await connection.lockApi(testChain('a'));
+            expect(api.getBestBlocks).toHaveBeenCalled();
+            unlock();
+        });
+    });
+    describe('lockApi — with resolve', () => {
+        it('calls resolve with chain and polkadotClient', async () => {
+            const resolve = vi.fn().mockResolvedValue('resolved-api');
+            const { connection } = createTestConnection({ resolve });
+            const chain = testChain('a');
+            const { api, unlock } = await connection.lockApi(chain);
+            expect(api).toBe('resolved-api');
+            expect(resolve).toHaveBeenCalledWith(chain, expect.anything());
+            unlock();
+        });
+        it('caches resolved api for subsequent calls', async () => {
+            const resolve = vi.fn().mockResolvedValue('resolved-api');
+            const { connection } = createTestConnection({ resolve });
+            const chain = testChain('a');
+            const { unlock: u1 } = await connection.lockApi(chain);
+            const { unlock: u2 } = await connection.lockApi(chain);
+            expect(resolve).toHaveBeenCalledTimes(1);
+            u1();
+            u2();
+        });
+        it('deduplicates concurrent resolutions', async () => {
+            const resolve = vi.fn().mockImplementation(() => new Promise(r => setTimeout(() => r('resolved-api'), 10)));
+            const { connection } = createTestConnection({ resolve });
+            const chain = testChain('a');
+            const [r1, r2] = await Promise.all([connection.lockApi(chain), connection.lockApi(chain)]);
+            expect(resolve).toHaveBeenCalledTimes(1);
+            r1.unlock();
+            r2.unlock();
+        });
+    });
+    describe('lockApi — error handling', () => {
+        it('throws when getBestBlocks rejects', async () => {
+            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                getBestBlocks: vi.fn().mockRejectedValue(new Error('connection failed')),
+                destroy: vi.fn(),
+            });
+            const { connection } = createTestConnection();
+            await expect(connection.lockApi(testChain('a'))).rejects.toThrow('connection failed');
+        });
+        it('destroys client on error when ref count reaches 0', async () => {
+            const destroyFn = vi.fn();
+            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                getBestBlocks: vi.fn().mockRejectedValue(new Error('fail')),
+                destroy: destroyFn,
+            });
+            const { connection } = createTestConnection();
+            await expect(connection.lockApi(testChain('a'))).rejects.toThrow();
+            expect(destroyFn).toHaveBeenCalled();
+        });
+        it('throws when resolve rejects and calls unlock', async () => {
+            const resolve = vi.fn().mockRejectedValue(new Error('resolve failed'));
+            const { connection } = createTestConnection({ resolve });
+            // Suppress the unhandled rejection from the detached .finally() promise chain
+            // in connectionPool.ts (pendingResolutions cleanup).
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            const suppress = () => { };
+            process.on('unhandledRejection', suppress);
+            await expect(connection.lockApi(testChain('a'))).rejects.toThrow('resolve failed');
+            // Let microtask queue flush so the .finally() settles
+            await new Promise(r => setTimeout(r, 0));
+            process.off('unhandledRejection', suppress);
+            // After resolve failure with last ref released, new lock should create fresh client
+            resolve.mockResolvedValue('recovered');
+            const { api, unlock } = await connection.lockApi(testChain('a'));
+            expect(api).toBe('recovered');
+            unlock();
+        });
+    });
+    describe('requestApi', () => {
+        it('calls callback with api and returns result', async () => {
+            const { connection } = createTestConnection();
+            const result = await connection.requestApi(testChain('a'), api => {
+                expect(api).toBeDefined();
+                return 42;
+            });
+            expect(result).toBe(42);
+        });
+        it('unlocks after callback completes', async () => {
+            const { connection } = createTestConnection();
+            await connection.requestApi(testChain('a'), () => 'done');
+            // Subsequent request should work without issue
+            const result = await connection.requestApi(testChain('a'), () => 'again');
+            expect(result).toBe('again');
+        });
+        it('unlocks when callback throws', async () => {
+            const { connection } = createTestConnection();
+            await expect(connection.requestApi(testChain('a'), () => {
+                throw new Error('callback error');
+            })).rejects.toThrow('callback error');
+            // Should still work after error
+            const result = await connection.requestApi(testChain('a'), () => 'ok');
+            expect(result).toBe('ok');
+        });
+    });
+    describe('status / onStatusChanged', () => {
+        it('returns disconnected for unknown chain', () => {
+            const { connection } = createTestConnection();
+            expect(connection.status('unknown')).toBe('disconnected');
+        });
+        it('reflects status from createProvider callback', async () => {
+            let statusCb;
+            const { connection } = createTestConnection({
+                createProvider: (_chain, onStatusChanged) => {
+                    statusCb = onStatusChanged;
+                    return createMockProvider().provider;
+                },
+            });
+            await connection.lockApi(testChain('a')).then(({ unlock }) => unlock());
+            statusCb('connected');
+            expect(connection.status('a')).toBe('connected');
+        });
+        it('onStatusChanged returns unsubscribe function', async () => {
+            let statusCb;
+            const { connection } = createTestConnection({
+                createProvider: (_chain, onStatusChanged) => {
+                    statusCb = onStatusChanged;
+                    return createMockProvider().provider;
+                },
+            });
+            await connection.lockApi(testChain('a')).then(({ unlock }) => unlock());
+            const callback = vi.fn();
+            const unsub = connection.onStatusChanged('a', callback);
+            statusCb('connected');
+            expect(callback).toHaveBeenCalledWith('connected');
+            unsub();
+            callback.mockClear();
+            statusCb('disconnected');
+            expect(callback).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type ChainConnection, type ChainConnectionConfig, createChainConnection } from './connectionPool.js';
+export { type MetadataCache, createMetadataCache } from './metadataCache.js';
+export { createWsJsonRpcProvider } from './providers.js';
+export { type ChainConfig, type ConnectionStatus } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createChainConnection } from './connectionPool.js';
+export { createMetadataCache } from './metadataCache.js';
+export { createWsJsonRpcProvider } from './providers.js';
+export {} from './types.js';

package/dist/metadataCache.d.ts

@@ -0,0 +1,10 @@
+import type { StorageAdapter } from '@novasamatech/storage-adapter';
+import { createClient } from 'polkadot-api';
+type ClientOptions = NonNullable<Parameters<typeof createClient>[1]>;
+export type MetadataCache = {
+    forChain(chainId: string): ClientOptions;
+};
+export declare const createMetadataCache: (options?: {
+    storage?: StorageAdapter;
+}) => MetadataCache;
+export {};

package/dist/metadataCache.js

@@ -0,0 +1,47 @@
+import { createClient } from 'polkadot-api';
+const bytesToBase64 = (bytes) => {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+};
+const base64ToBytes = (base64) => {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+};
+export const createMetadataCache = (options) => {
+    const memory = new Map();
+    const storage = options?.storage;
+    const cacheKey = (chainId, key) => `${chainId}:${key}`;
+    return {
+        forChain(chainId) {
+            return {
+                async getMetadata(key) {
+                    const k = cacheKey(chainId, key);
+                    const cached = memory.get(k);
+                    if (cached)
+                        return cached;
+                    if (storage) {
+                        const result = await storage.read(k);
+                        if (result.isOk() && result.value) {
+                            const bytes = base64ToBytes(result.value);
+                            memory.set(k, bytes);
+                            return bytes;
+                        }
+                    }
+                    return null;
+                },
+                setMetadata(key, metadata) {
+                    const k = cacheKey(chainId, key);
+                    memory.set(k, metadata);
+                    storage?.write(k, bytesToBase64(metadata));
+                },
+            };
+        },
+    };
+};

package/dist/metadataCache.spec.d.ts

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