@novasamatech/host-substrate-chain-connection 0.7.5 → 0.7.7

package/README.md

@@ -24,12 +24,16 @@ import {
 } from '@novasamatech/host-substrate-chain-connection';
 import { dot } from '@polkadot-api/descriptors';
 
-const polkadot: ChainConfig = {
+// `ChainConfig` only requires `genesisHash` — extend it with whatever fields
+// your app needs (here, the WebSocket endpoints to dial).
+type Chain = ChainConfig & { nodes: string[] };
+
+const polkadot: Chain = {
   genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
   nodes: ['wss://rpc.polkadot.io'],
 };
 
-const chains = createChainConnection({
+const chains = createChainConnection<Chain>({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
       endpoints: chain.nodes,
@@ -51,8 +55,10 @@ unlock();
   - [`lockApi`](#lockapichain)
   - [`getProvider`](#getproviderchain)
   - [`status` / `onStatusChanged`](#statusgenesishash--onstatuschangedgenesishash-callback)
+  - [`pauseAll` / `resumeAll`](#pauseall--resumeall)
   - [`createWsJsonRpcProvider`](#createwsjsonrpcprovideroptions)
   - [`createMetadataCache`](#createmetadatacacheoptions)
+  - [`withSubscriptionReplay`](#withsubscriptionreplayprovider-onreconnect)
 - [Recipes](#recipes)
   - [Custom resolve](#custom-resolve)
   - [Metadata caching](#metadata-caching)
@@ -88,10 +94,11 @@ function createChainConnection<C extends ChainConfig, T = PolkadotClient>(
 ```ts
 type ChainConfig = {
   genesisHash: string;
-  nodes: string[];
 };
 ```
 
+Extend it with whatever fields your `createProvider` / `resolve` callbacks need (e.g. `nodes`, `name`, `specName`).
+
 Returns a [`ChainConnection<C, T>`](#lockapichain) with the methods below.
 
 ---
@@ -176,19 +183,66 @@ unsubscribe();
 
 ---
 
+### `pauseAll` / `resumeAll`
+
+Drops the inner socket of every active provider that supports pausing (e.g. providers built via `createWsJsonRpcProvider`). Pooled clients and ref counts are preserved; tracked subscriptions are re-sent on `resumeAll()` via the replay wrapper.
+
+Use this when the host process goes to background (mobile / OS suspend) and you want to release sockets without tearing down callers.
+
+**Signature:**
+
+```ts
+function pauseAll(): void
+function resumeAll(): void
+```
+
+**Example:**
+
+```ts
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'hidden') {
+    chains.pauseAll();
+  } else {
+    chains.resumeAll();
+  }
+});
+```
+
+---
+
 ### `createWsJsonRpcProvider(options)`
 
 WebSocket provider factory. Wraps polkadot-api's `getWsProvider` and translates WebSocket events to `ConnectionStatus`. Active JSON-RPC subscriptions are automatically replayed after a reconnect — consumers using `getProvider` don't need to handle reconnects manually.
 
+The returned provider is **pausable**: `pause()` drops the inner socket and `resume()` reopens it. The connection pool calls these via `pauseAll()` / `resumeAll()`.
+
 **Signature:**
 
 ```ts
 function createWsJsonRpcProvider(options: {
   endpoints: string[];
   onStatusChanged?: (status: ConnectionStatus) => void;
-}): JsonRpcProvider;
+  websocketClass?: typeof WebSocket;
+  heartbeatTimeout?: number;
+  connectionTimeout?: number;
+  logger?: SocketLoggerFn;
+}): PausableJsonRpcProvider;
+
+type PausableJsonRpcProvider = JsonRpcProvider & {
+  pause(): void;
+  resume(): void;
+};
 ```
 
+| Field | Description |
+|---|---|
+| `endpoints` | One or more WebSocket URLs. Failover is handled by the underlying `getWsProvider`. |
+| `onStatusChanged` | Optional. Called with `'connecting' \| 'connected' \| 'disconnected'` on socket events. |
+| `websocketClass` | Optional. Override the WebSocket implementation (e.g. `ws` in Node). |
+| `heartbeatTimeout` | Optional. Milliseconds without a server message before the socket is considered dead. Defaults to the underlying library's 40 s. |
+| `connectionTimeout` | Optional. Milliseconds to wait for the initial connection before giving up. |
+| `logger` | Optional. A `SocketLoggerFn` from `@polkadot-api/ws-provider` for tracing socket events. |
+
 **Example:**
 
 ```ts
@@ -226,11 +280,30 @@ import { createLocalStorageAdapter } from '@novasamatech/storage-adapter';
 const cache = createMetadataCache();
 
 // With localStorage persistence (survives page reloads)
-const cache = createMetadataCache({
+const persistedCache = createMetadataCache({
   storage: createLocalStorageAdapter('chain-metadata'),
 });
 ```
 
+---
+
+### `withSubscriptionReplay(provider, onReconnect)`
+
+Wraps any `JsonRpcProvider` so that active JSON-RPC subscriptions are automatically re-sent after the underlying transport reconnects. `createWsJsonRpcProvider` applies this internally — use it directly only when building a custom provider that needs the same behavior.
+
+**Signature:**
+
+```ts
+function withSubscriptionReplay(
+  provider: JsonRpcProvider,
+  onReconnect: (callback: VoidFunction) => VoidFunction,
+): JsonRpcProvider;
+```
+
+`onReconnect` is a subscription primitive: call the supplied `callback` whenever your transport finishes reconnecting, and return a teardown function that removes the listener.
+
+> **Note:** After a reconnect the server assigns new subscription IDs. Always unsubscribe with the most recently received ID — stale IDs from a previous connection silently fail.
+
 ## Recipes
 
 ### Custom resolve
@@ -241,12 +314,14 @@ The `resolve` callback transforms the raw `PolkadotClient` into whatever your ap
 import { type PolkadotClient, type TypedApi } from 'polkadot-api';
 import { dot, type DotDescriptor } from '@polkadot-api/descriptors';
 
+type Chain = ChainConfig & { nodes: string[] };
+
 type ResolvedApi = {
   api: TypedApi<DotDescriptor>;
   client: PolkadotClient;
 };
 
-const chains = createChainConnection<ChainConfig, ResolvedApi>({
+const chains = createChainConnection<Chain, ResolvedApi>({
   createProvider(chain, onStatusChanged) {
     return createWsJsonRpcProvider({
       endpoints: chain.nodes,
@@ -275,11 +350,13 @@ unlock();
 ```ts
 import { createLocalStorageAdapter } from '@novasamatech/storage-adapter';
 
+type Chain = ChainConfig & { nodes: string[] };
+
 const metadataCache = createMetadataCache({
   storage: createLocalStorageAdapter('chain-metadata'),
 });
 
-const chains = createChainConnection({
+const chains = createChainConnection<Chain>({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
       endpoints: chain.nodes,
@@ -302,6 +379,7 @@ import { type Client as SmoldotClient, start as startSmoldot } from 'polkadot-ap
 
 type MyChain = ChainConfig & {
   name: string;
+  nodes: string[];
   lightClient?: boolean;
 };
 
@@ -361,11 +439,16 @@ Common additions beyond `api` and `client`:
 
 ```ts
 import { dot, ksm, type DotDescriptor, type KsmDescriptor } from '@polkadot-api/descriptors';
-import { type ChainDefinition, type CompatibilityToken, type TypedApi, getTypedCodecs } from 'polkadot-api';
+import { type ChainDefinition, type CompatibilityToken, type PolkadotClient, type TypedApi, getTypedCodecs } from 'polkadot-api';
+
+type Chain = ChainConfig & { nodes: string[] };
+
+const POLKADOT_GENESIS = '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3';
+const KUSAMA_GENESIS = '0xb0a8d493285c2df73290dfb7e61f870f17b41801197a149ca93654499ea3dafe';
 
 const descriptorMap: Record<string, ChainDefinition> = {
-  [polkadot.genesisHash]: dot,
-  [kusama.genesisHash]: ksm,
+  [POLKADOT_GENESIS]: dot,
+  [KUSAMA_GENESIS]: ksm,
 };
 
 type ResolvedApi = {
@@ -375,7 +458,7 @@ type ResolvedApi = {
   compatibilityToken: CompatibilityToken;
 };
 
-const chains = createChainConnection<MyChain, ResolvedApi>({
+const chains = createChainConnection<Chain, ResolvedApi>({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
       endpoints: chain.nodes,
@@ -491,6 +574,7 @@ import { dot, dot_ah, dot_ppl, ksm, ksm_ah, wnd, wnd_ah } from '@polkadot-api/de
 
 type Chain = ChainConfig & {
   name: string;
+  nodes: string[];
   specName: string;
 };
 

package/dist/connectionPool.js

@@ -106,15 +106,31 @@ export const createChainConnection = ({ resolve, clientOptions, createProvider,
         },
         getProvider(chain) {
             return getSyncProvider(onResult => {
+                let teardownCalled = false;
+                let pendingUnlock = null;
+                // Idempotent: subsequent calls (e.g. teardown after disconnect) are no-ops.
+                const releaseUnlock = () => {
+                    const unlock = pendingUnlock;
+                    pendingUnlock = null;
+                    unlock?.();
+                };
                 rawAcquire(chain)
                     .then(({ pooled, unlock }) => {
-                    onResult((onMessage, _onHalt) => pooled.provider.branch(unlock)(onMessage));
+                    if (teardownCalled) {
+                        unlock();
+                        onResult(null);
+                        return;
+                    }
+                    pendingUnlock = unlock;
+                    onResult((onMessage, _onHalt) => pooled.provider.branch(releaseUnlock)(onMessage));
                 })
                     .catch(() => {
                     onResult(null);
                 });
+                // Covers teardown without disconnect, and teardown before acquire resolves.
                 return () => {
-                    /* empty */
+                    teardownCalled = true;
+                    releaseUnlock();
                 };
             });
         },

package/dist/metadataCache.js

@@ -39,7 +39,10 @@ export const createMetadataCache = (options) => {
                 setMetadata(key, metadata) {
                     const k = cacheKey(chainId, key);
                     memory.set(k, metadata);
-                    storage?.write(k, bytesToBase64(metadata));
+                    // setMetadata is fire-and-forget by contract; log persist failures.
+                    storage?.write(k, bytesToBase64(metadata)).orTee(error => {
+                        console.error(`[metadataCache] failed to persist metadata for ${k}:`, error);
+                    });
                 },
             };
         },

package/dist/metadataCache.spec.js

@@ -3,8 +3,8 @@ import { describe, expect, it, vi } from 'vitest';
 import { createMetadataCache } from './metadataCache.js';
 const createMockStorage = () => ({
     read: vi.fn(),
-    write: vi.fn(),
-    clear: vi.fn(),
+    write: vi.fn(() => okAsync(undefined)),
+    clear: vi.fn(() => okAsync(undefined)),
     // eslint-disable-next-line @typescript-eslint/no-empty-function
     subscribe: vi.fn(() => () => { }),
 });

package/dist/subscriptionReplayProvider.js

@@ -69,6 +69,15 @@ export const withSubscriptionReplay = (provider, onReconnect) => onMessage => {
         onMessage(message);
     });
     const unsubReconnect = onReconnect(() => {
+        // Replay unconfirmed subscribes first: their `reconnectFor === null`, so
+        // they're disjoint from the entries inserted by the active-replay loop
+        // below (which all carry a non-null `reconnectFor`).
+        for (const [, pending] of pendingSubscriptions) {
+            if (pending.reconnectFor === null)
+                conn.send(pending.payload);
+        }
+        // Replay confirmed subscriptions: the server returns a fresh subId, which
+        // we map back to the consumer's stable subId.
         for (const [consumerSubId, sub] of activeSubscriptions) {
             pendingSubscriptions.set(sub.id, { payload: sub.payload, reconnectFor: consumerSubId });
             conn.send(sub.payload);

package/dist/subscriptionReplayProvider.spec.js

@@ -61,15 +61,16 @@ describe('withSubscriptionReplay', () => {
         control.triggerReconnect();
         expect(mock.send).not.toHaveBeenCalled();
     });
-    it('does not replay pending subscriptions (no server response yet) on reconnect', () => {
+    it('replays pending subscriptions (no server response yet) on reconnect', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'statement_subscribeStatement'));
+        const subscribeMsg = req(1, 'statement_subscribeStatement');
+        conn.send(subscribeMsg);
         // intentionally no simulateMessage — subscription not confirmed by server
         mock.send.mockClear();
         control.triggerReconnect();
-        expect(mock.send).not.toHaveBeenCalled();
+        expect(mock.send).toHaveBeenCalledWith(subscribeMsg);
     });
     it('replays active subscriptions on reconnect', () => {
         const mock = createMockProvider();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-substrate-chain-connection",
   "type": "module",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Chain connection pool with ref counting and provider branching for Polkadot API",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/storage-adapter": "0.7.5",
+    "@novasamatech/storage-adapter": "0.7.7",
     "@polkadot-api/ws-provider": "^0.9.0",
     "@polkadot-api/json-rpc-provider": "^0.2.0",
     "@polkadot-api/json-rpc-provider-proxy": "^0.4.0",