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

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