mirinjs 0.1.0-alpha.26 → 0.1.0-alpha.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.27",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",

package/src/app/facade.ts

@@ -12,6 +12,7 @@ import type { Updater } from "../updater/index.ts";
 import { updater } from "../updater/index.ts";
 import { Emitter } from "./lib/emitter.ts";
 import { normalizeMaterial } from "./lib/material.ts";
+import { type RpcEmitters, rpcEmitters } from "./lib/rpc-emitters.ts";
 import type {
   AppEvents,
   BroadcastEmitters,
@@ -139,22 +140,6 @@ export class WindowHandle extends Emitter<WindowEvents> {
   }
 }
 
-type RpcEmitters = Record<
-  string,
-  { emit(payload: unknown): void; broadcast(payload: unknown): void }
->;
-
-function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitters {
-  return new Proxy({} as RpcEmitters, {
-    get(_t, method: string) {
-      return {
-        emit: (payload: unknown) => send(method, payload),
-        broadcast: (payload: unknown) => send(method, payload),
-      };
-    },
-  });
-}
-
 class Windows {
   #byName = new Map<string, WindowHandle>();
   #byId = new Map<number, WindowHandle>();

package/src/app/lib/rpc-emitters.ts

@@ -0,0 +1,37 @@
+/**
+ * The untyped emitters behind `app.rpc` and a window's `rpc`: `rpc.progress`
+ * sends the event `progress`, and `rpc.window.focused` the nested router's
+ * `window.focused` (docs/api-design.md §3). `app.serve` hands out the same
+ * object typed by the router (BroadcastEmitters).
+ */
+
+import { SEPARATOR } from "../../shared/rpc-paths.ts";
+
+/** An event by name, and the events of a nested router under it (`rpc.window.focused`). */
+export type RpcEmitter = {
+  emit(payload: unknown): void;
+  broadcast(payload: unknown): void;
+} & RpcEmitters;
+
+export interface RpcEmitters {
+  readonly [name: string]: RpcEmitter;
+}
+
+export function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitters {
+  const node = (method: string): RpcEmitter =>
+    new Proxy({} as RpcEmitter, {
+      get(_t, prop) {
+        if (prop === "emit" || prop === "broadcast") {
+          return (payload: unknown) => send(method, payload);
+        }
+        // Not a promise, and nothing behind symbols.
+        if (typeof prop !== "string" || prop === "then") return undefined;
+        return node(`${method}${SEPARATOR}${prop}`);
+      },
+    });
+  return new Proxy({} as RpcEmitters, {
+    get(_t, method) {
+      return typeof method === "string" ? node(method) : undefined;
+    },
+  });
+}

package/src/app/types.ts

@@ -41,13 +41,18 @@ export interface WindowOpenOptions extends WindowConfig {
   name?: string;
 }
 
-/** Typed push emitters derived from a router's `event` procedures.
+/** Typed push emitters derived from a router's `event` procedures, nested
+ * routers under their names (`rpc.window.focused.broadcast(...)`).
  * Type-level `any` keeps the caller's router payload inference intact. */
 export type BroadcastEmitters<R extends Router<any>> = R extends Router<infer T>
   ? {
-      [K in keyof T as T[K] extends EventProc<any> ? K : never]: T[K] extends EventProc<infer P>
+      [K in keyof T as T[K] extends EventProc<any> | Router<any>
+        ? K
+        : never]: T[K] extends EventProc<infer P>
         ? { broadcast(payload: P): void }
-        : never;
+        : T[K] extends Router<any>
+          ? BroadcastEmitters<T[K]>
+          : never;
     }
   : never;
 

package/src/client.ts

@@ -6,6 +6,7 @@
  */
 
 import type { EventProc, MutationProc, QueryProc, Router } from "./rpc.ts";
+import { SEPARATOR } from "./shared/rpc-paths.ts";
 
 // Type-level `any` preserves the app router's concrete procedure inference for UI callers.
 export type ClientFor<R extends Router<any>> = R extends Router<infer T>
@@ -16,7 +17,9 @@ export type ClientFor<R extends Router<any>> = R extends Router<infer T>
           ? (input: I) => Promise<Awaited<O>>
           : T[K] extends EventProc<infer P>
             ? { on(listener: (payload: P) => void): () => void }
-            : never;
+            : T[K] extends Router<any>
+              ? ClientFor<T[K]>
+              : never;
     }
   : never;
 
@@ -51,20 +54,44 @@ function transport(): MirinTransport {
  */
 // Type-level `any` keeps `client<AppRouter>()` inference intact.
 export function client<R extends Router<any>>(): ClientFor<R> {
-  const eventCache = new Map<string, { on(l: (p: unknown) => void): () => void }>();
-
+  const nodes = new Map<string, unknown>();
+  const node = (path: string): unknown => {
+    let found = nodes.get(path);
+    if (found === undefined) {
+      found = clientNode(path, node);
+      nodes.set(path, found);
+    }
+    return found;
+  };
   return new Proxy({} as ClientFor<R>, {
     get(_target, prop) {
-      if (typeof prop !== "string") return undefined;
-      // Procedure kind is unknowable from the type-erased proxy; expose a callable
-      // that is *also* event-shaped. The router type makes misuse a compile error.
-      const callable = (input: unknown) => transport().call(prop, input);
-      let ev = eventCache.get(prop);
-      if (!ev) {
-        ev = { on: (listener) => transport().onEvent(prop, listener) };
-        eventCache.set(prop, ev);
+      return typeof prop === "string" ? node(prop) : undefined;
+    },
+  });
+}
+
+/** What a function's caller expects to find on it; anything else is a nested name. */
+const FUNCTION_MEMBERS = new Set(["apply", "bind", "call", "toString"]);
+
+/**
+ * One name in the client, `path` from the root. Procedure kind is unknowable
+ * from the type-erased proxy, so it is all of them at once: callable (a query
+ * or mutation), event-shaped (`.on`), and a router (any other name is a child
+ * at `path.name`). The router type makes misuse a compile error, and
+ * rpc.router keeps nested routers off the names used here.
+ */
+function clientNode(path: string, node: (path: string) => unknown): unknown {
+  const call = (input: unknown) => transport().call(path, input);
+  const on = (listener: (payload: unknown) => void) => transport().onEvent(path, listener);
+  return new Proxy(call, {
+    get(target, prop, receiver) {
+      if (prop === "on") return on;
+      // Not a promise: `await` and promise helpers must not take a node for one.
+      if (prop === "then") return undefined;
+      if (typeof prop !== "string" || FUNCTION_MEMBERS.has(prop)) {
+        return Reflect.get(target, prop, receiver);
       }
-      return Object.assign(callable, ev);
+      return node(`${path}${SEPARATOR}${prop}`);
     },
   });
 }

package/src/rpc-server.ts

@@ -9,6 +9,7 @@ import { devtoolsOptions } from "./devtools/options.ts";
 import { record } from "./devtools/sink.ts";
 import type { Procedure, Router, RpcContext } from "./rpc.ts";
 import { formatArg } from "./shared/format.ts";
+import { procedures, SEPARATOR } from "./shared/rpc-paths.ts";
 
 interface SocketData {
   webview: number;
@@ -44,8 +45,8 @@ export type ControlHandler = (frame: ControlFrame, webview: number) => void;
 export class RpcServer {
   readonly token = crypto.randomUUID();
   #server?: ReturnType<typeof Bun.serve>;
-  // Type-level `any` keeps the server able to store any concrete app router.
-  #router?: Router<any>;
+  /** The served router's procedures by path (`greet`, `window.min`). */
+  #procedures = new Map<string, Procedure>();
   #control?: ControlHandler;
   #sockets = new Set<ServerWebSocket<SocketData>>();
 
@@ -96,16 +97,16 @@ export class RpcServer {
     await server.stop(true);
   }
 
-  /** Type-level `any` keeps the caller's concrete router shape. */
+  /** Serve `router`, replacing the one served before (compose routers to serve
+   *  several). Type-level `any` keeps the caller's concrete router shape. */
   setRouter(router: Router<any>): void {
-    this.#router = router;
+    this.#procedures = procedures(router);
   }
 
-  /** The registered procedures, for the inspector's `/state`: a tool can discover
-   *  the RPC surface without reading source. */
+  /** The registered procedures by path, for the inspector's `/state`: a tool can
+   *  discover the RPC surface without reading source. */
   routes(): { name: string; type: string }[] {
-    const routes: Record<string, Procedure> = this.#router?.routes ?? {};
-    return Object.entries(routes).map(([name, proc]) => ({ name, type: proc.type }));
+    return [...this.#procedures].map(([name, proc]) => ({ name, type: proc.type }));
   }
 
   /** Register the handler for internal `mirin:*` control actions (e.g. window drag). */
@@ -127,6 +128,19 @@ export class RpcServer {
     }
   }
 
+  /** Why `method` can't be called: unknown, an event, or a router rather than one of its procedures. */
+  #notCallable(method: string, proc: Procedure | undefined): string {
+    if (proc?.type === "event") {
+      return `${method} is an event: the main process emits it and the UI listens with .on()`;
+    }
+    const prefix = `${method}${SEPARATOR}`;
+    const inside = [...this.#procedures.keys()].filter((name) => name.startsWith(prefix));
+    if (inside.length > 0) {
+      return `no such procedure: ${method} is a router; call one of its procedures (${inside.slice(0, 5).join(", ")}${inside.length > 5 ? ", …" : ""})`;
+    }
+    return `no such procedure: ${method}`;
+  }
+
   async #onMessage(ws: ServerWebSocket<SocketData>, raw: string | Buffer): Promise<void> {
     let frame: IncomingFrame;
     try {
@@ -148,9 +162,9 @@ export class RpcServer {
     const webview = ws.data.webview;
     traceRequest(frame, webview);
 
-    const proc = this.#router?.routes[frame.method];
+    const proc = this.#procedures.get(frame.method);
     if (!proc || (proc.type !== "query" && proc.type !== "mutation")) {
-      const error = `no such procedure: ${frame.method}`;
+      const error = this.#notCallable(frame.method, proc);
       traceFailure(frame, webview, 0, error, "unknown-procedure");
       reply(false, { error });
       return;

package/src/rpc.ts

@@ -3,9 +3,13 @@
  *
  * Imported by BOTH the main process (handlers run here, in the Bun Worker)
  * and UI code (type-only, via `client<Router>()` from mirin/client).
- * The router is global; handlers learn their caller from `ctx`.
+ * The router is global; handlers learn their caller from `ctx`. Routers nest:
+ * a router's routes can be other routers, and their procedures are called by
+ * path (`api.window.min()`, `window.min` on the wire).
  */
 
+import { procedures } from "./shared/rpc-paths.ts";
+
 export interface RpcContext {
   /** Name of the calling window, if it was opened with one. */
   window?: string;
@@ -35,14 +39,29 @@ export interface EventProc<P> {
 // no runtime value is widened through this union.
 export type Procedure = QueryProc<any, any> | MutationProc<any, any> | EventProc<any>;
 
-export interface Router<T extends Record<string, Procedure> = Record<string, Procedure>> {
+/** What a router holds: procedures, and other routers under their own names. */
+export interface Routes {
+  // Type-level `any` keeps each nested router's own procedure types.
+  readonly [name: string]: Procedure | Router<any>;
+}
+
+export interface Router<T extends Routes = Routes> {
   readonly type: "router";
   readonly routes: T;
 }
 
 export const rpc = {
-  router<T extends Record<string, Procedure>>(routes: T): Router<T> {
-    return { type: "router", routes };
+  /**
+   * Define a router. Nested routers keep their procedures apart
+   * (`window.close` and `install.close` are two procedures). Throws when two
+   * procedures end up with the same path, or when a nested router uses a name
+   * the client needs (`on`, `then`, `emit`, `broadcast`, `apply`, `bind`,
+   * `call`, `toString`).
+   */
+  router<T extends Routes>(routes: T): Router<T> {
+    const router: Router<T> = { type: "router", routes };
+    procedures(router);
+    return router;
   },
 
   /** Request/response, semantically a read. Runtime-identical to mutation in the MVP. */

package/src/shared/rpc-paths.ts

@@ -0,0 +1,83 @@
+/**
+ * Nested routers on the wire (docs/api-design.md §3). A router can hold other
+ * routers; each procedure is then named by its path, joined with dots
+ * (`window.min`), which is the method name a request frame carries. Flat
+ * routers keep their names as they were.
+ *
+ * The UI client and the main-process emitters are proxies that only know the
+ * router's type, so inside a nested router a few names belong to them: on a
+ * client node `on` subscribes, `then` would make it look like a promise, and
+ * `apply`, `bind`, `call`, `toString` keep it a normal function; on an emitter
+ * node `emit` and `broadcast` send. A nested router can't use those names.
+ * Top-level names are not restricted, as before.
+ */
+
+import type { Procedure, Router } from "../rpc.ts";
+
+export const SEPARATOR = ".";
+
+export const RESERVED_NESTED_NAMES: ReadonlySet<string> = new Set([
+  "on",
+  "then",
+  "emit",
+  "broadcast",
+  "apply",
+  "bind",
+  "call",
+  "toString",
+]);
+
+const KINDS = new Set(["query", "mutation", "event"]);
+
+export function isRouter(value: unknown): value is Router {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { type?: unknown; routes?: unknown };
+  return (
+    candidate.type === "router" && typeof candidate.routes === "object" && candidate.routes !== null
+  );
+}
+
+function isProcedure(value: unknown): value is Procedure {
+  if (typeof value !== "object" || value === null) return false;
+  return KINDS.has(String((value as { type?: unknown }).type));
+}
+
+/**
+ * Every procedure of `router` by its full path. Throws on a value that is not
+ * a procedure or a router, on two procedures with the same path (a flat
+ * `"window.min"` beside a nested `window: { min }`), on a router that contains
+ * itself, and on a reserved name inside a nested router.
+ */
+export function procedures(router: Router): Map<string, Procedure> {
+  const found = new Map<string, Procedure>();
+  const walk = (current: Router, prefix: string, open: Set<Router>): void => {
+    open.add(current);
+    for (const [name, value] of Object.entries(current.routes)) {
+      const path = prefix === "" ? name : `${prefix}${SEPARATOR}${name}`;
+      if (prefix !== "" && RESERVED_NESTED_NAMES.has(name)) {
+        throw new Error(
+          `rpc.router: "${path}" can't be used inside a nested router: ${[...RESERVED_NESTED_NAMES].join(", ")} are taken by the client and the event emitters. Rename it.`,
+        );
+      }
+      if (isRouter(value)) {
+        if (open.has(value)) throw new Error(`rpc.router: "${path}" contains itself`);
+        walk(value, path, open);
+        continue;
+      }
+      if (!isProcedure(value)) {
+        throw new Error(
+          `rpc.router: "${path}" is not a procedure or a router (use rpc.query, rpc.mutation, rpc.event, or rpc.router)`,
+        );
+      }
+      if (found.has(path)) {
+        throw new Error(
+          `rpc.router: two procedures are named "${path}" (a nested router's procedures are named <router>${SEPARATOR}<procedure>). Rename one.`,
+        );
+      }
+      found.set(path, value);
+    }
+    open.delete(current);
+  };
+  walk(router, "", new Set());
+  return found;
+}