@rxferrix/client 0.0.0-stage → 0.2.0

package/dist/testing.js

@@ -0,0 +1,97 @@
+export class FakeSocket {
+    url;
+    static CONNECTING = 0;
+    static OPEN = 1;
+    static CLOSING = 2;
+    static CLOSED = 3;
+    readyState = FakeSocket.CONNECTING;
+    sent = [];
+    closedByClient = false;
+    /** The server-side StateVersion of this socket, advanced by `transition`. */
+    version = { querySet: 0, identity: 0, ts: 0 };
+    onopen = null;
+    onmessage = null;
+    onclose = null;
+    onerror = null;
+    constructor(url) {
+        this.url = url;
+    }
+    send(data) {
+        if (this.readyState !== FakeSocket.OPEN)
+            throw new Error("send on a socket that is not open");
+        this.sent.push(JSON.parse(data));
+    }
+    close() {
+        if (this.readyState === FakeSocket.CLOSED)
+            return;
+        this.closedByClient = true;
+        this.readyState = FakeSocket.CLOSED;
+    }
+}
+export class FakeServer {
+    sockets = [];
+    WebSocket;
+    constructor() {
+        const sockets = this.sockets;
+        class BoundFakeSocket extends FakeSocket {
+            constructor(url) {
+                super(url);
+                sockets.push(this);
+            }
+        }
+        this.WebSocket = BoundFakeSocket;
+    }
+    /** The most recently created socket. */
+    get socket() {
+        const s = this.sockets[this.sockets.length - 1];
+        if (!s)
+            throw new Error("no socket created yet");
+        return s;
+    }
+    /** Everything the client sent on the current socket. */
+    get sent() {
+        return this.socket.sent;
+    }
+    /** Messages of one type sent on the current socket. */
+    sentOfType(type) {
+        return this.sent.filter((m) => m.type === type);
+    }
+    /** Returns and forgets what the client sent on the current socket so far. */
+    drain() {
+        return this.socket.sent.splice(0);
+    }
+    open() {
+        const s = this.socket;
+        s.readyState = FakeSocket.OPEN;
+        s.onopen?.({});
+    }
+    push(message) {
+        const s = this.socket;
+        if (s.readyState !== FakeSocket.OPEN)
+            throw new Error("push on a socket that is not open");
+        s.onmessage?.({ data: JSON.stringify(message) });
+    }
+    /**
+     * Pushes a Transition from the socket's current version. `end` overrides fields of the end version; unspecified
+     * fields keep their current value.
+     */
+    transition(end, modifications = []) {
+        const s = this.socket;
+        const startVersion = { ...s.version };
+        const endVersion = { ...s.version, ...end };
+        s.version = endVersion;
+        this.push({ type: "Transition", startVersion, endVersion, modifications });
+    }
+    /** The server closes the current socket. */
+    close(code = 1011, reason = "server closed") {
+        const s = this.socket;
+        s.readyState = FakeSocket.CLOSED;
+        s.onclose?.({ code, reason });
+    }
+}
+/** Lets queued microtasks (query-set flush, promise continuations) run. */
+export async function flushMicrotasks() {
+    for (let i = 0; i < 5; i++)
+        await Promise.resolve();
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/web_socket_manager.d.ts

@@ -0,0 +1,88 @@
+import { type ClientMessage, type ServerMessage } from "./protocol.js";
+import type { Logger } from "./logging.js";
+/** Silence threshold: the server pings every 15s, so 30s without any frame means the socket is dead. */
+export declare const SERVER_INACTIVITY_TIMEOUT_MS = 30000;
+export type SocketState = "disconnected" | "connecting" | "ready" | "stopped";
+export interface WebSocketManagerCallbacks {
+    /**
+     * The socket is open, `Connect` has been sent, and the manager is not paused. The client must now (re)build the
+     * server state for this socket: Authenticate, ModifyQuerySet, pending mutations.
+     */
+    onOpen(): void;
+    /** `resume()` was called while the socket was already initialized: the client may flush anything it held back. */
+    onResume(): void;
+    /** A parsed server message (Ping is answered internally and also forwarded). */
+    onMessage(message: ServerMessage): void;
+    /** The current socket is gone (closed by either side). Called once per socket that reached `connecting`. */
+    onClose(reason: string, wasOpen: boolean): void;
+    /** Any observable state change (for connection-state subscribers). */
+    onStateChange(): void;
+}
+export interface WebSocketManagerOptions {
+    url: string;
+    sessionId: string;
+    webSocketConstructor: typeof WebSocket;
+    logger: Logger;
+}
+/**
+ * Owns the WebSocket: connecting, the `Connect` handshake, the server-silence watchdog, Pong replies, and
+ * reconnecting with exponential backoff and jitter.
+ *
+ * Outgoing traffic is only possible while the socket is `ready` and not paused. While a reconnect is underway (the
+ * socket is `connecting` or `disconnected`) nothing is sent: the client keeps its state locally and rebuilds the
+ * server's view of it in `onOpen` on the next socket. `pause()` additionally holds back `onOpen` (or lets the client
+ * hold back its own sends) while the client fetches an auth token, so that queries are not run with stale identity.
+ */
+export declare class WebSocketManager {
+    private readonly url;
+    private readonly sessionId;
+    private readonly WS;
+    private readonly logger;
+    private readonly callbacks;
+    private ws;
+    private _state;
+    /** True once `Connect` was sent and `onOpen` delivered for the current socket. */
+    private initialized;
+    private paused;
+    private _connectionCount;
+    private _hasEverConnected;
+    private lastCloseReason;
+    private retries;
+    private reconnectTimer;
+    private watchdogTimer;
+    private readonly removeEnvListeners;
+    constructor(options: WebSocketManagerOptions, callbacks: WebSocketManagerCallbacks);
+    /** Opens the first socket. */
+    start(): void;
+    get state(): SocketState;
+    get connectionCount(): number;
+    get hasEverConnected(): boolean;
+    get connectionRetries(): number;
+    get isPaused(): boolean;
+    /** True when a message handed to `send` would go out right now. */
+    canSend(): boolean;
+    /** Sends if possible; returns whether the message was sent. */
+    send(message: ClientMessage): boolean;
+    /** Called by the client once the server has proven healthy (a Transition was applied): resets the backoff. */
+    markHealthy(): void;
+    /** Holds back `onOpen` and client sends until `resume()`. Pings are still answered. */
+    pause(): void;
+    resume(): void;
+    /** Drops the current socket and reconnects after a backoff delay. */
+    reconnect(reason: string): void;
+    /** Permanently closes the socket. */
+    stop(): void;
+    private rawSend;
+    private connect;
+    /** Detaches and closes the current socket (if any), reporting `onClose` once. */
+    private closeCurrent;
+    private scheduleReconnect;
+    /** Exponential backoff with "equal jitter": half fixed, half random. */
+    private nextBackoff;
+    private clearReconnectTimer;
+    private resetWatchdog;
+    private clearWatchdog;
+    /** Skip the backoff wait when the browser comes back online or the tab becomes visible. */
+    private installEnvListeners;
+}
+//# sourceMappingURL=web_socket_manager.d.ts.map

package/dist/web_socket_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_socket_manager.d.ts","sourceRoot":"","sources":["../src/web_socket_manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,wGAAwG;AACxG,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAQnD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,kHAAkH;IAClH,QAAQ,IAAI,IAAI,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,4GAA4G;IAC5G,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChD,sEAAsE;IACtE,aAAa,IAAI,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,OAAO,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IAEtD,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAA+B;IAC7C,kFAAkF;IAClF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAa;gBAEpC,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,yBAAyB;IASlF,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAIb,IAAI,KAAK,IAAI,WAAW,CAEvB;IACD,IAAI,eAAe,IAAI,MAAM,CAE5B;IACD,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IACD,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IACD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,mEAAmE;IACnE,OAAO,IAAI,OAAO;IAIlB,+DAA+D;IAC/D,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO;IAQrC,8GAA8G;IAC9G,WAAW,IAAI,IAAI;IAInB,uFAAuF;IACvF,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IAcd,qEAAqE;IACrE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO/B,qCAAqC;IACrC,IAAI,IAAI,IAAI;IAWZ,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,OAAO;IAmEf,iFAAiF;IACjF,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,iBAAiB;IAYzB,wEAAwE;IACxE,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,aAAa;IAOrB,2FAA2F;IAC3F,OAAO,CAAC,mBAAmB;CAoB5B"}

package/dist/web_socket_manager.js

@@ -0,0 +1,291 @@
+import { CLIENT_VERSION } from "./protocol.js";
+/** Silence threshold: the server pings every 15s, so 30s without any frame means the socket is dead. */
+export const SERVER_INACTIVITY_TIMEOUT_MS = 30_000;
+const INITIAL_BACKOFF_MS = 250;
+const MAX_BACKOFF_MS = 16_000;
+/** The close code a server sends when it restarts or hands over to a new process (RFC 6455 "Service Restart"). */
+const SERVICE_RESTART = 1012;
+/** Spread of the immediate reconnects after a restart, so every client doesn't arrive in the same millisecond. */
+const RESTART_JITTER_MS = 250;
+/**
+ * Owns the WebSocket: connecting, the `Connect` handshake, the server-silence watchdog, Pong replies, and
+ * reconnecting with exponential backoff and jitter.
+ *
+ * Outgoing traffic is only possible while the socket is `ready` and not paused. While a reconnect is underway (the
+ * socket is `connecting` or `disconnected`) nothing is sent: the client keeps its state locally and rebuilds the
+ * server's view of it in `onOpen` on the next socket. `pause()` additionally holds back `onOpen` (or lets the client
+ * hold back its own sends) while the client fetches an auth token, so that queries are not run with stale identity.
+ */
+export class WebSocketManager {
+    url;
+    sessionId;
+    WS;
+    logger;
+    callbacks;
+    ws = null;
+    _state = "disconnected";
+    /** True once `Connect` was sent and `onOpen` delivered for the current socket. */
+    initialized = false;
+    paused = false;
+    _connectionCount = -1;
+    _hasEverConnected = false;
+    lastCloseReason = null;
+    retries = 0;
+    reconnectTimer = null;
+    watchdogTimer = null;
+    removeEnvListeners;
+    constructor(options, callbacks) {
+        this.url = options.url;
+        this.sessionId = options.sessionId;
+        this.WS = options.webSocketConstructor;
+        this.logger = options.logger;
+        this.callbacks = callbacks;
+        this.removeEnvListeners = this.installEnvListeners();
+    }
+    /** Opens the first socket. */
+    start() {
+        if (this.ws === null && this.reconnectTimer === null)
+            this.connect();
+    }
+    get state() {
+        return this._state;
+    }
+    get connectionCount() {
+        return Math.max(this._connectionCount, 0);
+    }
+    get hasEverConnected() {
+        return this._hasEverConnected;
+    }
+    get connectionRetries() {
+        return this.retries;
+    }
+    get isPaused() {
+        return this.paused;
+    }
+    /** True when a message handed to `send` would go out right now. */
+    canSend() {
+        return this._state === "ready" && this.initialized && !this.paused;
+    }
+    /** Sends if possible; returns whether the message was sent. */
+    send(message) {
+        if (!this.canSend()) {
+            this.logger.debug("not sent (socket not ready):", message.type);
+            return false;
+        }
+        return this.rawSend(message);
+    }
+    /** Called by the client once the server has proven healthy (a Transition was applied): resets the backoff. */
+    markHealthy() {
+        this.retries = 0;
+    }
+    /** Holds back `onOpen` and client sends until `resume()`. Pings are still answered. */
+    pause() {
+        if (this._state === "stopped")
+            return;
+        this.paused = true;
+        this.callbacks.onStateChange();
+    }
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        if (this._state === "ready") {
+            if (!this.initialized) {
+                this.initialized = true;
+                this.callbacks.onOpen();
+            }
+            else {
+                this.callbacks.onResume();
+            }
+        }
+        this.callbacks.onStateChange();
+    }
+    /** Drops the current socket and reconnects after a backoff delay. */
+    reconnect(reason) {
+        if (this._state === "stopped")
+            return;
+        this.logger.debug(`reconnecting: ${reason}`);
+        this.closeCurrent(reason);
+        this.scheduleReconnect(reason);
+    }
+    /** Permanently closes the socket. */
+    stop() {
+        if (this._state === "stopped")
+            return;
+        this.closeCurrent("ClientClosed");
+        this.clearReconnectTimer();
+        this._state = "stopped";
+        this.removeEnvListeners();
+        this.callbacks.onStateChange();
+    }
+    // -------------------------------------------------------------------------------------------------------------
+    rawSend(message) {
+        const ws = this.ws;
+        if (!ws)
+            return false;
+        try {
+            this.logger.debug("->", message);
+            ws.send(JSON.stringify(message));
+            return true;
+        }
+        catch (e) {
+            this.logger.warn("WebSocket send failed", e);
+            this.reconnect("SendFailed");
+            return false;
+        }
+    }
+    connect() {
+        if (this._state === "stopped")
+            return;
+        this.clearReconnectTimer();
+        let ws;
+        try {
+            ws = new this.WS(this.url);
+        }
+        catch (e) {
+            this.logger.warn("failed to construct WebSocket", e);
+            this._state = "disconnected";
+            this.scheduleReconnect("ConstructorFailed");
+            return;
+        }
+        this.ws = ws;
+        this._state = "connecting";
+        this.initialized = false;
+        this._connectionCount += 1;
+        this.callbacks.onStateChange();
+        ws.onopen = () => {
+            if (this.ws !== ws)
+                return;
+            this._state = "ready";
+            this._hasEverConnected = true;
+            this.resetWatchdog();
+            this.rawSend({
+                type: "Connect",
+                sessionId: this.sessionId,
+                connectionCount: this._connectionCount,
+                lastCloseReason: this.lastCloseReason,
+                clientVersion: CLIENT_VERSION,
+                features: ["diffs"],
+            });
+            if (!this.paused) {
+                this.initialized = true;
+                this.callbacks.onOpen();
+            }
+            this.callbacks.onStateChange();
+        };
+        ws.onmessage = (event) => {
+            if (this.ws !== ws)
+                return;
+            this.resetWatchdog();
+            let message;
+            try {
+                message = JSON.parse(typeof event.data === "string" ? event.data : String(event.data));
+            }
+            catch (e) {
+                this.logger.warn("received malformed frame", e);
+                this.reconnect("MalformedMessage");
+                return;
+            }
+            this.logger.debug("<-", message);
+            if (message.type === "Ping")
+                this.rawSend({ type: "Pong" });
+            this.callbacks.onMessage(message);
+        };
+        ws.onerror = () => {
+            // An error is always followed by a close event; reconnection is handled there.
+            if (this.ws === ws)
+                this.logger.debug("WebSocket error");
+        };
+        ws.onclose = (event) => {
+            if (this.ws !== ws)
+                return;
+            const reason = event?.reason ? `${event.code}: ${event.reason}` : `closed (${event?.code ?? "?"})`;
+            this.closeCurrent(reason);
+            // 1012 "service restart": the server is restarting or handing over to a new process, and the new one is
+            // already accepting (or about to): reconnect right away (with a little jitter) instead of backing off.
+            if (event?.code === SERVICE_RESTART)
+                this.retries = 0;
+            this.scheduleReconnect(reason, event?.code === SERVICE_RESTART ? Math.random() * RESTART_JITTER_MS : undefined);
+        };
+    }
+    /** Detaches and closes the current socket (if any), reporting `onClose` once. */
+    closeCurrent(reason) {
+        this.clearWatchdog();
+        const ws = this.ws;
+        if (!ws)
+            return;
+        const wasOpen = this._state === "ready";
+        this.ws = null;
+        this.initialized = false;
+        this._state = "disconnected";
+        this.lastCloseReason = reason;
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onerror = null;
+        ws.onclose = null;
+        try {
+            ws.close();
+        }
+        catch {
+            // ignore
+        }
+        this.callbacks.onClose(reason, wasOpen);
+        this.callbacks.onStateChange();
+    }
+    scheduleReconnect(reason, delayMs) {
+        if (this._state === "stopped" || this.reconnectTimer !== null)
+            return;
+        const delay = delayMs ?? this.nextBackoff();
+        this.retries += 1;
+        this.logger.info(`connection lost (${reason}); reconnecting in ${Math.round(delay)}ms`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+        this.callbacks.onStateChange();
+    }
+    /** Exponential backoff with "equal jitter": half fixed, half random. */
+    nextBackoff() {
+        const cap = Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** Math.min(this.retries, 16));
+        return cap / 2 + Math.random() * (cap / 2);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    resetWatchdog() {
+        this.clearWatchdog();
+        this.watchdogTimer = setTimeout(() => {
+            this.watchdogTimer = null;
+            this.reconnect("ServerInactivity");
+        }, SERVER_INACTIVITY_TIMEOUT_MS);
+    }
+    clearWatchdog() {
+        if (this.watchdogTimer !== null) {
+            clearTimeout(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+    }
+    /** Skip the backoff wait when the browser comes back online or the tab becomes visible. */
+    installEnvListeners() {
+        const g = globalThis;
+        if (typeof g.addEventListener !== "function" || typeof g.removeEventListener !== "function")
+            return () => { };
+        const kick = () => {
+            if (g.document?.visibilityState === "hidden")
+                return;
+            if (this._state === "disconnected" && this.reconnectTimer !== null) {
+                this.connect();
+            }
+        };
+        g.addEventListener("online", kick);
+        g.addEventListener("visibilitychange", kick);
+        return () => {
+            g.removeEventListener?.("online", kick);
+            g.removeEventListener?.("visibilitychange", kick);
+        };
+    }
+}
+//# sourceMappingURL=web_socket_manager.js.map

package/dist/web_socket_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_socket_manager.js","sourceRoot":"","sources":["../src/web_socket_manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@rxferrix/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Framework-agnostic reactive sync client for RxFerrix",
+  "license": "MIT",
+  "homepage": "https://genesysflow.github.io/rxferrix/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genesysflow/rxferrix.git",
+    "directory": "packages/client"
+  },
+  "keywords": [
+    "rxferrix",
+    "reactive",
+    "realtime",
+    "websocket"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.ts

@@ -0,0 +1,86 @@
+/**
+ * Function references: typed handles to server functions.
+ *
+ * Codegen emits an `api` object whose leaves are created with {@link makeFunctionReference}:
+ *
+ * ```ts
+ * export const api = {
+ *   todos: {
+ *     list: makeFunctionReference<"query", { done?: boolean | null }, Doc<"todos">[]>("query", "todos:list"),
+ *   },
+ * };
+ * ```
+ */
+
+/** The three kinds of public server functions. */
+export type FunctionKind = "query" | "mutation" | "action";
+
+/**
+ * A typed reference to a server function.
+ *
+ * Only `_kind` and `_path` exist at runtime. `__args` and `__output` are phantom fields that carry the argument and
+ * return types for inference; they are never present on the object.
+ */
+export interface FunctionReference<
+  Kind extends FunctionKind = FunctionKind,
+  Args = any,
+  Output = any,
+> {
+  readonly _kind: Kind;
+  readonly _path: string;
+  /** Phantom: never present at runtime. */
+  readonly __args: Args;
+  /** Phantom: never present at runtime. */
+  readonly __output: Output;
+}
+
+/** Any reference to a query. */
+export type AnyQueryReference = FunctionReference<"query", any, any>;
+/** Any reference to a mutation. */
+export type AnyMutationReference = FunctionReference<"mutation", any, any>;
+/** Any reference to an action. */
+export type AnyActionReference = FunctionReference<"action", any, any>;
+
+/** Creates a function reference. Used by generated code; rarely needed by hand. */
+export function makeFunctionReference<Kind extends FunctionKind, Args = Record<string, never>, Output = unknown>(
+  kind: Kind,
+  path: string,
+): FunctionReference<Kind, Args, Output> {
+  return Object.freeze({ _kind: kind, _path: path }) as unknown as FunctionReference<Kind, Args, Output>;
+}
+
+/** The argument object type of a function reference. */
+export type ArgsOf<F> = F extends FunctionReference<any, infer A, any> ? A : never;
+
+/** The return type of a function reference. */
+export type OutputOf<F> = F extends FunctionReference<any, any, infer O> ? O : never;
+
+/** True when every key of `Args` is optional (so the whole object may be omitted). */
+export type HasNoRequiredArgs<Args> = {} extends Args ? true : false;
+
+/**
+ * Rest-parameter tuple for a function's args: optional when the args object has no required keys.
+ *
+ * `fn(ref, ...args: OptionalArgs<typeof ref>)`
+ */
+export type OptionalArgs<F> = HasNoRequiredArgs<ArgsOf<F>> extends true
+  ? [args?: ArgsOf<F>]
+  : [args: ArgsOf<F>];
+
+/** Like {@link OptionalArgs} but also accepts `"skip"` in place of the args. */
+export type OptionalArgsOrSkip<F> = HasNoRequiredArgs<ArgsOf<F>> extends true
+  ? [args?: ArgsOf<F> | "skip"]
+  : [args: ArgsOf<F> | "skip"];
+
+/** Args followed by an optional options object; the args are optional when they have no required keys. */
+export type ArgsAndOptions<F, Options> = HasNoRequiredArgs<ArgsOf<F>> extends true
+  ? [args?: ArgsOf<F>, options?: Options]
+  : [args: ArgsOf<F>, options?: Options];
+
+/** A document ID for the given table. At runtime it is a plain string. */
+export type Id<TableName extends string> = string & { __tableName: TableName };
+
+/** Returns the `udfPath` (e.g. `"todos:list"`) of a function reference. */
+export function getFunctionName(ref: FunctionReference): string {
+  return ref._path;
+}