@rpckit/core 0.9.99

package/dist/types.d.ts

@@ -0,0 +1,187 @@
+import type { AnySchema, ExtractParams, ExtractRequestMethod, ExtractReturn, ExtractSubscriptionMethod, Schema } from './schema.js';
+export type UnsubscribeCleanup = (context: {
+    request: (method: string, ...params: unknown[]) => Promise<unknown>;
+    method: string;
+    params: unknown[];
+    initialResult: unknown;
+}) => Promise<void>;
+export type Unsubscribe = (cleanup?: UnsubscribeCleanup) => Promise<void>;
+export interface Transport<S extends Schema = AnySchema> {
+    url: string;
+    connect(): Promise<void>;
+    request<M extends ExtractRequestMethod<S>>(method: M, ...params: ExtractParams<S, M>): Promise<ExtractReturn<S, M>>;
+    subscribe<M extends ExtractSubscriptionMethod<S>>(method: M, ...args: [
+        ...ExtractParams<S, M>,
+        callback: (data: ExtractReturn<S, M>) => void
+    ]): Promise<Unsubscribe>;
+    close(): Promise<void>;
+}
+export interface BatchConfig {
+    wait?: number;
+    batchSize?: number;
+}
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    retryCount?: number;
+    /** Base delay between retries in ms (default: 150). Exponential backoff is applied. */
+    retryDelay?: number;
+}
+export interface PingConfig {
+    interval: number;
+    method?: string;
+    params?: unknown[];
+}
+export interface HandshakeConfig {
+    method: string;
+    params?: unknown[];
+}
+export interface WebSocketTransportConfig extends RetryConfig {
+    url: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Connection timeout in milliseconds */
+    connectTimeout?: number;
+    handshake?: HandshakeConfig;
+    keepAlive?: number | PingConfig;
+    reconnect?: {
+        delay: number;
+        attempts: number;
+    };
+    headers?: Record<string, string>;
+    batch?: boolean | BatchConfig;
+    onUnsubscribe?: UnsubscribeCleanup;
+    /**
+     * Transform the initial subscription result before delivering to the callback.
+     * Useful for normalizing initial results to match the notification format.
+     * `result` is the raw value wrapped in a single-element array.
+     * For example, Electrum Cash notifications arrive as [...params, ...result]
+     * while the initial result is just the raw value `[value]`.
+     *
+     * Return `undefined` to suppress delivery of the initial result to the callback.
+     * This is useful for protocols like Ethereum where the initial result is a
+     * subscription ID (metadata) rather than actual data.
+     */
+    transformInitialResult?: (method: string, params: unknown[], result: unknown[]) => unknown;
+    /**
+     * Filter notifications before delivery to subscribers. Return true to deliver.
+     * Used by protocols like Electrum Cash where multiple subscriptions share the
+     * same method name but use different params for routing.
+     */
+    notificationFilter?: (subscriptionParams: unknown[], notificationParams: unknown[]) => boolean;
+}
+/** Extended WebSocket transport with socket access methods */
+export interface WebSocketTransport<S extends Schema = AnySchema> extends Transport<S> {
+    /** Get the underlying WebSocket instance (null if not connected) */
+    getSocket(): WebSocket | null;
+    /** Get the underlying WebSocket instance, connecting first if needed */
+    getSocketAsync(): Promise<WebSocket>;
+}
+/** Extended TCP transport with socket access methods */
+export interface TcpTransport<S extends Schema = AnySchema> extends Transport<S> {
+    /** Get the underlying TCP socket (null if not connected) */
+    getSocket(): import('node:net').Socket | null;
+    /** Get the underlying TCP socket, connecting first if needed */
+    getSocketAsync(): Promise<import('node:net').Socket>;
+}
+export type TcpTransportConfig = ({
+    url: string;
+    tls?: import('tls').ConnectionOptions;
+} & TcpTransportOptions) | ({
+    host: string;
+    port: number;
+    tls?: boolean | import('tls').ConnectionOptions;
+} & TcpTransportOptions);
+export interface TcpTransportOptions extends RetryConfig {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Connection timeout in milliseconds */
+    connectTimeout?: number;
+    handshake?: HandshakeConfig;
+    keepAlive?: number | PingConfig;
+    reconnect?: {
+        delay: number;
+        attempts: number;
+    };
+    batch?: boolean | BatchConfig;
+    onUnsubscribe?: UnsubscribeCleanup;
+    /**
+     * Transform the initial subscription result before delivering to the callback.
+     * `result` is the raw value wrapped in a single-element array.
+     *
+     * Return `undefined` to suppress delivery of the initial result to the callback.
+     */
+    transformInitialResult?: (method: string, params: unknown[], result: unknown[]) => unknown;
+    /**
+     * Filter notifications before delivery to subscribers. Return true to deliver.
+     * Used by protocols like Electrum Cash where multiple subscriptions share the
+     * same method name but use different params for routing.
+     */
+    notificationFilter?: (subscriptionParams: unknown[], notificationParams: unknown[]) => boolean;
+}
+export interface HttpTransportConfig extends RetryConfig {
+    url: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    headers?: Record<string, string>;
+    batch?: boolean | BatchConfig;
+    /** Custom fetch implementation (e.g., node-fetch, undici) */
+    fetchFn?: typeof fetch;
+    /** Extra options passed to fetch (excluding method, headers, body, signal) */
+    fetchOptions?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'signal'>;
+    /** Callback before each fetch request */
+    onRequest?: (info: {
+        url: string;
+        body: unknown;
+    }) => void;
+    /** Callback after each fetch response */
+    onResponse?: (info: {
+        status: number;
+        body: unknown;
+    }) => void;
+    /** Return RPC errors as results instead of throwing (default: false) */
+    raw?: boolean;
+}
+export interface RankConfig<S extends Schema = AnySchema> {
+    interval?: number;
+    ping?: (transport: Transport<S>) => Promise<unknown>;
+    sampleCount?: number;
+    timeout?: number;
+    weights?: {
+        latency?: number;
+        stability?: number;
+    };
+}
+export interface TransportScore<S extends Schema = AnySchema> {
+    transport: Transport<S>;
+    score: number;
+    latency: number;
+    stability: number;
+}
+export interface TransportResponse<S extends Schema = AnySchema> {
+    method: string;
+    params: unknown[];
+    transport: Transport<S>;
+    response?: unknown;
+    error?: unknown;
+    status: 'success' | 'error';
+}
+export interface FallbackTransport<S extends Schema = AnySchema> extends Transport<S> {
+    transports: Transport<S>[];
+    scores: TransportScore<S>[];
+    onScores(listener: (scores: TransportScore<S>[]) => void): () => void;
+    onResponse(listener: (info: TransportResponse<S>) => void): () => void;
+}
+export interface ClusterTransport<S extends Schema = AnySchema> extends Transport<S> {
+    transports: Transport<S>[];
+    onResponse(listener: (info: TransportResponse<S>) => void): () => void;
+}
+export interface FallbackTransportOptions<S extends Schema = AnySchema> {
+    shouldThrow?: (error: Error) => boolean | undefined;
+    rank?: boolean | RankConfig<S>;
+    eagerConnect?: boolean;
+}
+export interface ClusterTransportOptions {
+    quorum: number;
+    timeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@rpckit/core",
+  "version": "0.9.99",
+  "description": "Core types, schema utilities, and batch scheduler for JSON-RPC communication",
+  "author": "mainnet_pat",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./electrum-cash": {
+      "types": "./dist/electrum-cash/index.d.ts",
+      "default": "./dist/electrum-cash/index.js"
+    },
+    "./ethereum": {
+      "types": "./dist/ethereum/index.d.ts",
+      "default": "./dist/ethereum/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "json-rpc",
+    "rpc",
+    "electrum",
+    "electrum-cash",
+    "ethereum",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainnet-pat/rpckit.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://rpckit.dev",
+  "bugs": {
+    "url": "https://github.com/mainnet-pat/rpckit/issues"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}