@pezkuwi/rpc-provider 16.5.16 → 16.5.18

package/src/mock/subscribe.spec.ts

@@ -0,0 +1,81 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { TypeRegistry } from '@pezkuwi/types/create';
+
+import { MockProvider } from './index.js';
+
+describe('subscribe', (): void => {
+  const registry = new TypeRegistry();
+  let mock: MockProvider;
+
+  beforeEach((): void => {
+    mock = new MockProvider(registry);
+  });
+
+  afterEach(async () => {
+    await mock.disconnect();
+  });
+
+  it('fails on unknown methods', async (): Promise<void> => {
+    await mock
+      .subscribe('test', 'test_notFound')
+      .catch((error): void => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect((error as Error).message).toMatch(/Invalid method 'test_notFound'/);
+      });
+  });
+
+  it('returns a subscription id', async (): Promise<void> => {
+    await mock
+      .subscribe('chain_newHead', 'chain_subscribeNewHead', (): void => undefined)
+      .then((id): void => {
+        expect(id).toEqual(1);
+      });
+  });
+
+  it('calls back with the last known value', async (): Promise<void> => {
+    mock.isUpdating = false;
+    mock.subscriptions.chain_subscribeNewHead.lastValue = 'testValue';
+
+    await new Promise<boolean>((resolve) => {
+      mock.subscribe('chain_newHead', 'chain_subscribeNewHead', (_: any, value: string): void => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect(value).toEqual('testValue');
+        resolve(true);
+      }).catch(console.error);
+    });
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('calls back with new headers', async (): Promise<void> => {
+    await new Promise<boolean>((resolve) => {
+      mock.subscribe('chain_newHead', 'chain_subscribeNewHead', (_: any, header: { number: number }): void => {
+        if (header.number === 4) {
+          resolve(true);
+        }
+      }).catch(console.error);
+    });
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('handles errors within callbacks gracefully', async (): Promise<void> => {
+    let hasThrown = false;
+
+    await new Promise<boolean>((resolve) => {
+      mock.subscribe('chain_newHead', 'chain_subscribeNewHead', (_: any, header: { number: number }): void => {
+        if (!hasThrown) {
+          hasThrown = true;
+
+          throw new Error('testing');
+        }
+
+        if (header.number === 3) {
+          resolve(true);
+        }
+      }).catch(console.error);
+    });
+  });
+});

package/src/mock/types.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Server } from 'mock-socket';
+
+export type Global = typeof globalThis & {
+  WebSocket: typeof WebSocket;
+  fetch: any;
+}
+
+export interface Mock {
+  body: Record<string, Record<string, unknown>>;
+  requests: number;
+  server: Server;
+  done: () => Promise<void>;
+}
+
+export type MockStateSubscriptionCallback = (error: Error | null, value: any) => void;
+
+export interface MockStateSubscription {
+  callbacks: Record<number, MockStateSubscriptionCallback>;
+  lastValue: any;
+}
+
+export interface MockStateSubscriptions {
+  // known
+  chain_subscribeNewHead: MockStateSubscription;
+  state_subscribeStorage: MockStateSubscription;
+
+  // others
+  [key: string]: MockStateSubscription;
+}
+
+export type MockStateDb = Record<string, Uint8Array>;
+
+export type MockStateRequests = Record<string, (db: MockStateDb, params: any[]) => string>;

package/src/mock/unsubscribe.spec.ts

@@ -0,0 +1,57 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { TypeRegistry } from '@pezkuwi/types/create';
+
+import { MockProvider } from './index.js';
+
+describe('unsubscribe', (): void => {
+  const registry = new TypeRegistry();
+  let mock: MockProvider;
+  let id: number;
+
+  beforeEach((): Promise<void> => {
+    mock = new MockProvider(registry);
+
+    return mock
+      .subscribe('chain_newHead', 'chain_subscribeNewHead', (): void => undefined)
+      .then((_id): void => {
+        id = _id;
+      });
+  });
+
+  afterEach(async () => {
+    await mock.disconnect();
+  });
+
+  it('fails on unknown ids', async (): Promise<void> => {
+    await mock
+      .unsubscribe('chain_newHead', 'chain_subscribeNewHead', 5)
+      .catch((error): boolean => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect((error as Error).message).toMatch(/Unable to find/);
+
+        return false;
+      });
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('unsubscribes successfully', async (): Promise<void> => {
+    await mock.unsubscribe('chain_newHead', 'chain_subscribeNewHead', id);
+  });
+
+  it('fails on double unsubscribe', async (): Promise<void> => {
+    await mock.unsubscribe('chain_newHead', 'chain_subscribeNewHead', id)
+      .then((): Promise<boolean> =>
+        mock.unsubscribe('chain_newHead', 'chain_subscribeNewHead', id)
+      )
+      .catch((error): boolean => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect((error as Error).message).toMatch(/Unable to find/);
+
+        return false;
+      });
+  });
+});

package/src/mod.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './index.js';

package/src/packageDetect.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2026 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @pezkuwi/dev
+// (packageInfo imports will be kept as-is, user-editable)
+
+import { packageInfo as typesInfo } from '@pezkuwi/types/packageInfo';
+import { detectPackage } from '@pezkuwi/util';
+
+import { packageInfo } from './packageInfo.js';
+
+detectPackage(packageInfo, null, [typesInfo]);

package/src/packageInfo.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2026 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @pezkuwi/dev
+
+export const packageInfo = { name: '@pezkuwi/rpc-provider', path: 'auto', type: 'auto', version: '16.5.18' };

package/src/types.ts

@@ -0,0 +1,101 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export interface JsonRpcObject {
+  id: number;
+  jsonrpc: '2.0';
+}
+
+export interface JsonRpcRequest extends JsonRpcObject {
+  method: string;
+  params: unknown[];
+}
+
+export interface JsonRpcResponseBaseError {
+  code: number;
+  data?: number | string;
+  message: string;
+}
+
+export interface RpcErrorInterface<T> {
+  code: number;
+  data?: T;
+  message: string;
+  stack: string;
+}
+
+interface JsonRpcResponseSingle<T> {
+  error?: JsonRpcResponseBaseError;
+  result: T;
+}
+
+interface JsonRpcResponseSubscription<T> {
+  method?: string;
+  params: {
+    error?: JsonRpcResponseBaseError;
+    result: T;
+    subscription: number | string;
+  };
+}
+
+export type JsonRpcResponseBase<T> = JsonRpcResponseSingle<T> & JsonRpcResponseSubscription<T>;
+
+export type JsonRpcResponse<T> = JsonRpcObject & JsonRpcResponseBase<T>;
+
+export type ProviderInterfaceCallback = (error: Error | null, result: any) => void;
+
+export type ProviderInterfaceEmitted = 'connected' | 'disconnected' | 'error';
+
+export type ProviderInterfaceEmitCb = (value?: any) => any;
+
+export interface ProviderInterface {
+  /** true if the provider supports subscriptions (not available for HTTP) */
+  readonly hasSubscriptions: boolean;
+  /** true if the clone() functionality is available on the provider */
+  readonly isClonable: boolean;
+  /** true if the provider is currently connected (ws/sc has connection logic) */
+  readonly isConnected: boolean;
+  /** (optional) stats for the provider with connections/bytes */
+  readonly stats?: ProviderStats;
+  /** (optional) stats for the provider with connections/bytes */
+  readonly ttl?: number | null;
+
+  clone (): ProviderInterface;
+  connect (): Promise<void>;
+  disconnect (): Promise<void>;
+  on (type: ProviderInterfaceEmitted, sub: ProviderInterfaceEmitCb): () => void;
+  send <T = any> (method: string, params: unknown[], isCacheable?: boolean): Promise<T>;
+  subscribe (type: string, method: string, params: unknown[], cb: ProviderInterfaceCallback): Promise<number | string>;
+  unsubscribe (type: string, method: string, id: number | string): Promise<boolean>;
+}
+
+/** Stats for a specific endpoint */
+export interface EndpointStats {
+  /** The total number of bytes sent */
+  bytesRecv: number;
+  /** The total number of bytes received */
+  bytesSent: number;
+  /** The number of cached/in-progress requests made */
+  cached: number;
+  /** The number of errors found */
+  errors: number;
+  /** The number of requests */
+  requests: number;
+  /** The number of subscriptions */
+  subscriptions: number;
+  /** The number of request timeouts */
+  timeout: number;
+}
+
+/** Overall stats for the provider */
+export interface ProviderStats {
+  /** Details for the active/open requests */
+  active: {
+    /** Number of active requests */
+    requests: number;
+    /** Number of active subscriptions */
+    subscriptions: number;
+  };
+  /** The total requests that have been made */
+  total: EndpointStats;
+}

package/src/ws/connect.spec.ts

@@ -0,0 +1,167 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { Mock } from '../mock/types.js';
+
+import { mockWs } from '../mock/mockWs.js';
+import { WsProvider } from './index.js';
+
+const TEST_WS_URL = 'ws://localhost-connect.spec.ts:9988';
+
+function sleep (ms = 100): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('onConnect', (): void => {
+  let mocks: Mock[];
+  let provider: WsProvider | null;
+
+  beforeEach((): void => {
+    mocks = [mockWs([], TEST_WS_URL)];
+  });
+
+  afterEach(async () => {
+    if (provider) {
+      await provider.disconnect();
+      await sleep();
+
+      provider = null;
+    }
+
+    await Promise.all(mocks.map((m) => m.done()));
+    await sleep();
+  });
+
+  it('Does not connect when autoConnect is false', async () => {
+    provider = new WsProvider(TEST_WS_URL, 0);
+
+    await sleep();
+
+    expect(provider.isConnected).toBe(false);
+
+    await provider.connect();
+    await sleep();
+
+    expect(provider.isConnected).toBe(true);
+
+    await provider.disconnect();
+    await sleep();
+
+    expect(provider.isConnected).toBe(false);
+  });
+
+  it('Does connect when autoConnect is true', async () => {
+    provider = new WsProvider(TEST_WS_URL, 1);
+
+    await sleep();
+
+    expect(provider.isConnected).toBe(true);
+  });
+
+  it('Creates a new WebSocket instance by calling the connect() method', async () => {
+    provider = new WsProvider(TEST_WS_URL, false);
+
+    expect(provider.isConnected).toBe(false);
+    expect(mocks[0].server.clients().length).toBe(0);
+
+    await provider.connect();
+    await sleep();
+
+    expect(provider.isConnected).toBe(true);
+    expect(mocks[0].server.clients()).toHaveLength(1);
+  });
+
+  it('Connects to first endpoint when an array is given', async () => {
+    provider = new WsProvider([TEST_WS_URL], 1);
+
+    await sleep();
+
+    expect(provider.isConnected).toBe(true);
+    expect(mocks[0].server.clients()).toHaveLength(1);
+  });
+
+  it('Does not allow connect() on already-connected', async () => {
+    provider = new WsProvider([TEST_WS_URL], 1);
+
+    await sleep();
+
+    expect(provider.isConnected).toBe(true);
+
+    await expect(
+      provider.connect()
+    ).rejects.toThrow(/already connected/);
+  });
+
+  it('Connects to the second endpoint when the first is unreachable', async () => {
+    const endpoints: string[] = ['ws://localhost-unreachable-connect.spec.ts:9956', TEST_WS_URL];
+
+    provider = new WsProvider(endpoints, 1);
+
+    await sleep();
+
+    expect(mocks[0].server.clients()).toHaveLength(1);
+    expect(provider.isConnected).toBe(true);
+  });
+
+  it('Connects to the second endpoint when the first is dropped', async () => {
+    const endpoints: string[] = [TEST_WS_URL, 'ws://localhost-connect.spec.ts:9957'];
+
+    mocks.push(mockWs([], endpoints[1]));
+
+    provider = new WsProvider(endpoints, 1);
+
+    await sleep();
+
+    // Check that first server is connected
+    expect(mocks[0].server.clients()).toHaveLength(1);
+    expect(mocks[1].server.clients()).toHaveLength(0);
+
+    // Close connection from first server
+    mocks[0].server.clients()[0].close();
+
+    await sleep();
+
+    // Check that second server is connected
+    expect(mocks[1].server.clients()).toHaveLength(1);
+    expect(provider.isConnected).toBe(true);
+  });
+
+  it('Round-robin of endpoints on WsProvider', async () => {
+    const endpoints: string[] = [
+      TEST_WS_URL,
+      'ws://localhost-connect.spec.ts:9956',
+      'ws://localhost-connect.spec.ts:9957',
+      'ws://invalid-connect.spec.ts:9956',
+      'ws://localhost-connect.spec.ts:9958'
+    ];
+
+    mocks.push(mockWs([], endpoints[1]));
+    mocks.push(mockWs([], endpoints[2]));
+    mocks.push(mockWs([], endpoints[4]));
+
+    const mockNext = [
+      mocks[1],
+      mocks[2],
+      mocks[3],
+      mocks[0]
+    ];
+
+    provider = new WsProvider(endpoints, 1);
+
+    for (let round = 0; round < 2; round++) {
+      for (let mock = 0; mock < mocks.length; mock++) {
+        await sleep();
+
+        // Wwe are connected, the current mock has the connection and the next doesn't
+        expect(provider.isConnected).toBe(true);
+        expect(mocks[mock].server.clients()).toHaveLength(1);
+        expect(mockNext[mock].server.clients()).toHaveLength(0);
+
+        // Close connection from first server
+        mocks[mock].server.clients()[0].close();
+      }
+    }
+  });
+});

package/src/ws/errors.ts

@@ -0,0 +1,41 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// from https://stackoverflow.com/questions/19304157/getting-the-reason-why-websockets-closed-with-close-code-1006
+
+const known: Record<number, string> = {
+  1000: 'Normal Closure',
+  1001: 'Going Away',
+  1002: 'Protocol Error',
+  1003: 'Unsupported Data',
+  1004: '(For future)',
+  1005: 'No Status Received',
+  1006: 'Abnormal Closure',
+  1007: 'Invalid frame payload data',
+  1008: 'Policy Violation',
+  1009: 'Message too big',
+  1010: 'Missing Extension',
+  1011: 'Internal Error',
+  1012: 'Service Restart',
+  1013: 'Try Again Later',
+  1014: 'Bad Gateway',
+  1015: 'TLS Handshake'
+};
+
+export function getWSErrorString (code: number): string {
+  if (code >= 0 && code <= 999) {
+    return '(Unused)';
+  } else if (code >= 1016) {
+    if (code <= 1999) {
+      return '(For WebSocket standard)';
+    } else if (code <= 2999) {
+      return '(For WebSocket extensions)';
+    } else if (code <= 3999) {
+      return '(For libraries and frameworks)';
+    } else if (code <= 4999) {
+      return '(For applications)';
+    }
+  }
+
+  return known[code] || '(Unknown)';
+}

package/src/ws/index.spec.ts

@@ -0,0 +1,97 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { Request } from '../mock/mockWs.js';
+import type { Mock } from '../mock/types.js';
+
+import { mockWs } from '../mock/mockWs.js';
+import { WsProvider } from './index.js';
+
+const TEST_WS_URL = 'ws://localhost-index.spec.ts:9977';
+
+let provider: WsProvider | null;
+let mock: Mock;
+
+function createWs (requests: Request[], autoConnect = 1000, headers?: Record<string, string>, timeout?: number): WsProvider {
+  mock = mockWs(requests, TEST_WS_URL);
+  provider = new WsProvider(TEST_WS_URL, autoConnect, headers, timeout);
+
+  return provider;
+}
+
+describe('Ws', (): void => {
+  afterEach(async () => {
+    if (mock) {
+      await mock.done();
+    }
+
+    if (provider) {
+      await provider.disconnect();
+      provider = null;
+    }
+  });
+
+  it('returns the connected state', (): void => {
+    expect(
+      createWs([]).isConnected
+    ).toEqual(false);
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('allows you to initialize the provider with custom headers', () => {
+    createWs([], 100, { foo: 'bar' });
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('allows you to set custom timeout value for handlers', () => {
+    const CUSTOM_TIMEOUT_S = 90;
+    const CUSTOM_TIMEOUT_MS = CUSTOM_TIMEOUT_S * 1000;
+
+    createWs([], 100, { foo: 'bar' }, CUSTOM_TIMEOUT_MS);
+  });
+});
+
+describe('Endpoint Parsing', (): void => {
+  // eslint-disable-next-line jest/expect-expect
+  it('Succeeds when WsProvider endpoint is a valid string', () => {
+    /* eslint-disable no-new */
+    new WsProvider(TEST_WS_URL, 0);
+  });
+
+  it('should throw error on negative cache capacity or TTL', () => {
+    expect(() => new WsProvider(TEST_WS_URL, false, {}, undefined, -5, 30000)).toThrow(/'capacity' must be a non-negative integer/);
+    expect(() => new WsProvider(TEST_WS_URL, false, {}, undefined, 1024, -1000)).toThrow(/'ttl' must be between 0 and 1800000 ms or null to disable/);
+  });
+
+  it('Throws when WsProvider endpoint is an invalid string', () => {
+    expect(
+      () => new WsProvider('http://127.0.0.1:9955', 0)
+    ).toThrow(/^Endpoint should start with /);
+  });
+
+  // eslint-disable-next-line jest/expect-expect
+  it('Succeeds when WsProvider endpoint is a valid array', () => {
+    const endpoints: string[] = ['ws://127.0.0.1:9955', 'wss://testnet.io:9944', 'ws://mychain.com:9933'];
+
+    /* eslint-disable no-new */
+    new WsProvider(endpoints, 0);
+  });
+
+  it('Throws when WsProvider endpoint is an empty array', () => {
+    const endpoints: string[] = [];
+
+    expect(
+      () => new WsProvider(endpoints, 0)
+    ).toThrow('WsProvider requires at least one Endpoint');
+  });
+
+  it('Throws when WsProvider endpoint is an invalid array', () => {
+    const endpoints: string[] = ['ws://127.0.0.1:9955', 'http://bad.co:9944', 'ws://mychain.com:9933'];
+
+    expect(
+      () => new WsProvider(endpoints, 0)
+    ).toThrow(/^Endpoint should start with /);
+  });
+});