@vitejs/devtools-rpc 0.0.0-alpha.3 → 0.0.0-alpha.30

package/README.md

@@ -0,0 +1,214 @@
+# @vitejs/devtools-rpc
+
+DevTools RPC for Vite, featuring extensible [birpc](https://github.com/antfu-collective/birpc) interfaces with advanced type-safe function definitions.
+
+## Features
+
+- **Type-safe function definitions** with automatic type inference
+- **Dynamic function registration** with hot updates
+- **User-provided function context** for setup and handlers
+- **Schema validation** via [`valibot`](https://valibot.dev)
+- **Cache Manager** for RPC result caching
+- **Dump feature** for pre-computing results (static hosting, testing, offline mode)
+- **Basic RPC Client/Server** built on birpc
+- **WebSocket Presets** ready-to-use transport presets
+
+## Installation
+
+```bash
+pnpm install @vitejs/devtools-rpc
+```
+
+## Usage
+
+### Basic RPC Client/Server
+
+```ts
+import { createRpcClient } from '@vitejs/devtools-rpc/client'
+import { createWsRpcPreset } from '@vitejs/devtools-rpc/presets/ws/client'
+import { createRpcServer } from '@vitejs/devtools-rpc/server'
+```
+
+### Defining Functions
+
+Use `defineRpcFunction` to create type-safe RPC function definitions:
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-rpc'
+
+// Simple function
+const greet = defineRpcFunction({
+  name: 'greet',
+  handler: (name: string) => `Hello, ${name}!`
+})
+```
+
+You can provide a context to functions for setup and initialization:
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-rpc'
+
+// With setup and context
+const getUser = defineRpcFunction({
+  name: 'getUser',
+  setup: (context) => {
+    console.log(context)
+    return {
+      handler: (id: string) => context.users[id]
+    }
+  }
+})
+```
+
+#### Schema Validation
+
+Use Valibot schemas for automatic argument and return value validation:
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-rpc'
+import * as v from 'valibot'
+
+const add = defineRpcFunction({
+  name: 'add',
+  args: [v.number(), v.number()] as const,
+  returns: v.number(),
+  handler: (a, b) => a + b // Types are automatically inferred
+})
+```
+
+### Function Collector
+
+`RpcFunctionsCollector` manages dynamic function registration and provides a type-safe proxy for accessing functions:
+
+```ts
+import { defineRpcFunction, RpcFunctionsCollectorBase } from '@vitejs/devtools-rpc'
+
+// Provide a custom context to the collector
+const collector = new RpcFunctionsCollectorBase({ users: [/* ... */] })
+
+// Register functions
+collector.register(defineRpcFunction({
+  name: 'greet',
+  handler: (name: string) => `Hello, ${name}!`,
+}))
+collector.register(defineRpcFunction({
+  name: 'getUser',
+  setup: (context) => {
+    return {
+      handler: (id: string) => context.users.find((user: { id: string }) => user.id === id)
+    }
+  }
+}))
+
+// Access via proxy
+await collector.functions.greet('Alice') // "Hello, Alice!"
+
+// Listen for changes
+const unsubscribe = collector.onChanged((fnName) => {
+  console.log(`Function ${fnName} changed`)
+})
+```
+
+### Dump Feature
+
+The dump feature allows pre-computing RPC results for static hosting, testing, or offline mode. This is useful for static sites or when you want to avoid runtime computation.
+
+```ts
+import { createClientFromDump, defineRpcFunction, dumpFunctions } from '@vitejs/devtools-rpc'
+
+// Define functions with dump configurations
+const greet = defineRpcFunction({
+  name: 'greet',
+  handler: (name: string) => `Hello, ${name}!`,
+  dump: {
+    inputs: [
+      ['Alice'],
+      ['Bob'],
+      ['Charlie']
+    ],
+    fallback: 'Hello, stranger!'
+  }
+})
+
+// Collect pre-computed results
+const store = await dumpFunctions([greet])
+
+// Create a client that serves from the dump store
+const client = createClientFromDump(store)
+
+await client.greet('Alice') // Returns pre-computed: "Hello, Alice!"
+await client.greet('Unknown') // Returns fallback: "Hello, stranger!"
+```
+
+Functions with `type: 'static'` automatically get dumped with empty arguments if no dump configuration is provided.
+
+#### Pre-computed Records
+
+You can provide pre-computed records directly to bypass function execution:
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-rpc'
+
+const multiply = defineRpcFunction({
+  name: 'multiply',
+  handler: (a: number, b: number) => a * b,
+  dump: {
+    records: [
+      { inputs: [2, 3], output: 6 },
+      { inputs: [4, 5], output: 20 },
+    ],
+  },
+})
+```
+
+You can also mix computed (`inputs`) and pre-computed (`records`) in the same dump configuration.
+
+#### Parallel Execution
+
+Enable parallel processing for faster dump collection:
+
+```ts
+import { dumpFunctions } from '@vitejs/devtools-rpc'
+
+// Enable parallel with default concurrency of 5
+const store = await dumpFunctions([greet], context, {
+  concurrency: true
+})
+
+// Or specify a custom concurrency limit
+const store = await dumpFunctions([greet], context, {
+  concurrency: 10 // Limit to 10 concurrent executions
+})
+```
+
+Set `concurrency` to `true` for parallel execution (default limit: 5) or a number to specify the exact concurrency limit.
+
+## Package Exports
+
+- **`.`** - Type-safe function definitions and utilities (main export)
+  - `RpcFunctionsCollectorBase`, `defineRpcFunction`, `createDefineWrapperWithContext`
+  - `dumpFunctions`, `createClientFromDump`, `RpcCacheManager`
+  - Type definitions and utilities
+
+- **`./client`** - RPC client
+  - `createRpcClient`
+
+- **`./server`** - RPC server
+  - `createRpcServer`
+
+- **`./presets`** - RPC presets
+  - `defineRpcClientPreset`, `defineRpcServerPreset`
+
+- **`./presets/ws/client`** - WebSocket client preset
+  - `createWsRpcPreset`
+
+- **`./presets/ws/server`** - WebSocket server preset
+  - `createWsRpcPreset`
+
+## Examples
+
+See [src/examples](./src/examples) and [test files](./src) for complete integration examples.
+
+## License
+
+MIT License © [VoidZero Inc.](https://github.com/vitejs)

package/dist/client.d.mts

@@ -0,0 +1,9 @@
+import { BirpcOptions, BirpcReturn } from "birpc";
+
+//#region src/client.d.ts
+declare function createRpcClient<ServerFunctions extends object = Record<string, never>, ClientFunctions extends object = Record<string, never>>(functions: ClientFunctions, options: {
+  preset: BirpcOptions<ServerFunctions, ClientFunctions, false>;
+  rpcOptions?: Partial<BirpcOptions<ServerFunctions, ClientFunctions, boolean>>;
+}): BirpcReturn<ServerFunctions, ClientFunctions, false>;
+//#endregion
+export { createRpcClient };

package/dist/client.mjs

@@ -0,0 +1,15 @@
+import { createBirpc } from "birpc";
+
+//#region src/client.ts
+function createRpcClient(functions, options) {
+	const { preset, rpcOptions = {} } = options;
+	return createBirpc(functions, {
+		...preset,
+		timeout: -1,
+		...rpcOptions,
+		proxify: false
+	});
+}
+
+//#endregion
+export { createRpcClient };

package/dist/index.d.mts

@@ -0,0 +1,257 @@
+import { BirpcFn, BirpcReturn } from "birpc";
+import { GenericSchema, InferInput } from "valibot";
+
+//#region src/cache.d.ts
+interface RpcCacheOptions {
+  functions: string[];
+  keySerializer?: (args: unknown[]) => string;
+}
+/**
+ * @experimental API is expected to change.
+ */
+declare class RpcCacheManager {
+  private cacheMap;
+  private options;
+  private keySerializer;
+  constructor(options: RpcCacheOptions);
+  updateOptions(options: Partial<RpcCacheOptions>): void;
+  cached<T>(m: string, a: unknown[]): T | undefined;
+  apply(req: {
+    m: string;
+    a: unknown[];
+  }, res: unknown): void;
+  validate(m: string): boolean;
+  clear(fn?: string): void;
+}
+//#endregion
+//#region src/utils.d.ts
+/** Infers TypeScript tuple type from Valibot schema array */
+type InferArgsType<S extends RpcArgsSchema | undefined> = S extends readonly [] ? [] : S extends readonly [infer H, ...infer T] ? H extends GenericSchema ? T extends readonly GenericSchema[] ? [InferInput<H>, ...InferArgsType<T>] : never : never : never;
+/** Infers TypeScript return type from Valibot return schema */
+type InferReturnType<S extends RpcReturnSchema | undefined> = S extends RpcReturnSchema ? InferInput<S> : void;
+//#endregion
+//#region src/types.d.ts
+type Thenable<T> = T | Promise<T>;
+type EntriesToObject<T extends readonly [string, any][]> = { [K in T[number] as K[0]]: K[1] };
+/**
+ * Type of the RPC function,
+ * - static: A function that returns a static data, no arguments (can be cached and dumped)
+ * - action: A function that performs an action (no data returned)
+ * - event: A function that emits an event (no data returned), and does not wait for a response
+ * - query: A function that queries a resource
+ *
+ * By default, the function is a query function.
+ */
+type RpcFunctionType = 'static' | 'action' | 'event' | 'query';
+/**
+ * Manages dynamic function registration and provides a type-safe proxy for accessing functions.
+ */
+interface RpcFunctionsCollector<LocalFunctions, SetupContext = undefined> {
+  /** User-provided context passed to setup functions */
+  context: SetupContext;
+  /** Type-safe proxy for calling registered functions */
+  readonly functions: LocalFunctions;
+  /** Map of registered function definitions keyed by function name */
+  readonly definitions: Map<string, RpcFunctionDefinitionAnyWithContext<SetupContext>>;
+  /** Register a new function definition */
+  register: (fn: RpcFunctionDefinitionAnyWithContext<SetupContext>) => void;
+  /** Update an existing function definition */
+  update: (fn: RpcFunctionDefinitionAnyWithContext<SetupContext>) => void;
+  /** Subscribe to function changes, returns unsubscribe function */
+  onChanged: (fn: (id?: string) => void) => (() => void);
+}
+/**
+ * Result returned by a function's setup method.
+ */
+interface RpcFunctionSetupResult<ARGS extends any[], RETURN = void> {
+  /** Function handler */
+  handler?: (...args: ARGS) => RETURN;
+  /** Optional dump definition (overrides definition-level dump) */
+  dump?: RpcDumpDefinition<ARGS, RETURN>;
+}
+/** Valibot schema array for validating function arguments */
+type RpcArgsSchema = readonly GenericSchema[];
+/** Valibot schema for validating function return value */
+type RpcReturnSchema = GenericSchema;
+/**
+ * Single record in a dump store with pre-computed results.
+ */
+interface RpcDumpRecord<ARGS extends any[] = any[], RETURN = any> {
+  /** Function arguments */
+  inputs: ARGS;
+  /** Result (value or lazy function) */
+  output?: RETURN;
+  /** Error if execution failed */
+  error?: {
+    /** Error message */message: string; /** Error type name (e.g., "Error", "TypeError") */
+    name: string;
+  };
+}
+/**
+ * Defines argument combinations to pre-compute for a function.
+ */
+interface RpcDumpDefinition<ARGS extends any[] = any[], RETURN = any> {
+  /** Argument combinations to pre-compute by executing handler */
+  inputs?: ARGS[];
+  /** Pre-computed records to use directly (bypasses handler execution) */
+  records?: RpcDumpRecord<ARGS, RETURN>[];
+  /** Fallback value when no match found */
+  fallback?: RETURN;
+}
+/**
+ * Dynamically generates dump definitions based on context.
+ */
+type RpcDumpGetter<ARGS extends any[] = any[], RETURN = any, CONTEXT = any> = (context: CONTEXT, handler: (...args: ARGS) => RETURN) => Thenable<RpcDumpDefinition<ARGS, RETURN>>;
+/**
+ * Dump configuration (static object or dynamic function).
+ */
+type RpcDump<ARGS extends any[] = any[], RETURN = any, CONTEXT = any> = RpcDumpDefinition<ARGS, RETURN> | RpcDumpGetter<ARGS, RETURN, CONTEXT>;
+/**
+ * Base function definition metadata.
+ */
+interface RpcFunctionDefinitionBase {
+  /** Function name (unique identifier) */
+  name: string;
+  /** Function type (static, action, event, or query) */
+  type?: RpcFunctionType;
+}
+/**
+ * Dump store containing pre-computed results.
+ * Flat structure for serialization and efficient lookups.
+ */
+interface RpcDumpStore<T = any> {
+  /** Function definitions keyed by name */
+  definitions: Record<string, RpcFunctionDefinitionBase>;
+  /** Records keyed by '<function-name>---<hash>' or '<function-name>---fallback' */
+  records: Record<string, RpcDumpRecord | (() => Promise<RpcDumpRecord>)>;
+  /** @internal */
+  _functions?: T;
+}
+/**
+ * Dump client options.
+ */
+interface RpcDumpClientOptions {
+  /** Called when arguments don't match any pre-computed entry */
+  onMiss?: (functionName: string, args: any[]) => void;
+}
+/**
+ * Options for collecting dumps.
+ */
+interface RpcDumpCollectionOptions {
+  /**
+   * Concurrency control for parallel execution.
+   * - `false` or `undefined`: sequential execution (default)
+   * - `true`: parallel execution with concurrency limit of 5
+   * - `number`: parallel execution with specified concurrency limit
+   */
+  concurrency?: boolean | number | null;
+}
+/**
+ * RPC function definition with optional dump support.
+ */
+type RpcFunctionDefinition<NAME extends string, TYPE extends RpcFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined, CONTEXT = undefined> = [AS, RS] extends [undefined, undefined] ? {
+  /** Function name (unique identifier) */name: NAME; /** Function type (static, action, event, or query) */
+  type?: TYPE; /** Whether the function results should be cached */
+  cacheable?: boolean; /** Valibot schema array for validating function arguments */
+  args?: AS; /** Valibot schema for validating function return value */
+  returns?: RS; /** Setup function called with context to initialize handler and dump */
+  setup?: (context: CONTEXT) => Thenable<RpcFunctionSetupResult<ARGS, RETURN>>; /** Function implementation (required if setup doesn't provide one) */
+  handler?: (...args: ARGS) => RETURN; /** Dump definition (setup dump takes priority) */
+  dump?: RpcDump<ARGS, RETURN, CONTEXT>;
+  __resolved?: RpcFunctionSetupResult<ARGS, RETURN>;
+  __promise?: Thenable<RpcFunctionSetupResult<ARGS, RETURN>>;
+} : {
+  /** Function name (unique identifier) */name: NAME; /** Function type (static, action, event, or query) */
+  type?: TYPE; /** Whether the function results should be cached */
+  cacheable?: boolean; /** Valibot schema array for validating function arguments */
+  args: AS; /** Valibot schema for validating function return value */
+  returns: RS; /** Setup function called with context to initialize handler and dump */
+  setup?: (context: CONTEXT) => Thenable<RpcFunctionSetupResult<InferArgsType<AS>, InferReturnType<RS>>>; /** Function implementation (required if setup doesn't provide one) */
+  handler?: (...args: InferArgsType<AS>) => InferReturnType<RS>; /** Dump definition (setup dump takes priority) */
+  dump?: RpcDump<InferArgsType<AS>, InferReturnType<RS>, CONTEXT>;
+  __resolved?: RpcFunctionSetupResult<InferArgsType<AS>, InferReturnType<RS>>;
+  __promise?: Thenable<RpcFunctionSetupResult<InferArgsType<AS>, InferReturnType<RS>>>;
+};
+type RpcFunctionDefinitionToFunction<T extends RpcFunctionDefinitionAny> = T extends {
+  args: infer AS;
+  returns: infer RS;
+} ? AS extends RpcArgsSchema ? RS extends RpcReturnSchema ? (...args: InferArgsType<AS>) => InferReturnType<RS> : never : never : T extends RpcFunctionDefinition<string, any, infer ARGS, infer RETURN, any, any, any> ? (...args: ARGS) => RETURN : never;
+type RpcFunctionDefinitionAny = RpcFunctionDefinition<string, any, any, any, any, any, any>;
+type RpcFunctionDefinitionAnyWithContext<CONTEXT = undefined> = RpcFunctionDefinition<string, any, any, any, any, any, CONTEXT>;
+type RpcDefinitionsToFunctions<T extends readonly RpcFunctionDefinitionAny[]> = EntriesToObject<{ [K in keyof T]: [T[K]['name'], RpcFunctionDefinitionToFunction<T[K]>] }>;
+type RpcDefinitionsFilter<T extends readonly RpcFunctionDefinitionAny[], Type extends RpcFunctionType> = { [K in keyof T]: T[K] extends {
+  type: Type;
+} ? T[K] : never };
+//#endregion
+//#region src/collector.d.ts
+declare class RpcFunctionsCollectorBase<LocalFunctions extends Record<string, any>, SetupContext> implements RpcFunctionsCollector<LocalFunctions, SetupContext> {
+  readonly context: SetupContext;
+  readonly definitions: Map<string, RpcFunctionDefinition<string, any, any, any, any, any, SetupContext>>;
+  readonly functions: LocalFunctions;
+  private readonly _onChanged;
+  constructor(context: SetupContext);
+  register(fn: RpcFunctionDefinition<string, any, any, any, any, any, SetupContext>, force?: boolean): void;
+  update(fn: RpcFunctionDefinition<string, any, any, any, any, any, SetupContext>, force?: boolean): void;
+  onChanged(fn: (id?: string) => void): () => void;
+  getHandler<T extends keyof LocalFunctions>(name: T): Promise<LocalFunctions[T]>;
+  getSchema<T extends keyof LocalFunctions>(name: T): {
+    args: RpcArgsSchema | undefined;
+    returns: RpcReturnSchema | undefined;
+  };
+  has(name: string): boolean;
+  get(name: string): RpcFunctionDefinition<string, any, any, any, any, any, SetupContext> | undefined;
+  list(): string[];
+}
+//#endregion
+//#region src/define.d.ts
+declare function defineRpcFunction<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
+declare function createDefineWrapperWithContext<CONTEXT>(): <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, CONTEXT>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, CONTEXT>;
+//#endregion
+//#region src/dumps.d.ts
+/**
+ * Collects pre-computed dumps by executing functions with their defined input combinations.
+ * Static functions without dump config automatically get `{ inputs: [[]] }`.
+ *
+ * @example
+ * ```ts
+ * const store = await dumpFunctions([greet], context, { concurrency: 10 })
+ * ```
+ */
+declare function dumpFunctions<T extends readonly RpcFunctionDefinitionAny[]>(definitions: T, context?: any, options?: RpcDumpCollectionOptions): Promise<RpcDumpStore<RpcDefinitionsToFunctions<T>>>;
+/**
+ * Creates a client that serves pre-computed results from a dump store.
+ * Uses argument hashing to match calls to stored records.
+ *
+ * @example
+ * ```ts
+ * const client = createClientFromDump(store)
+ * await client.greet('Alice')
+ * ```
+ */
+declare function createClientFromDump<T extends Record<string, any>>(store: RpcDumpStore<T>, options?: RpcDumpClientOptions): BirpcReturn<T>;
+/**
+ * Filters function definitions to only those with dump definitions.
+ * Note: Only checks the definition itself, not setup results.
+ */
+declare function getDefinitionsWithDumps<T extends readonly RpcFunctionDefinitionAny[]>(definitions: T): RpcFunctionDefinitionAny[];
+//#endregion
+//#region src/handler.d.ts
+declare function getRpcResolvedSetupResult<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, CONTEXT = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, any, any, CONTEXT>, context: CONTEXT): Promise<RpcFunctionSetupResult<ARGS, RETURN>>;
+declare function getRpcHandler<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, CONTEXT = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, any, any, CONTEXT>, context: CONTEXT): Promise<(...args: ARGS) => RETURN>;
+//#endregion
+//#region src/validation.d.ts
+/**
+ * Validates RPC function definitions.
+ * Action and event functions cannot have dumps (side effects should not be cached).
+ *
+ * @throws {Error} If an action or event function has a dump configuration
+ */
+declare function validateDefinitions(definitions: readonly RpcFunctionDefinitionAny[]): void;
+/**
+ * Validates a single RPC function definition.
+ *
+ * @throws {Error} If an action or event function has a dump configuration
+ */
+declare function validateDefinition(definition: RpcFunctionDefinitionAny): void;
+//#endregion
+export { type BirpcFn, type BirpcReturn, EntriesToObject, RpcArgsSchema, RpcCacheManager, RpcCacheOptions, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcDump, RpcDumpClientOptions, RpcDumpCollectionOptions, RpcDumpDefinition, RpcDumpGetter, RpcDumpRecord, RpcDumpStore, RpcFunctionDefinition, RpcFunctionDefinitionAny, RpcFunctionDefinitionAnyWithContext, RpcFunctionDefinitionBase, RpcFunctionDefinitionToFunction, RpcFunctionSetupResult, RpcFunctionType, RpcFunctionsCollector, RpcFunctionsCollectorBase, RpcReturnSchema, Thenable, createClientFromDump, createDefineWrapperWithContext, defineRpcFunction, dumpFunctions, getDefinitionsWithDumps, getRpcHandler, getRpcResolvedSetupResult, validateDefinition, validateDefinitions };