@pezkuwi/rpc-provider 16.5.5 → 16.5.8

package/types.d.ts

@@ -0,0 +1,85 @@
+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;
+}
+export {};

package/types.js

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

package/ws/errors.d.ts

@@ -0,0 +1 @@
+export declare function getWSErrorString(code: number): string;

package/ws/errors.js

@@ -0,0 +1,38 @@
+const known = {
+    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) {
+    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/ws/index.d.ts

@@ -0,0 +1,121 @@
+import type { EndpointStats, ProviderInterface, ProviderInterfaceCallback, ProviderInterfaceEmitCb, ProviderInterfaceEmitted, ProviderStats } from '../types.js';
+interface SubscriptionHandler {
+    callback: ProviderInterfaceCallback;
+    type: string;
+}
+/**
+ * # @pezkuwi/rpc-provider/ws
+ *
+ * @name WsProvider
+ *
+ * @description The WebSocket Provider allows sending requests using WebSocket to a WebSocket RPC server TCP port. Unlike the [[HttpProvider]], it does support subscriptions and allows listening to events such as new blocks or balance changes.
+ *
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import Api from '@pezkuwi/api/promise';
+ * import { WsProvider } from '@pezkuwi/rpc-provider/ws';
+ *
+ * const provider = new WsProvider('ws://127.0.0.1:9944');
+ * const api = new Api(provider);
+ * ```
+ *
+ * @see [[HttpProvider]]
+ */
+export declare class WsProvider implements ProviderInterface {
+    #private;
+    /**
+     * @param {string | string[]} endpoint The endpoint url. Usually `ws://ip:9944` or `wss://ip:9944`, may provide an array of endpoint strings.
+     * @param {number | false} autoConnectMs Whether to connect automatically or not (default). Provided value is used as a delay between retries.
+     * @param {Record<string, string>} headers The headers provided to the underlying WebSocket
+     * @param {number} [timeout] Custom timeout value used per request . Defaults to `DEFAULT_TIMEOUT_MS`
+     * @param {number} [cacheCapacity] Custom size of the WsProvider LRUCache. Defaults to `DEFAULT_CAPACITY` (1024)
+     * @param {number} [cacheTtl] Custom TTL of the WsProvider LRUCache. Determines how long an object can live in the cache. Defaults to DEFAULT_TTL` (30000)
+     */
+    constructor(endpoint?: string | string[], autoConnectMs?: number | false, headers?: Record<string, string>, timeout?: number, cacheCapacity?: number, cacheTtl?: number | null);
+    /**
+     * @summary `true` when this provider supports subscriptions
+     */
+    get hasSubscriptions(): boolean;
+    /**
+     * @summary `true` when this provider supports clone()
+     */
+    get isClonable(): boolean;
+    /**
+     * @summary Whether the node is connected or not.
+     * @return {boolean} true if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * @description Promise that resolves the first time we are connected and loaded
+     */
+    get isReady(): Promise<WsProvider>;
+    get endpoint(): string;
+    /**
+     * @description Returns a clone of the object
+     */
+    clone(): WsProvider;
+    protected selectEndpointIndex(endpoints: string[]): number;
+    /**
+     * @summary Manually connect
+     * @description The [[WsProvider]] connects automatically by default, however if you decided otherwise, you may
+     * connect manually using this method.
+     */
+    connect(): Promise<void>;
+    /**
+     * @description Connect, never throwing an error, but rather forcing a retry
+     */
+    connectWithRetry(): Promise<void>;
+    /**
+     * @description Manually disconnect from the connection, clearing auto-connect logic
+     */
+    disconnect(): Promise<void>;
+    /**
+     * @description Returns the connection stats
+     */
+    get stats(): ProviderStats;
+    /**
+    * @description Returns the connection stats
+    */
+    get ttl(): number | null | undefined;
+    get endpointStats(): EndpointStats;
+    /**
+     * @summary Listens on events after having subscribed using the [[subscribe]] function.
+     * @param  {ProviderInterfaceEmitted} type Event
+     * @param  {ProviderInterfaceEmitCb}  sub  Callback
+     * @return unsubscribe function
+     */
+    on(type: ProviderInterfaceEmitted, sub: ProviderInterfaceEmitCb): () => void;
+    /**
+     * @summary Send JSON data using WebSockets to configured HTTP Endpoint or queue.
+     * @param method The RPC methods to execute
+     * @param params Encoded parameters as applicable for the method
+     * @param subscription Subscription details (internally used)
+     */
+    send<T = any>(method: string, params: unknown[], isCacheable?: boolean, subscription?: SubscriptionHandler): Promise<T>;
+    /**
+     * @name subscribe
+     * @summary Allows subscribing to a specific event.
+     *
+     * @example
+     * <BR>
+     *
+     * ```javascript
+     * const provider = new WsProvider('ws://127.0.0.1:9944');
+     * const rpc = new Rpc(provider);
+     *
+     * rpc.state.subscribeStorage([[storage.system.account, <Address>]], (_, values) => {
+     *   console.log(values)
+     * }).then((subscriptionId) => {
+     *   console.log('balance changes subscription id: ', subscriptionId)
+     * })
+     * ```
+     */
+    subscribe(type: string, method: string, params: unknown[], callback: ProviderInterfaceCallback): Promise<number | string>;
+    /**
+     * @summary Allows unsubscribing to subscriptions made with [[subscribe]].
+     */
+    unsubscribe(type: string, method: string, id: number | string): Promise<boolean>;
+}
+export {};