@irpclib/irpc 0.0.2 → 1.0.0-beta.16

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-import { IRPCCall } from "./call.js";
+import { ErrorCode } from "./error.js";
+import { IRPCTransport } from "./transport.js";
 import { ZodArray, ZodBoolean, ZodNull, ZodNumber, ZodObject, ZodSafeParseResult, ZodString, ZodUndefined } from "zod/v4";
 
 //#region src/types.d.ts
@@ -7,17 +8,12 @@ import { ZodArray, ZodBoolean, ZodNull, ZodNumber, ZodObject, ZodSafeParseResult
  * A registry that maps IRPCHandlers to their corresponding IRPCHosts.
  * Uses WeakMap to avoid memory leaks by not preventing garbage collection of handlers.
  */
-type IRPCRegistry = WeakMap<IRPCHandler, IRPCHost<IRPCInputs, IRPCOutput>>;
+type IRPCStubStore = WeakMap<IRPCHandler, IRPCSpec<IRPCInputs, IRPCOutput>>;
 /**
  * A store that maps string identifiers to IRPCHosts.
  * Used to keep track of available RPC hosts by their names.
  */
-type IRPCStore = Map<string, IRPCHost<IRPCInputs, IRPCOutput>>;
-/**
- * A function that authorizes RPC requests.
- * Takes a Request object and returns a boolean (sync or async) indicating authorization status.
- */
-type IRPCAuthorizer = (req: Request) => Promise<boolean> | boolean;
+type IRPCSpecStore = Map<string, IRPCSpec<IRPCInputs, IRPCOutput>>;
 /**
  * Represents primitive data types that can be used in IRPC communications.
  * Includes string, number, boolean, null, and undefined.
@@ -66,7 +62,7 @@ type IRPCOutput = IRPCDataSchema;
 /**
  * Defines the basic information about an RPC namespace.
  */
-type IRPCNamespace = {
+type IRPCPackageInfo = {
   /** The name of the namespace */
   name: string;
   /** The version of the namespace */
@@ -74,12 +70,14 @@ type IRPCNamespace = {
   /** 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 = IRPCNamespace & {
-  /** Optional function to submit RPC calls */
-  submit?: (calls: IRPCCall[]) => Promise<IRPCResponse[]>;
+type IRPCModule = IRPCPackageInfo & {
   /** Optional timeout for RPC calls */
   timeout?: number;
   /** Optional transport mechanism for RPC communications */
@@ -107,73 +105,37 @@ type IRPCSchema<I extends IRPCInputs, O extends IRPCOutput> = {
  * Type definition for an RPC handler function.
  * Takes IRPCData arguments and returns a Promise resolving to IRPCData.
  */
-type IRPCHandler = (...args: IRPCData[]) => Promise<IRPCData>;
+type IRPCHandler = Function;
 /**
- * Specification for an RPC function including its name, schema, and description.
+ * Configuration options for initializing an RPC function.
+ * Contains metadata and constraints for the RPC function.
+ *
+ * @template I - Tuple of input validation schemas
+ * @template O - Output validation schema
  */
-type IRPCSpec<I extends IRPCInputs, O extends IRPCOutput> = {
+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 maximum age of a call in milliseconds */
+  maxAge?: number;
+  /** Optional timeout for RPC calls */
+  timeout?: number;
 };
 /**
- * Host definition for an RPC function that combines the specification with execution details.
+ * Complete specification for an RPC function including its implementation.
+ * Extends IRPCInit with the actual handler function.
+ *
+ * @template I - Tuple of input validation schemas
+ * @template O - Output validation schema
  */
-type IRPCHost<I extends IRPCInputs, O extends IRPCOutput> = IRPCSpec<I, O> & {
+type IRPCSpec<I extends IRPCInputs, O extends IRPCOutput> = IRPCInit<I, O> & {
   /** The actual handler function that implements the RPC */
   handler: IRPCHandler;
 };
-/**
- * Factory interface for creating and managing RPC functions.
- */
-interface IRPCFactory {
-  /**
-   * Creates a new RPC function with the given specification.
-   * @param spec The specification for the RPC function
-   */
-  <F, I extends IRPCInputs = IRPCInputs, O extends IRPCOutput = IRPCOutput>(spec: IRPCSpec<I, O>): F;
-  /** The namespace associated with this factory */
-  get namespace(): IRPCNamespace;
-  /**
-   * Gets the endpoint URL for this factory.
-   * @param prefix Optional prefix to prepend to the endpoint, default to '/irpc'
-   */
-  endpoint(prefix?: string): string;
-  /**
-   * Sets the transport mechanism for this factory.
-   * @param transport The transport to use
-   */
-  use(transport: IRPCTransport): IRPCFactory;
-  /**
-   * Gets the specification for an RPC function by name.
-   * @param name The name of the RPC function
-   */
-  get<I extends IRPCInputs, O extends IRPCOutput>(name: string): IRPCSpec<I, O>;
-  /**
-   * Configures the module settings for this factory.
-   * @param config Partial configuration for the module
-   */
-  configure(config: Partial<IRPCModule>): IRPCFactory;
-  /**
-   * Constructs an RPC function with its handler.
-   * @param irpc The RPC function
-   * @param handler The handler that implements the RPC function
-   */
-  construct<F>(irpc: F, handler: F): IRPCFactory;
-  /**
-   * Gets information about an RPC request.
-   * @param req The RPC request
-   */
-  info<I extends IRPCInputs, O extends IRPCOutput>(req: IRPCRequest): IRPCSpec<I, O>;
-  /**
-   * Resolves an RPC request.
-   * @param req The RPC request to resolve
-   */
-  resolve<R>(req: IRPCRequest): Promise<R>;
-}
 /**
  * Represents an incoming RPC request.
  */
@@ -185,6 +147,10 @@ type IRPCRequest = {
   /** Arguments for the RPC function */
   args: unknown[];
 };
+type IRPCError = {
+  code: ErrorCode;
+  message: string;
+};
 /**
  * Represents an RPC response.
  */
@@ -194,24 +160,23 @@ type IRPCResponse = {
   /** Name of the RPC function that was called */
   name: string;
   /** Error message if the call failed */
-  error?: string;
+  error?: IRPCError;
   /** Result of the RPC call if successful */
   result?: unknown;
 };
+type IRPCCache = {
+  data: IRPCData;
+  expiresAt: number;
+  timestamp: number;
+};
 /**
- * Abstract base class for RPC transport mechanisms.
+ * Represents a cache for RPC responses.
  */
-declare abstract class IRPCTransport {
-  /**
-   * Sends RPC calls and returns the responses.
-   * @param calls Array of RPC calls to send
-   */
-  abstract send(calls: IRPCCall[]): Promise<IRPCResponse[]>;
-}
+type IRPCCaches = Map<string, IRPCCache>;
 /**
  * Context storage mechanism for RPC operations.
  */
-type IRPCContext<K, V> = Map<K, V>;
+type IRPCContext<K$1, V$1> = Map<K$1, V$1>;
 /**
  * Interface for managing RPC context stores.
  */
@@ -225,5 +190,9 @@ type IRPCContextProvider = {
   /** Gets the current context store */
   getStore<K, V>(): IRPCContext<K, V>;
 };
+type TransportConfig = {
+  timeout?: number;
+  debounce?: number;
+};
 //#endregion
-export { IRPCArraySchema, IRPCAuthorizer, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCFactory, IRPCHandler, IRPCHost, IRPCInputs, IRPCModule, IRPCNamespace, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCRegistry, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCStore, IRPCTransport };
+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 };

package/dist/types.js

@@ -1,8 +1 @@
-//#region src/types.ts
-/**
-* Abstract base class for RPC transport mechanisms.
-*/
-var IRPCTransport = class {};
-
-//#endregion
-export { IRPCTransport };
+export {  };

package/dist/uuid.d.ts

@@ -0,0 +1,21 @@
+//#region src/uuid.d.ts
+/**
+ * A function that generates a random UUID string.
+ *
+ * @returns A UUID v4 string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+type UUIDProvider = () => string;
+/**
+ * Generates a new UUID using the currently configured provider.
+ *
+ * @returns A UUID string generated by the current provider
+ */
+declare function uuid(): string;
+/**
+ * Sets a custom UUID provider function to be used by the uuid() function.
+ *
+ * @param provider - A function that returns a UUID string when called
+ */
+declare function setUUIDProvider(provider: UUIDProvider): void;
+//#endregion
+export { UUIDProvider, setUUIDProvider, uuid };

package/dist/uuid.js

@@ -0,0 +1,45 @@
+//#region src/uuid.ts
+/**
+* Generates a random UUID v4 string using a simple algorithm.
+*
+* @returns A UUID v4 string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+*/
+function simpleId() {
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+/**
+* Default UUID provider that attempts to use the crypto API if available,
+* otherwise falls back to a simpler implementation.
+*
+* @returns A UUID v4 string
+*/
+function defaultUUIDProvider() {
+	if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return simpleId();
+}
+/**
+* The currently active UUID provider function.
+*/
+let uuidProvider = defaultUUIDProvider;
+/**
+* Generates a new UUID using the currently configured provider.
+*
+* @returns A UUID string generated by the current provider
+*/
+function uuid() {
+	return (uuidProvider ?? defaultUUIDProvider)();
+}
+/**
+* Sets a custom UUID provider function to be used by the uuid() function.
+*
+* @param provider - A function that returns a UUID string when called
+*/
+function setUUIDProvider(provider) {
+	uuidProvider = provider;
+}
+
+//#endregion
+export { setUUIDProvider, uuid };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@irpclib/irpc",
-  "version": "0.0.2",
+  "version": "1.0.0-beta.16",
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
   "exports": {
@@ -10,9 +10,7 @@
       "import": "./dist/index.js"
     }
   },
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "directories": {
     "dist": "./dist"
   },
@@ -21,20 +19,18 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.3",
+    "@types/bun": "1.3.1",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "esbuild-raw-plugin": "^0.3.1",
-    "prettier": "^3.6.2",
-    "publint": "^0.3.15",
-    "rimraf": "^6.0.1",
-    "tsdown": "^0.15.9",
-    "vite": "^7.1.10",
+    "publint": "0.3.15",
+    "rimraf": "6.0.1",
+    "tsdown": "0.15.9",
+    "vite": "7.1.12",
     "vitest": "^3.2.4",
-    "zod": "^4.1.5",
-    "@types/bun": "1.3.1"
+    "zod": "^4.1.5"
   },
   "peerDependencies": {
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.3"
   },
   "optionalDependencies": {
     "zod": "^4.1.5"
@@ -49,4 +45,4 @@
     "prepublish": "bun run format && bun run clean && tsdown && publint"
   },
   "license": "MIT"
-}
+}

package/readme.md

@@ -1,166 +1,194 @@
-# IRPC - Isomorphic Remote Procedure Call
+# @irpclib/irpc
 
-IRPC (Isomorphic Remote Procedure Call) is a revolutionary approach to distributed computing that eliminates the cognitive overhead of network communication. It enables developers to invoke remote functions with the same ergonomics as local function calls, abstracting away the transport layer entirely.
+**Isomorphic Remote Procedure Call** - Call remote functions like local functions.
 
-Unlike traditional approaches like REST APIs, GraphQL, or gRPC, IRPC removes the need to think about endpoints, serialization, or transport protocols. You focus on business logic while IRPC handles the communication complexity transparently.
+```typescript
+// Instead of this:
+const response = await fetch('/api/hello');
+const data = await response.json();
 
-## Learn More
+// Just do this:
+const message = await hello('John');
+```
 
-For detailed documentation, visit [https://irpc.anchorlib.dev](https://irpc.anchorlib.dev)
+---
 
-## Quick Start
+## Why IRPC?
 
-### Create a Module
+**Beside the simplicity**, this is what you get:
 
-```ts
-import { createModule } from '@irpclib/irpc';
+### Benchmark Results
+**Scenario:** 100,000 users, 10 calls each (1,000,000 total calls)
 
-const irpc = createModule({ name: 'my-module', version: '1.0.0' });
-```
+| Framework | Total Time | HTTP Requests | Speedup |
+|-----------|------------|---------------|---------|
+| **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 |
 
-### Define Functions
+**IRPC handled 1 million API calls in 3.6 seconds with 10x fewer HTTP connections.**
 
-```ts
-export const greet = irpc<(name: string) => Promise<string>>({
-  name: 'greet'
-});
-```
+---
 
-### Set up Transport (Client-side)
+## Features
 
-```ts
-import { HTTPTransport } from '@irpclib/http';
+- ✅ **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)
 
-export const transport = new HTTPTransport(
-  {
-    baseURL: 'http://localhost:3000',
-    endpoint: '/rpc',
-  },
-  irpc
-);
-```
+---
+
+## Quick Start
 
-### Implement Handlers (Server-side)
+### Create New Project
 
-```ts
-irpc.construct(greet, async (name) => {
-  return `Hello, ${name}!`;
-});
+```bash
+npx degit beerush/anchor/templates/irpc-bun-app my-api
+cd my-api
+bun install
+bun run serve
 ```
 
-### Server Setup
+Server runs on `http://localhost:3000`
 
-```ts
-import { setContextStore } from '@irpclib/irpc';
-import { AsyncLocalStorage } from 'async_hooks';
+---
 
-setContextStore(new AsyncLocalStorage());
+## Manual Setup
 
-Bun.serve({
-  routes: {
-    [transport.endpoint]: {
-      GET: () => new Response('OK'),
-      POST: (req) => transport.respond(req),
-    }
-  },
-});
+### Installation
+
+```bash
+npm install @irpclib/irpc @irpclib/http
 ```
 
-### Client Usage
+### 1. Create Package
 
-```ts
-import { greet } from './my-module';
+```typescript
+// lib/module.ts
+import { createPackage } from '@irpclib/irpc';
+import { HTTPTransport } from '@irpclib/http';
 
-const message = await greet('World');
-console.log(message); // "Hello, World!"
-```
+export const irpc = createPackage({ 
+  name: 'my-api', 
+  version: '1.0.0' 
+});
 
-## Key Features
+export const transport = new HTTPTransport({
+  endpoint: `/irpc/${irpc.href}`,
+});
 
-- **Isomorphic Design**: Call functions identically on client and server
-- **Zero Boilerplate**: No REST endpoints, no GraphQL schemas, no complex serialization
-- **Transport Agnostic**: Switch between HTTP, WebSockets, and other transports without changing your business logic
-- **End-to-End Type Safety**: Compile-time validation from client to server
-- **Performance Optimized**: Intelligent batching and connection reuse
+irpc.use(transport);
+```
 
-## Core Components
+### 2. Declare Functions
 
-### Module
+```typescript
+// rpc/hello/index.ts
+import { irpc } from '../lib/module.js';
 
-A module is a container for your IRPC functions. It manages the registry of functions and their implementations.
+export type HelloFn = (name: string) => Promise<string>;
 
-```ts
-const irpc = createModule({ name: 'fs', version: '1.0.0' });
+export const hello = irpc.declare<HelloFn>({
+  name: 'hello'
+});
 ```
 
-### Function
+### 3. Implement Handlers (Server)
 
-Functions are the core building blocks of IRPC. They define the interface for remote calls and can be implemented on the server side.
+```typescript
+// rpc/hello/constructor.ts
+import { irpc } from '../lib/module.js';
+import { hello } from './index.js';
 
-```ts
-export const readFile = irpc<(path: string) => Promise<string>>('readFile');
+irpc.construct(hello, async (name) => {
+  return `Hello ${name}`;
+});
 ```
 
-### Transport
-
-Transports handle the actual communication between client and server. IRPC is transport-agnostic, allowing you to switch between different communication protocols.
+### 4. Setup Server
 
-```ts
-export const transport = new IRPCHttpTransport(
-  {
-    baseURL: 'http://localhost:3000',
-    endpoint: '/rpc',
-    timeout: 1000,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-  },
-  irpc
-);
-```
+```typescript
+// server.ts
+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
 
-The transport automatically registers itself with the IRPC module during construction, so there's no need to manually register it.
+setContextProvider(new AsyncLocalStorage());
 
-## Usage
+const router = new HTTPRouter(irpc, transport);
 
-### Client
+Bun.serve({
+  port: 3000,
+  routes: {
+    [transport.endpoint]: {
+      POST: (req) => router.resolve(req),
+    }
+  },
+});
+```
 
-On the client side, you simply import and call your functions as if they were local:
+### 5. Use on Client
 
-```ts
-import { readFile } from './fs';
+```typescript
+import { hello } from './rpc/hello/index.js';
 
-console.log(await readFile('/path/to/file'));
+const message = await hello('John');
+console.log(message); // "Hello John"
 ```
 
-### Server
-
-On the server side, you implement the actual functionality for your functions:
+---
 
-```ts
-import { transport } from './fs';
-import { setContextStore } from '@irpclib/irpc';
+## Advanced Features
 
-setContextStore(new AsyncLocalStorage());
+### Caching
 
-Bun.serve({
-  routes: {
-    [transport.endpoint]: {
-      GET: () => {
-        return new Response('Ok!');
-      },
-      POST: (req) => transport.respond(req),
-    }
-  },
+```typescript
+export const getUser = irpc.declare<GetUserFn>({
+  name: 'getUser',
+  maxAge: 60000, // Cache for 60 seconds
 });
 ```
 
-#### Handler
+### Timeout
 
-Handlers are the actual implementations of your remote functions:
+```typescript
+export const slowQuery = irpc.declare<SlowQueryFn>({
+  name: 'slowQuery',
+  timeout: 30000, // 30 second timeout
+});
+```
 
-```ts
-irpc.construct(readFile, async (path) => {
-  // Implementation goes here
+### Validation (Optional Zod)
+
+```typescript
+import { z } from 'zod';
+
+export const createUser = irpc.declare({
+  name: 'createUser',
+  input: [z.object({
+    name: z.string(),
+    email: z.string().email(),
+  })],
+  output: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
 });
 ```
+
+---
+
+## Documentation
+
+For detailed documentation, visit [https://anchorlib.dev/docs/irpc](https://anchorlib.dev/docs/irpc)
+
+## License
+
+MIT

package/dist/batch.d.ts

@@ -1,18 +0,0 @@
-import { IRPCCall } from "./call.js";
-
-//#region src/batch.d.ts
-
-/**
- * Batches multiple IRPC calls together and executes them with a specified delay.
- *
- * This function collects IRPC calls in a queue and executes them all at once after
- * a specified delay has passed. If multiple calls are made within the delay period,
- * they will be grouped together in a single batch execution.
- *
- * @param call - The IRPC call to be added to the current batch
- * @param handler - A function that will be called with all queued calls when the batch executes
- * @param delay - The delay in milliseconds before executing the batch (default: 0)
- */
-declare function batch(call: IRPCCall, handler: (calls: IRPCCall[]) => void, delay?: number): void;
-//#endregion
-export { batch };

package/dist/batch.js

@@ -1,23 +0,0 @@
-//#region src/batch.ts
-const IRPC_QUEUE = /* @__PURE__ */ new Set();
-/**
-* Batches multiple IRPC calls together and executes them with a specified delay.
-*
-* This function collects IRPC calls in a queue and executes them all at once after
-* a specified delay has passed. If multiple calls are made within the delay period,
-* they will be grouped together in a single batch execution.
-*
-* @param call - The IRPC call to be added to the current batch
-* @param handler - A function that will be called with all queued calls when the batch executes
-* @param delay - The delay in milliseconds before executing the batch (default: 0)
-*/
-function batch(call, handler, delay = 0) {
-	if (!IRPC_QUEUE.size) setTimeout(() => {
-		handler([...IRPC_QUEUE.values()]);
-		IRPC_QUEUE.clear();
-	}, delay);
-	IRPC_QUEUE.add(call);
-}
-
-//#endregion
-export { batch };