@rpckit/core 0.9.99

package/README.md

@@ -0,0 +1,131 @@
+# @rpckit/core
+
+Core types, schema utilities, and batch scheduler for communication with JSON-RPC servers.
+
+## Installation
+
+```bash
+npm install @rpckit/core
+```
+
+## Usage
+
+```typescript
+import type { Schema, Transport } from '@rpckit/core'
+import { webSocket } from '@rpckit/websocket'
+
+type MySchema = {
+  requests: [
+    { method: 'getblockcount'; params: []; return: number }
+  ]
+  subscriptions: []
+}
+
+const transport = webSocket<MySchema>('wss://example.com')
+const blockCount = await transport.request('getblockcount')
+await transport.close()
+```
+
+## Electrum Cash Subpackage
+
+Electrum Cash schema types and a pre-configured `parse()` variant are available under the `electrum-cash` subpath:
+
+```typescript
+import type { ElectrumCashSchema } from '@rpckit/core/electrum-cash'
+import { parse } from '@rpckit/core/electrum-cash'
+
+const transport = await parse('wss://electrum.example.com')
+```
+
+## Ethereum Subpackage
+
+Ethereum schema types and a pre-configured `parse()` variant are available under the `ethereum` subpath:
+
+```typescript
+import type { EthereumSchema } from '@rpckit/core/ethereum'
+import { parse } from '@rpckit/core/ethereum'
+
+const transport = await parse('wss://ethereum-rpc.publicnode.com')
+```
+
+## Parse Utility
+
+Create transports from one-liner configuration strings:
+
+```typescript
+import { parse } from '@rpckit/core'
+
+// Simple transports (uses base, protocol-agnostic packages)
+const ws = await parse('wss://example.com:50004')
+const tcp = await parse('tcp+tls://example.com:50002?timeout=10000')
+
+// With options
+const batched = await parse('wss://example.com?batchSize=10&batchWait=50')
+
+// Fallback with ranking
+const fb = await parse('fallback(wss://a.com,tcp://b.com)?rank=true')
+
+// Cluster with quorum
+const cl = await parse('cluster(2,ws://1.com,ws://2.com,ws://3.com)')
+
+// Nested
+const nested = await parse('fallback(wss://primary.com,cluster(2,ws://1.com,ws://2.com,ws://3.com))')
+```
+
+### createParse
+
+Create a custom `parse` function that uses different packages for transport creation:
+
+```typescript
+import { createParse } from '@rpckit/core'
+
+// Use electrum-cash variants for all transports
+const electrumParse = createParse({
+  websocket: '@rpckit/websocket/electrum-cash',
+  tcp: '@rpckit/tcp/electrum-cash',
+  http: '@rpckit/http/electrum-cash',
+})
+
+const transport = await electrumParse('wss://electrum.example.com')
+```
+
+A pre-built Electrum Cash parse is available at `@rpckit/core/electrum-cash`.
+
+### createParseSync
+
+Create a synchronous `parse` function using pre-imported factory functions. Unlike `createParse` which uses dynamic imports, this variant accepts already-loaded factories:
+
+```typescript
+import { createParseSync } from '@rpckit/core'
+import { webSocket } from '@rpckit/websocket/electrum-cash'
+import { fallback } from '@rpckit/fallback'
+
+const parseSync = createParseSync({ webSocket, fallback })
+const transport = parseSync('fallback(wss://a.com,wss://b.com)?eagerConnect=true')
+```
+
+Supported schemes: `wss://`, `ws://`, `tcp://`, `tcp+tls://`, `http://`, `https://`
+
+Supported options: `timeout`, `retryCount`, `retryDelay`, `keepAlive`, `batch`, `batchSize`, `batchWait`, `rank`, `eagerConnect`
+
+## Exports
+
+### Main (`@rpckit/core`)
+
+- `BatchScheduler` - Request batching utility
+- `parse` - One-liner transport configuration parser
+- `createParse` - Factory for custom parse functions with overridden package maps
+- `createParseSync` - Synchronous factory using pre-imported transport functions
+- `withRetry` - Async retry utility with exponential backoff
+- `Transport` - Transport interface for implementing custom transports
+- Type utilities: `ExtractReturn`, `ExtractParams`, `ExtractMethod`, `FilterMethods`, `OverrideRequests`, `PackageMap`, `FactoryMap`, etc.
+
+### Electrum Cash (`@rpckit/core/electrum-cash`)
+
+- `parse` - Pre-configured parse using Electrum Cash transport variants
+- `ElectrumCashSchema` - Type definitions for Electrum Cash protocol (v1.5 and v1.6)
+
+### Ethereum (`@rpckit/core/ethereum`)
+
+- `parse` - Pre-configured parse using Ethereum transport variants
+- `EthereumSchema` - Type definitions for Ethereum JSON-RPC (EIP-1474 standard methods)

package/dist/batch.d.ts

@@ -0,0 +1,17 @@
+import type { RpcRequest, RpcResponse } from './protocol.js';
+import type { BatchConfig } from './types.js';
+export interface BatchSchedulerOptions extends BatchConfig {
+    /** Return RPC errors as results instead of throwing (default: false) */
+    raw?: boolean;
+}
+export declare class BatchScheduler {
+    private queue;
+    private timer;
+    private config;
+    private raw;
+    private send;
+    constructor(config: BatchSchedulerOptions, send: (requests: RpcRequest[]) => Promise<RpcResponse[]>);
+    enqueue(request: RpcRequest): Promise<unknown>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAQ7C,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,wEAAwE;IACxE,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,KAAK,CAA6C;IAC1D,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,IAAI,CAAoD;gBAG9D,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC;IAO1D,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAYxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAsC7B"}

package/dist/batch.js

@@ -0,0 +1,59 @@
+export class BatchScheduler {
+    queue = [];
+    timer = null;
+    config;
+    raw;
+    send;
+    constructor(config, send) {
+        this.config = { batchSize: config.batchSize ?? 10, wait: config.wait ?? 0 };
+        this.raw = config.raw ?? false;
+        this.send = send;
+    }
+    enqueue(request) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ request, resolve, reject });
+            if (this.queue.length >= this.config.batchSize) {
+                this.flush();
+            }
+            else if (!this.timer) {
+                this.timer = setTimeout(() => this.flush(), this.config.wait);
+            }
+        });
+    }
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0);
+        try {
+            const responses = await this.send(batch.map((p) => p.request));
+            const byId = new Map(responses.map((r) => [r.id, r]));
+            for (const pending of batch) {
+                const response = byId.get(pending.request.id);
+                if (!response) {
+                    pending.reject(new Error(`No response for request id ${pending.request.id}, try reducing batch size`));
+                }
+                else if (response.error) {
+                    if (this.raw) {
+                        pending.resolve(response);
+                    }
+                    else {
+                        pending.reject(response.error);
+                    }
+                }
+                else {
+                    pending.resolve(this.raw ? response : response.result);
+                }
+            }
+        }
+        catch (error) {
+            for (const pending of batch) {
+                pending.reject(error);
+            }
+        }
+    }
+}
+//# sourceMappingURL=batch.js.map

package/dist/batch.js.map

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

package/dist/electrum-cash/index.d.ts

@@ -0,0 +1,3 @@
+export { parse } from './parse.js';
+export type { ElectrumCashSchema, ElectrumCashSchema_1_5_3, ElectrumCashSchema_1_6_0, } from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/electrum-cash/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/electrum-cash/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,aAAa,CAAA"}

package/dist/electrum-cash/index.js

@@ -0,0 +1,2 @@
+export { parse } from './parse.js';
+//# sourceMappingURL=index.js.map

package/dist/electrum-cash/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/electrum-cash/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/dist/electrum-cash/parse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse a transport one-liner string into a Transport with Electrum Cash defaults.
+ *
+ * Leaf transports (websocket, tcp, http) are loaded from their `electrum-cash`
+ * subpath variants, which apply protocol-specific defaults:
+ * - Handshake: `server.version` with `['rpckit', '1.6']`
+ * - KeepAlive: `server.ping` method when interval is specified
+ * - Unsubscribe: `method.replace('subscribe', 'unsubscribe')`
+ * - HTTP headers: `server.version` header
+ *
+ * Use `clientName` to override the client name in the handshake (default: `'rpckit'`).
+ * Use `protocolVersion` to override the protocol version (default: `'1.6'`).
+ *
+ * Meta-transports (fallback, cluster) are unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from '@rpckit/core/electrum-cash'
+ *
+ * const ws = await parse('wss://electrum.example.com')
+ * const tcp = await parse('tcp+tls://electrum.example.com:50002?timeout=10000')
+ * const custom = await parse('wss://electrum.example.com?clientName=myapp')
+ * const fb = await parse('fallback(wss://a.com,tcp://b.com:50001)')
+ * ```
+ */
+export declare const parse: <S extends import("../schema.js").Schema = import("../schema.js").AnySchema>(input: string) => Promise<import("../types.js").Transport<S>>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/electrum-cash/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/electrum-cash/parse.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,KAAK,4IAIhB,CAAA"}

package/dist/electrum-cash/parse.js

@@ -0,0 +1,32 @@
+import { createParse } from '../parse.js';
+/**
+ * Parse a transport one-liner string into a Transport with Electrum Cash defaults.
+ *
+ * Leaf transports (websocket, tcp, http) are loaded from their `electrum-cash`
+ * subpath variants, which apply protocol-specific defaults:
+ * - Handshake: `server.version` with `['rpckit', '1.6']`
+ * - KeepAlive: `server.ping` method when interval is specified
+ * - Unsubscribe: `method.replace('subscribe', 'unsubscribe')`
+ * - HTTP headers: `server.version` header
+ *
+ * Use `clientName` to override the client name in the handshake (default: `'rpckit'`).
+ * Use `protocolVersion` to override the protocol version (default: `'1.6'`).
+ *
+ * Meta-transports (fallback, cluster) are unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from '@rpckit/core/electrum-cash'
+ *
+ * const ws = await parse('wss://electrum.example.com')
+ * const tcp = await parse('tcp+tls://electrum.example.com:50002?timeout=10000')
+ * const custom = await parse('wss://electrum.example.com?clientName=myapp')
+ * const fb = await parse('fallback(wss://a.com,tcp://b.com:50001)')
+ * ```
+ */
+export const parse = createParse({
+    websocket: '@rpckit/websocket/electrum-cash',
+    tcp: '@rpckit/tcp/electrum-cash',
+    http: '@rpckit/http/electrum-cash',
+});
+//# sourceMappingURL=parse.js.map

package/dist/electrum-cash/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/electrum-cash/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,WAAW,CAAC;IAC/B,SAAS,EAAE,iCAAiC;IAC5C,GAAG,EAAE,2BAA2B;IAChC,IAAI,EAAE,4BAA4B;CACnC,CAAC,CAAA"}