@irpclib/irpc 1.0.0-beta.19 → 1.0.0-beta.21

package/dist/types.d.ts

@@ -1,5 +1,8 @@
+import { IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
 import { ErrorCode } from "./error.js";
 import { IRPCTransport } from "./transport.js";
+import { RemoteState } from "./state.js";
+import { StateChange } from "@anchorlib/core";
 import { ZodArray, ZodBoolean, ZodNull, ZodNumber, ZodObject, ZodSafeParseResult, ZodString, ZodUndefined } from "zod/v4";
 
 //#region src/types.d.ts
@@ -14,6 +17,41 @@ type IRPCStubStore = WeakMap<IRPCHandler, IRPCSpec<IRPCInputs, IRPCOutput>>;
  * Used to keep track of available RPC hosts by their names.
  */
 type IRPCSpecStore = Map<string, IRPCSpec<IRPCInputs, IRPCOutput>>;
+type IRPCStatus = (typeof IRPC_STATUS)[keyof typeof IRPC_STATUS];
+type IRPCDataType = (typeof IRPC_DATA_TYPE)[keyof typeof IRPC_DATA_TYPE];
+type IRPCPacketType = (typeof IRPC_PACKET_TYPE)[keyof typeof IRPC_PACKET_TYPE];
+type IRPCEventType = (typeof IRPC_EVENT_TYPE)[keyof typeof IRPC_EVENT_TYPE];
+type IRPCPacketBase = {
+  id: string;
+  name: string;
+  type: IRPCPacketType;
+  status: IRPCStatus;
+  createdAt?: number;
+  arrivedAt?: number;
+};
+type IRPCPacketData = {
+  type: IRPCDataType;
+  value: IRPCData;
+};
+type IRPCPacketCall = IRPCPacketBase & {
+  args: IRPCData[];
+};
+type IRPCPacketAnswer<T extends IRPCData> = IRPCPacketBase & {
+  data?: T;
+  error?: IRPCError;
+};
+type IRPCPacketEvent = IRPCPacketBase & {
+  data: StateChange;
+};
+type IRPCPacketClose = IRPCPacketBase & {
+  error?: IRPCError;
+};
+type IRPCPacketStream<T extends IRPCData> = IRPCPacketAnswer<T> | IRPCPacketEvent | IRPCPacketClose;
+interface IRPCReadable<T> {
+  data: T;
+  error: Error | undefined;
+  status: IRPCStatus;
+}
 /**
  * Represents primitive data types that can be used in IRPC communications.
  * Includes string, number, boolean, null, and undefined.
@@ -70,17 +108,7 @@ type IRPCPackageInfo = {
   /** Optional description of the namespace */
   description?: string;
 };
-type IRPCPackageConfig = IRPCPackageInfo & {
-  timeout?: number;
-  transport?: IRPCTransport;
-};
-/**
- * Defines an RPC module which extends a namespace with execution capabilities.
- */
-type IRPCModule = IRPCPackageInfo & {
-  /** Optional timeout for RPC calls */
-  timeout?: number;
-  /** Optional transport mechanism for RPC communications */
+type IRPCPackageConfig = IRPCPackageInfo & IRPCCallConfig & {
   transport?: IRPCTransport;
 };
 /**
@@ -116,15 +144,31 @@ type IRPCHandler = Function;
 type IRPCInit<I extends IRPCInputs, O extends IRPCOutput> = {
   /** The name of the RPC function */
   name: string;
-  /** Optional schema for input/output validation */
-  schema?: IRPCSchema<I, O>;
   /** Optional description of the RPC function */
   description?: string;
+  /** Optional schema for input/output validation */
+  schema?: IRPCSchema<I, O>;
   /** Optional maximum age of a call in milliseconds */
   maxAge?: number;
-  /** Optional timeout for RPC calls */
-  timeout?: number;
-};
+  /**
+   * Whether to coalesce multiple calls to the same RPC function within a short time period.
+   * If true, multiple calls with the same parameters will be combined into a single call,
+   * with subsequent calls waiting for the result of the first call.
+   * This can help reduce the number of actual function executions.
+   */
+  coalesce?: boolean;
+} & IRPCCallConfig;
+/**
+ * Type definition for an RPC declaration.
+ * Represents an RPC function with its name, description, and configuration.
+ *
+ * @template F - The function signature of the RPC
+ * @template I - Tuple of input validation schemas
+ * @template O - Output validation schema
+ */
+type IRPCDeclareInit<F, I extends IRPCInputs, O extends IRPCOutput> = F extends ((...args: any[]) => RemoteState<infer R>) ? IRPCInit<I, IRPCOutput> & {
+  init: () => R;
+} : IRPCInit<I, O>;
 /**
  * Complete specification for an RPC function including its implementation.
  * Extends IRPCInit with the actual handler function.
@@ -135,6 +179,7 @@ type IRPCInit<I extends IRPCInputs, O extends IRPCOutput> = {
 type IRPCSpec<I extends IRPCInputs, O extends IRPCOutput> = IRPCInit<I, O> & {
   /** The actual handler function that implements the RPC */
   handler: IRPCHandler;
+  init?: () => unknown;
 };
 /**
  * Represents an incoming RPC request.
@@ -164,15 +209,6 @@ type IRPCResponse = {
   /** Result of the RPC call if successful */
   result?: unknown;
 };
-type IRPCCache = {
-  data: IRPCData;
-  expiresAt: number;
-  timestamp: number;
-};
-/**
- * Represents a cache for RPC responses.
- */
-type IRPCCaches = Map<string, IRPCCache>;
 /**
  * Context storage mechanism for RPC operations.
  */
@@ -190,9 +226,25 @@ type IRPCContextProvider = {
   /** Gets the current context store */
   getStore<K, V>(): IRPCContext<K, V>;
 };
-type TransportConfig = {
+/**
+ * Configuration options for an RPC call.
+ */
+type IRPCCallConfig = {
+  /** Timeout for the RPC call in milliseconds */
   timeout?: number;
-  debounce?: number;
+  /** Maximum number of retries for the call */
+  maxRetries?: number;
+  /** Retry strategy mode - either linear or exponential backoff */
+  retryMode?: 'linear' | 'exponential';
+  /** Base delay between retries in milliseconds */
+  retryDelay?: number;
+};
+/**
+ * Configuration for transport layer, extending call configuration with debounce settings.
+ */
+type TransportConfig = IRPCCallConfig & {
+  /** Debounce setting for transport - can be a boolean to enable/disable or a number for specific delay */
+  debounce?: number | boolean;
 };
 //#endregion
-export { IRPCArraySchema, IRPCCache, IRPCCaches, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCError, IRPCHandler, IRPCInit, IRPCInputs, IRPCModule, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStubStore, TransportConfig };
+export { IRPCArraySchema, IRPCCallConfig, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCDeclareInit, IRPCError, IRPCEventType, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCPacketAnswer, IRPCPacketBase, IRPCPacketCall, IRPCPacketClose, IRPCPacketData, IRPCPacketEvent, IRPCPacketStream, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStubStore, TransportConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@irpclib/irpc",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.21",
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
   "exports": {
@@ -36,13 +36,16 @@
     "zod": "^4.1.5"
   },
   "scripts": {
-    "dev": "tsdown --watch",
+    "dev": "rimraf dist && tsdown --watch ./src",
     "clean": "rimraf dist",
-    "build": "tsdown && publint",
+    "build": "rimraf dist && tsdown && publint",
     "format": "biome format --write",
     "test": "rimraf coverage && vitest --run",
     "test:preview": "rimraf coverage && vitest --run && vite preview --outDir coverage",
     "prepublish": "bun run format && bun run clean && tsdown && publint"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@anchorlib/core": "1.0.0-beta.20"
+  }
 }

package/readme.md

@@ -1,52 +1,46 @@
 # @irpclib/irpc
 
-**Isomorphic Remote Procedure Call** - Call remote functions like local functions.
+**Stop thinking about the network. Just call functions.**
 
-```typescript
-// Instead of this:
-const response = await fetch('/api/hello');
-const data = await response.json();
+IRPC makes remote function calls and reactive streaming look and feel like local functions. Declare once, implement on the server, call from the client — no routes, no endpoints, no WebSocket configuration.
 
-// Just do this:
+```typescript
 const message = await hello('John');
+
+const call = loadDashboard('user-123');
+call.subscribe(state => console.log(state.data));
 ```
 
 ---
 
-## Why IRPC?
-
-**Beside the simplicity**, this is what you get:
-
-### Benchmark Results
-**Scenario:** 100,000 users, 10 calls each (1,000,000 total calls)
+## Performance
 
 | Framework | Total Time | HTTP Requests | Speedup |
 |-----------|------------|---------------|---------|
-| **IRPC** | **3,617ms** | **100,000** | **6.96x** 🚀 |
+| **IRPC** | **3,617ms** | **100,000** | **6.96x** |
 | Bun Native | 25,180ms | 1,000,000 | 1.00x |
 | Hono | 18,004ms | 1,000,000 | 1.40x |
 | Elysia | 36,993ms | 1,000,000 | 0.68x |
 
-**IRPC handled 1 million API calls in 3.6 seconds with 10x fewer HTTP connections.**
+**1 million API calls in 3.6 seconds with 10x fewer HTTP connections.**
 
 ---
 
 ## Features
 
-- ✅ **6.96x faster** than traditional REST
-- ✅ **10x fewer HTTP connections** (automatic batching)
-- ✅ **Type-safe** (end-to-end TypeScript)
-- ✅ **Zero boilerplate** (no routes, no endpoints)
-- ✅ **Transport agnostic** (HTTP, WebSocket, etc.)
-- ✅ **Built-in caching** (configurable per-call)
-- ✅ **Retry & timeout** (automatic error handling)
+- 6.96x faster than traditional REST APIs
+- 10x fewer HTTP connections through automatic batching
+- Native continuous reactive streaming via `RemoteState`
+- End-to-end type safety with TypeScript
+- Zero boilerplate — no routes or endpoints
+- Transport agnostic (HTTP, WebSocket, BroadcastChannel)
+- Built-in caching configurable per function
+- Automatic retry and timeout handling
 
 ---
 
 ## Quick Start
 
-### Create New Project
-
 ```bash
 npx degit beerush/anchor/templates/irpc-bun-app my-api
 cd my-api
@@ -92,9 +86,18 @@ irpc.use(transport);
 import { irpc } from '../lib/module.js';
 
 export type HelloFn = (name: string) => Promise<string>;
+export const hello = irpc.declare<HelloFn>({ name: 'hello' });
+```
 
-export const hello = irpc.declare<HelloFn>({
-  name: 'hello'
+```typescript
+// rpc/dashboard/index.ts
+import { irpc } from '../lib/module.js';
+import type { RemoteState } from '@irpclib/irpc';
+
+export type LoadDashboardFn = (userId: string) => RemoteState<DashboardData>;
+export const loadDashboard = irpc.declare<LoadDashboardFn>({
+  name: 'loadDashboard',
+  init: () => ({} as DashboardData), // Initial client-side state before server data arrives
 });
 ```
 
@@ -110,6 +113,22 @@ irpc.construct(hello, async (name) => {
 });
 ```
 
+```typescript
+// rpc/dashboard/constructor.ts
+import { irpc } from '../lib/module.js';
+import { loadDashboard } from './index.js';
+import { stream } from '@irpclib/irpc';
+
+irpc.construct(loadDashboard, (userId) => {
+  return stream((data, resolve) => {
+    const q1 = db.users.get(userId).then(res => data.user = res);
+    const q2 = db.sales.aggregate(userId).then(res => data.sales = res);
+    
+    Promise.all([q1, q2]).then(() => resolve());
+  }, {});
+});
+```
+
 ### 4. Setup Server
 
 ```typescript
@@ -118,7 +137,7 @@ import { setContextProvider } from '@irpclib/irpc';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { HTTPRouter } from '@irpclib/http';
 import { irpc, transport } from './lib/module.js';
-import './rpc/hello/constructor.js'; // Import handlers
+import './rpc/hello/constructor.js';
 
 setContextProvider(new AsyncLocalStorage());
 
@@ -137,16 +156,54 @@ Bun.serve({
 ### 5. Use on Client
 
 ```typescript
+// client.ts
 import { hello } from './rpc/hello/index.js';
+import { loadDashboard } from './rpc/dashboard/index.js';
 
+// Standard execution
 const message = await hello('John');
 console.log(message); // "Hello John"
+
+// Stream subscription
+const call = loadDashboard('user-123');
+call.subscribe(state => console.log('Hydration state:', state.data));
 ```
 
 ---
 
 ## Advanced Features
 
+### Call Configuration (Available at All Levels)
+
+Configure retry, timeout, and other call behaviors at **function**, **package**, or **transport** level:
+
+```typescript
+// Function-level (highest priority)
+const criticalFn = irpc.declare({
+  name: 'processPayment',
+  timeout: 30000,     // 30s timeout
+  maxRetries: 5,      // 5 retry attempts
+  retryMode: 'exponential',
+});
+
+// Package-level (medium priority)
+const irpc = createPackage({
+  name: 'my-api',
+  timeout: 10000,     // 10s default
+  maxRetries: 3,      // 3 retry attempts
+  retryMode: 'linear',
+});
+
+// Transport-level (lowest priority)
+const transport = new HTTPTransport({
+  endpoint: '/api',
+  timeout: 5000,      // 5s fallback
+  maxRetries: 1,      // 1 retry attempt
+});
+```
+
+**Priority Order:** Function → Package → Transport
+
 ### Caching
 
 ```typescript
@@ -156,15 +213,27 @@ export const getUser = irpc.declare<GetUserFn>({
 });
 ```
 
-### Timeout
+### Coalesce
+
+Combine multiple calls with identical arguments:
 
 ```typescript
-export const slowQuery = irpc.declare<SlowQueryFn>({
-  name: 'slowQuery',
-  timeout: 30000, // 30 second timeout
+export const expensiveQuery = irpc.declare<ExpensiveQueryFn>({
+  name: 'expensiveQuery',
+  coalesce: true,
 });
 ```
 
+### Cache Invalidation
+
+```typescript
+// Invalidate specific cache entry
+irpc.invalidate(getUser, 'user-123');
+
+// Invalidate all cache for a function
+irpc.invalidate(getUser);
+```
+
 ### Validation (Optional Zod)
 
 ```typescript