devframe 0.1.16 → 0.1.18

package/dist/{index-DvKDO5H8.d.mts → types-BkyzI9r4.d.mts}

@@ -1,29 +1,6 @@
 import { GenericSchema, InferInput } from "valibot";
 import { BirpcFn, BirpcReturn as BirpcReturn$1 } from "birpc";
 
-//#region src/rpc/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/rpc/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;
@@ -158,6 +135,20 @@ interface RpcFunctionDefinitionBase {
   name: string;
   /** Function type (static, action, event, or query) */
   type?: RpcFunctionType;
+  /**
+   * Declares whether this function's args/return are JSON-serializable
+   * — i.e. no `Map`, `Set`, `Date`, `BigInt`, class instances, circular
+   * references, `undefined` leaves, `Symbol`, or `Function` values.
+   *
+   * - `true` — args and return are encoded with strict `JSON.stringify`
+   *   on the wire and on disk. Misshapen values throw `DF0019` at the
+   *   sender, surfacing the bug *during the offending call* rather than
+   *   silently coercing to `{}` later. Required for `agent` exposure.
+   * - `false` (default) — payloads use `structured-clone-es`, which
+   *   round-trips Maps/Sets/cycles. Functions in this mode cannot be
+   *   exposed via the `agent` field — registration throws `DF0018`.
+   */
+  jsonSerializable?: boolean;
 }
 /**
  * Dump store containing pre-computed results.
@@ -199,6 +190,16 @@ type RpcFunctionDefinition<NAME extends string, TYPE extends RpcFunctionType = '
   cacheable?: boolean; /** Valibot schema array for validating function arguments */
   args?: AS; /** Valibot schema for validating function return value */
   returns?: RS;
+  /**
+   * Declares whether this function's args/return are JSON-serializable
+   * (no Map/Set/Date/BigInt/cycles/class instances/undefined/Symbol/Function).
+   *
+   * - `true` — wire and dump use strict `JSON.stringify`; misshapen
+   *   values throw `DF0019` at the call site. Required for `agent`.
+   * - `false` (default) — `structured-clone-es` round-trips fancy
+   *   types. Cannot be `agent`-exposed (registration throws `DF0018`).
+   */
+  jsonSerializable?: boolean;
   /**
    * Expose this function to agents (e.g. via the MCP adapter).
    * When omitted, the function is not agent-exposed (default-deny).
@@ -226,6 +227,16 @@ type RpcFunctionDefinition<NAME extends string, TYPE extends RpcFunctionType = '
   cacheable?: boolean; /** Valibot schema array for validating function arguments */
   args: AS; /** Valibot schema for validating function return value */
   returns: RS;
+  /**
+   * Declares whether this function's args/return are JSON-serializable
+   * (no Map/Set/Date/BigInt/cycles/class instances/undefined/Symbol/Function).
+   *
+   * - `true` — wire and dump use strict `JSON.stringify`; misshapen
+   *   values throw `DF0019` at the call site. Required for `agent`.
+   * - `false` (default) — `structured-clone-es` round-trips fancy
+   *   types. Cannot be `agent`-exposed (registration throws `DF0018`).
+   */
+  jsonSerializable?: boolean;
   /**
    * Expose this function to agents (e.g. via the MCP adapter).
    * When omitted, the function is not agent-exposed (default-deny).
@@ -259,75 +270,4 @@ type RpcDefinitionsFilter<T extends readonly RpcFunctionDefinitionAny[], Type ex
   type: Type;
 } ? T[K] : never };
 //#endregion
-//#region src/rpc/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/rpc/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/rpc/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$1<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/rpc/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/rpc/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 { RpcFunctionSetupResult as A, RpcDumpStore as C, RpcFunctionDefinitionAnyWithContext as D, RpcFunctionDefinitionAny as E, RpcCacheManager as F, RpcCacheOptions as I, RpcFunctionsCollector as M, RpcReturnSchema as N, RpcFunctionDefinitionBase as O, Thenable as P, RpcDumpRecord as S, RpcFunctionDefinition as T, RpcDump as _, createClientFromDump as a, RpcDumpDefinition as b, createDefineWrapperWithContext as c, BirpcFn as d, BirpcReturn$1 as f, RpcDefinitionsToFunctions as g, RpcDefinitionsFilter as h, getRpcResolvedSetupResult as i, RpcFunctionType as j, RpcFunctionDefinitionToFunction as k, defineRpcFunction as l, RpcArgsSchema as m, validateDefinitions as n, dumpFunctions as o, EntriesToObject as p, getRpcHandler as r, getDefinitionsWithDumps as s, validateDefinition as t, RpcFunctionsCollectorBase as u, RpcDumpClientOptions as v, RpcFunctionAgentOptions as w, RpcDumpGetter as x, RpcDumpCollectionOptions as y };
+export { RpcReturnSchema as C, RpcFunctionsCollector as S, RpcFunctionDefinitionAnyWithContext as _, RpcDefinitionsFilter as a, RpcFunctionSetupResult as b, RpcDumpClientOptions as c, RpcDumpGetter as d, RpcDumpRecord as f, RpcFunctionDefinitionAny as g, RpcFunctionDefinition as h, RpcArgsSchema as i, RpcDumpCollectionOptions as l, RpcFunctionAgentOptions as m, BirpcReturn$1 as n, RpcDefinitionsToFunctions as o, RpcDumpStore as p, EntriesToObject as r, RpcDump as s, BirpcFn as t, RpcDumpDefinition as u, RpcFunctionDefinitionBase as v, Thenable as w, RpcFunctionType as x, RpcFunctionDefinitionToFunction as y };

package/dist/utils/events.d.mts

@@ -1,4 +1,4 @@
-import { Vt as EventsMap, zt as EventEmitter } from "../devtool-OJ3QW0ns.mjs";
+import { $t as EventsMap, Zt as EventEmitter } from "../devtool-CHT-4_OU.mjs";
 
 //#region src/utils/events.d.ts
 /**

package/dist/utils/shared-state.d.mts

@@ -1,2 +1,2 @@
-import { C as ImmutableSet, D as createSharedState, E as SharedStateOptions, S as ImmutableObject, T as SharedStateEvents, b as ImmutableArray, k as Patch, w as SharedState, x as ImmutableMap, y as Immutable } from "../devtool-OJ3QW0ns.mjs";
+import { C as ImmutableSet, D as createSharedState, E as SharedStateOptions, S as ImmutableObject, T as SharedStateEvents, b as ImmutableArray, k as Patch, w as SharedState, x as ImmutableMap, y as Immutable } from "../devtool-CHT-4_OU.mjs";
 export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, Patch as SharedStatePatch, createSharedState };

package/dist/utils/shared-state.mjs

@@ -1,5 +1,5 @@
 import { createEventEmitter } from "./events.mjs";
-import { i as produceWithPatches, n as enablePatches, r as produce, t as applyPatches } from "../immer-HjMAm3b6.mjs";
+import { i as produceWithPatches, n as enablePatches, r as produce, t as applyPatches } from "../immer-DEqg5kOd.mjs";
 import { nanoid } from "./nanoid.mjs";
 //#region src/utils/shared-state.ts
 function createSharedState(options) {

package/dist/utils/state.d.mts

@@ -1,4 +1,4 @@
-import { O as Objectish, k as Patch, zt as EventEmitter } from "../devtool-OJ3QW0ns.mjs";
+import { O as Objectish, Zt as EventEmitter, k as Patch } from "../devtool-CHT-4_OU.mjs";
 
 //#region src/utils/state.d.ts
 type ImmutablePrimitive = undefined | null | boolean | string | number | Function;

package/dist/utils/state.mjs

@@ -1,5 +1,5 @@
 import { createEventEmitter } from "./events.mjs";
-import { i as produceWithPatches, r as produce, t as applyPatches } from "../immer-HjMAm3b6.mjs";
+import { i as produceWithPatches, r as produce, t as applyPatches } from "../immer-DEqg5kOd.mjs";
 //#region src/utils/state.ts
 function createSharedState(options) {
 	const { enablePatches = false } = options;

package/dist/utils/when.d.mts

@@ -1,2 +1,2 @@
-import { i as resolveContextValue, n as WhenExpression, r as evaluateWhen, t as WhenContext } from "../when-CGLewRtm.mjs";
+import { i as resolveContextValue, n as WhenExpression, r as evaluateWhen, t as WhenContext } from "../when-aBBXAEh5.mjs";
 export { WhenContext, WhenExpression, evaluateWhen, resolveContextValue };

package/dist/ws-client-CDGmViwt.d.mts

@@ -0,0 +1,26 @@
+import { g as RpcFunctionDefinitionAny } from "./types-BkyzI9r4.mjs";
+import { ChannelOptions } from "birpc";
+
+//#region src/rpc/transports/ws-client.d.ts
+interface WsRpcChannelOptions {
+  url: string;
+  onConnected?: (e: Event) => void;
+  onError?: (e: Error) => void;
+  onDisconnected?: (e: CloseEvent) => void;
+  authToken?: string;
+  /**
+   * RPC function definitions (or just the `jsonSerializable` flag per
+   * method) used to dispatch the per-call wire serializer. Pass an
+   * empty / partial map on clients that don't have the full registry —
+   * encoding falls back to structured-clone (the safer superset) and
+   * decoding still routes correctly via the wire prefix.
+   */
+  definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>;
+}
+/**
+ * Build a birpc `ChannelOptions` object backed by a browser `WebSocket`.
+ * Pass the result straight to `createRpcClient`'s `channel` option.
+ */
+declare function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions;
+//#endregion
+export { createWsRpcChannel as n, WsRpcChannelOptions as t };

package/dist/{ws-server--IuUAaGi.d.mts → ws-server-Cu8tmZcF.d.mts}

@@ -1,3 +1,4 @@
+import { g as RpcFunctionDefinitionAny } from "./types-BkyzI9r4.mjs";
 import { BirpcGroup, ChannelOptions } from "birpc";
 import { ServerOptions } from "node:https";
 import { WebSocket, WebSocketServer } from "ws";
@@ -20,9 +21,20 @@ interface WsRpcTransportOptions {
   host?: string;
   /** When set, a new https.Server is created and the WebSocketServer is attached to it. */
   https?: ServerOptions;
+  /**
+   * RPC function definitions, used by the per-call wire serializer to
+   * dispatch between strict-JSON and structured-clone encoding based
+   * on each function's `jsonSerializable` flag.
+   *
+   * When omitted, all messages fall back to structured-clone — safe but
+   * loses dev-time validation for `jsonSerializable: true` declarations.
+   */
+  definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>;
   onConnected?: (ws: WebSocket, req: IncomingMessage, meta: DevToolsNodeRpcSessionMeta) => void;
   onDisconnected?: (ws: WebSocket, meta: DevToolsNodeRpcSessionMeta) => void;
+  /** Override the default per-call serializer. Most callers should leave this unset. */
   serialize?: ChannelOptions['serialize'];
+  /** Override the default per-call deserializer. Most callers should leave this unset. */
   deserialize?: ChannelOptions['deserialize'];
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Framework for building generic DevTools",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",

package/dist/ws-client-CklfxUHE.d.mts

@@ -1,17 +0,0 @@
-import { ChannelOptions } from "birpc";
-
-//#region src/rpc/transports/ws-client.d.ts
-interface WsRpcChannelOptions {
-  url: string;
-  onConnected?: (e: Event) => void;
-  onError?: (e: Error) => void;
-  onDisconnected?: (e: CloseEvent) => void;
-  authToken?: string;
-}
-/**
- * Build a birpc `ChannelOptions` object backed by a browser `WebSocket`.
- * Pass the result straight to `createRpcClient`'s `channel` option.
- */
-declare function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions;
-//#endregion
-export { createWsRpcChannel as n, WsRpcChannelOptions as t };