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

package/dist/types.d.ts

@@ -1,7 +1,9 @@
-import { IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
+import { IRPC_BASE_CONTEXT, IRPC_DATA_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
 import { ErrorCode } from "./error.js";
+import { IRPCFile } from "./file.js";
 import { IRPCTransport } from "./transport.js";
 import { RemoteState } from "./state.js";
+import { IRPCReader } from "./reader.js";
 import { StateChange } from "@anchorlib/core";
 import { ZodArray, ZodBoolean, ZodNull, ZodNumber, ZodObject, ZodSafeParseResult, ZodString, ZodUndefined } from "zod/v4";
 
@@ -20,7 +22,7 @@ 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 IRPCBaseContext = (typeof IRPC_BASE_CONTEXT)[keyof typeof IRPC_BASE_CONTEXT];
 type IRPCPacketBase = {
   id: string;
   name: string;
@@ -29,10 +31,6 @@ type IRPCPacketBase = {
   createdAt?: number;
   arrivedAt?: number;
 };
-type IRPCPacketData = {
-  type: IRPCDataType;
-  value: IRPCData;
-};
 type IRPCPacketCall = IRPCPacketBase & {
   args: IRPCData[];
 };
@@ -52,6 +50,53 @@ interface IRPCReadable<T> {
   error: Error | undefined;
   status: IRPCStatus;
 }
+/**
+ * Represents a client-side stub for a remote function.
+ * When called, it returns an IRPCReader to handle the asynchronous result or stream.
+ *
+ * @template T - The original function type.
+ * @template A - The argument types of the function.
+ * @template R - The return data type.
+ */
+interface IRPCStub<T, A$1 extends unknown[], R$1 extends IRPCData> {
+  (...args: A$1): IRPCReader<R$1>;
+  stub: T;
+  /**
+   * Creates a call that expect to run in browser environment.
+   * The function runs immediately on the browser and will not re-run.
+   *
+   * @param args - A factory function returning the argument array.
+   * @returns An IRPCReader instance for handling the asynchronous result or stream.
+   */
+  once(...args: A$1): IRPCReader<R$1>;
+  /**
+   * Creates a reactive call that expect to run in browser environment.
+   * The function runs immediately on the browser and will re-run when
+   * the reactive dependencies change.
+   *
+   * @param args - A factory function returning the argument array.
+   * @param debounce - The debounce time in milliseconds.
+   * @returns An IRPCReader instance for handling the asynchronous result or stream.
+   */
+  with(args: () => A$1, debounce?: number): IRPCReader<R$1>;
+  /**
+   * Creates a reactive call that expect to run in browser environment.
+   * The function only runs on the first dependency change and re-run
+   * when the reactive dependencies change.
+   *
+   * @param args - A factory function returning the argument array.
+   * @param debounce - The debounce time in milliseconds.
+   * @returns An IRPCReader instance for handling the asynchronous result or stream.
+   */
+  when(args: () => A$1, debounce?: number): IRPCReader<R$1>;
+}
+/**
+ * A utility type that transforms a standard function type into its corresponding IRPCStub.
+ * It automatically unwraps RemoteState types to determine the underlying data type.
+ *
+ * @template T - The function type to be transformed.
+ */
+type IRPCFunction<T> = T extends ((...args: infer A) => infer R) ? R extends RemoteState<infer S> ? S extends IRPCData ? IRPCStub<T, A, S> : IRPCStub<T, A, IRPCData> : R extends Promise<infer O> ? O extends IRPCData ? IRPCStub<T, A, O> : IRPCStub<T, A, IRPCData> : R extends IRPCData ? IRPCStub<T, A, R> : IRPCStub<T, A, IRPCData> : IRPCStub<T, [], IRPCData>;
 /**
  * Represents primitive data types that can be used in IRPC communications.
  * Includes string, number, boolean, null, and undefined.
@@ -68,7 +113,7 @@ type IRPCObject = {
  * Represents all possible data types in IRPC, including primitives, objects, and arrays.
  * This is a recursive type that allows nested structures.
  */
-type IRPCData = IRPCPrimitive | IRPCObject | IRPCData[];
+type IRPCData = IRPCPrimitive | IRPCObject | IRPCFile | IRPCData[];
 /**
  * Union type of all primitive Zod schema types used for validation.
  */
@@ -123,11 +168,11 @@ type IRPCPayload = {
 /**
  * Defines the schema for input and output validation of an RPC function.
  */
-type IRPCSchema<I extends IRPCInputs, O extends IRPCOutput> = {
+type IRPCSchema<I extends IRPCInputs, O$1 extends IRPCOutput> = {
   /** Optional input validation schemas */
   input?: I;
   /** Optional output validation schema */
-  output?: O;
+  output?: O$1;
 };
 /**
  * Type definition for an RPC handler function.
@@ -141,13 +186,13 @@ type IRPCHandler = Function;
  * @template I - Tuple of input validation schemas
  * @template O - Output validation schema
  */
-type IRPCInit<I extends IRPCInputs, O extends IRPCOutput> = {
+type IRPCInit<R$1, I extends IRPCInputs, O$1 extends IRPCOutput> = {
   /** The name of the RPC function */
   name: string;
   /** Optional description of the RPC function */
   description?: string;
   /** Optional schema for input/output validation */
-  schema?: IRPCSchema<I, O>;
+  schema?: IRPCSchema<I, O$1>;
   /** Optional maximum age of a call in milliseconds */
   maxAge?: number;
   /**
@@ -157,7 +202,20 @@ type IRPCInit<I extends IRPCInputs, O extends IRPCOutput> = {
    * This can help reduce the number of actual function executions.
    */
   coalesce?: boolean;
+  /** Optional initialization function to seed the data */
+  init?: () => R$1;
 } & IRPCCallConfig;
+/**
+ * Configuration options for initializing an RPC stream function.
+ * Contains metadata and constraints for the RPC stream function.
+ *
+ * @template I - Tuple of input validation schemas
+ * @template O - Output validation schema
+ */
+type IRPCStreamInit<I extends IRPCInputs, O$1 extends IRPCOutput, R$1> = IRPCInit<R$1, I, O$1> & {
+  stream: true;
+  ttl?: number;
+};
 /**
  * Type definition for an RPC declaration.
  * Represents an RPC function with its name, description, and configuration.
@@ -166,9 +224,7 @@ type IRPCInit<I extends IRPCInputs, O extends IRPCOutput> = {
  * @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>;
+type IRPCDeclareInit<F, I extends IRPCInputs, O$1 extends IRPCOutput> = F extends ((...args: IRPCData[]) => infer R) ? R extends RemoteState<infer S> ? S extends IRPCData ? IRPCStreamInit<I, O$1, S> : IRPCInit<IRPCData, IRPCInputs, IRPCOutput> : R extends Promise<infer D> ? D extends IRPCData ? IRPCInit<D, I, O$1> : IRPCInit<IRPCData, IRPCInputs, IRPCOutput> : R extends IRPCData ? IRPCInit<R, I, O$1> : IRPCInit<IRPCData, IRPCInputs, IRPCOutput> : IRPCInit<IRPCData, IRPCInputs, IRPCOutput>;
 /**
  * Complete specification for an RPC function including its implementation.
  * Extends IRPCInit with the actual handler function.
@@ -176,9 +232,14 @@ type IRPCDeclareInit<F, I extends IRPCInputs, O extends IRPCOutput> = F extends
  * @template I - Tuple of input validation schemas
  * @template O - Output validation schema
  */
-type IRPCSpec<I extends IRPCInputs, O extends IRPCOutput> = IRPCInit<I, O> & {
+type IRPCSpec<I extends IRPCInputs, O$1 extends IRPCOutput> = IRPCInit<IRPCData, I, O$1> & {
+  /** Optional time-to-live for a call in milliseconds */
+  ttl?: number;
+  /** Whether to stream the result of the RPC call */
+  stream?: boolean;
   /** The actual handler function that implements the RPC */
   handler: IRPCHandler;
+  /** Optional initialization function for a stream RPC */
   init?: () => unknown;
 };
 /**
@@ -238,6 +299,8 @@ type IRPCCallConfig = {
   retryMode?: 'linear' | 'exponential';
   /** Base delay between retries in milliseconds */
   retryDelay?: number;
+  /** Optional initialization function for a stream RPC */
+  init?: () => unknown;
 };
 /**
  * Configuration for transport layer, extending call configuration with debounce settings.
@@ -246,5 +309,17 @@ type TransportConfig = IRPCCallConfig & {
   /** Debounce setting for transport - can be a boolean to enable/disable or a number for specific delay */
   debounce?: number | boolean;
 };
+type StreamCleanup = () => void;
+/**
+ * A callback function type used to natively construct and drive a reactive stream.
+ * It provides the initial reactive data reference and terminal resolution hooks
+ * without forcing strict async/await boundaries, securely yielding stream operations.
+ *
+ * @template T - The type of data yielded globally by the stream.
+ * @param state - The reactive state reference for the stream.
+ * @param resolve - Callback to statically mark the stream as successfully completed, optionally with a resolved value.
+ * @param reject - Callback to forcefully throw a runtime error into the stream structure.
+ */
+type StreamConstructor<T> = (state: IRPCReadable<T>, resolve: (value?: T) => void, reject: (error: Error) => void) => StreamCleanup | void | Promise<StreamCleanup | void>;
 //#endregion
-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 };
+export { IRPCArraySchema, IRPCBaseContext, IRPCCallConfig, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCDeclareInit, IRPCError, IRPCFunction, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCPacketAnswer, IRPCPacketBase, IRPCPacketCall, IRPCPacketClose, IRPCPacketEvent, IRPCPacketStream, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStreamInit, IRPCStub, IRPCStubStore, StreamCleanup, StreamConstructor, TransportConfig };

package/package.json

@@ -1,13 +1,17 @@
 {
   "type": "module",
   "name": "@irpclib/irpc",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.23",
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
     }
   },
   "files": ["dist"],
@@ -25,7 +29,7 @@
     "publint": "0.3.15",
     "rimraf": "6.0.1",
     "tsdown": "0.15.9",
-    "vite": "7.1.12",
+    "vite": "8.0.10",
     "vitest": "^3.2.4",
     "zod": "^4.1.5"
   },
@@ -46,6 +50,6 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@anchorlib/core": "1.0.0-beta.20"
+    "@anchorlib/core": "^1.0.0-beta.23"
   }
 }

package/readme.md

@@ -120,7 +120,7 @@ import { loadDashboard } from './index.js';
 import { stream } from '@irpclib/irpc';
 
 irpc.construct(loadDashboard, (userId) => {
-  return stream((data, resolve) => {
+  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);
     
@@ -131,6 +131,8 @@ irpc.construct(loadDashboard, (userId) => {
 
 ### 4. Setup Server
 
+The integration point extracts application-level values from transport-specific objects and injects them as standardized context via `initContext`. This keeps middleware and handlers transport-agnostic.
+
 ```typescript
 // server.ts
 import { setContextProvider } from '@irpclib/irpc';
@@ -147,7 +149,10 @@ Bun.serve({
   port: 3000,
   routes: {
     [transport.endpoint]: {
-      POST: (req) => router.resolve(req),
+      POST: (req) => router.resolve(req, [
+        ['token', req.headers.get('authorization')],
+        ['locale', req.headers.get('accept-language')],
+      ]),
     }
   },
 });
@@ -256,7 +261,7 @@ export const createUser = irpc.declare({
 
 ## Documentation
 
-For detailed documentation, visit [https://anchorlib.dev/docs/irpc](https://anchorlib.dev/docs/irpc)
+For detailed documentation, visit [https://airlib.dev/irpc](https://airlib.dev/irpc)
 
 ## License
 

package/dist/uuid.d.ts

@@ -1,21 +0,0 @@
-//#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

@@ -1,45 +0,0 @@
-//#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 };