@rayfold/client 0.1.0

package/index.js

@@ -0,0 +1,7 @@
+export { RayfoldCache, entityKey, isRef } from "./cache.js";
+export { createFetchTransport, createLocalTransport } from "./transport.js";
+export { RayfoldClient, RayfoldClientError, Batch, OpHandle } from "./client.js";
+export { localStorageQueue, memoryQueue, isUnreachable } from "./offline.js";
+export { createWebSocketTransport } from "./ws-transport.js";
+export { restoreTypes, typeAtPath } from "./types.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAsF,MAAM,YAAY,CAAC;AAChJ,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAA8C,MAAM,gBAAgB,CAAC;AACxH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,EAAE,QAAQ,EAAgG,MAAM,aAAa,CAAC;AAC/K,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAA0D,MAAM,cAAc,CAAC;AACrI,OAAO,EAAE,wBAAwB,EAA2B,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC","sourcesContent":["export { RayfoldCache, entityKey, isRef, type EntityKey, type Ref, type CachedResult, type CacheListener, type OptimisticOp } from \"./cache.ts\";\nexport { createFetchTransport, createLocalTransport, type Transport, type FetchTransportOptions } from \"./transport.ts\";\nexport { RayfoldClient, RayfoldClientError, Batch, OpHandle, type ClientOptions, type OpOptions, type CommandOptions, type QueryOptions, type BatchResult } from \"./client.ts\";\nexport { localStorageQueue, memoryQueue, isUnreachable, type QueueStorage, type QueuedCommand, type QueueEvent } from \"./offline.ts\";\nexport { createWebSocketTransport, type WsTransportOptions } from \"./ws-transport.ts\";\nexport { restoreTypes, typeAtPath } from \"./types.ts\";\n"]}

package/offline.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The offline queue of sub-profile `sync` (spec 08 section 5): commands made while the server cannot be reached wait,
+ * in the order they were made and with their idempotency keys, and go out when the connection is back. The keys make
+ * the resend safe: a command the server ran before its answer was lost is replayed, not run again.
+ */
+import type { OptimisticOp } from "./cache.js";
+import type { OpOptions } from "./client.js";
+/** A command waiting for the server: everything needed to send it again, and to show its prediction meanwhile. */
+export interface QueuedCommand {
+    key: string;
+    op: string;
+    args: Record<string, unknown>;
+    options: OpOptions;
+    optimistic?: OptimisticOp[];
+    queuedAt: number;
+    /** Order of creation: a command queued late because its attempt failed late still goes out in its place. */
+    seq: number;
+}
+/** Where the queue is kept, so waiting commands survive a reload. */
+export interface QueueStorage {
+    load(): QueuedCommand[] | Promise<QueuedCommand[]>;
+    save(queue: readonly QueuedCommand[]): void | Promise<void>;
+}
+export interface QueueEvent {
+    type: "queued" | "sent" | "failed";
+    command: QueuedCommand;
+    /** Why the server refused a queued command (`failed`). */
+    error?: unknown;
+    /** Commands still waiting after this event. */
+    pending: number;
+}
+/** Keeps the queue in memory only: waiting commands are lost with the page. */
+export declare function memoryQueue(): QueueStorage;
+/** Keeps the queue in `localStorage` (or any storage with the same three methods) under `name`. */
+export declare function localStorageQueue(name?: string, storage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | undefined): QueueStorage;
+/** Whether a failure means the server could not be reached, so the command may go out again later with its key. */
+export declare function isUnreachable(e: unknown): boolean;
+/** @internal The queue itself; RayfoldClient owns one when created with `offline`. */
+export declare class OfflineQueue {
+    private readonly storage;
+    private readonly send;
+    /** Called once a command has left the queue, sent or refused: its prediction goes. */
+    private readonly settle;
+    private readonly entries;
+    private draining;
+    private readonly listeners;
+    readonly restored: Promise<void>;
+    constructor(storage: QueueStorage, send: (c: QueuedCommand) => Promise<unknown>, 
+    /** Called once a command has left the queue, sent or refused: its prediction goes. */
+    settle: (c: QueuedCommand) => void, 
+    /** Called for each command a reload brought back: its prediction is shown again. */
+    restore: (c: QueuedCommand) => void);
+    get size(): number;
+    get commands(): readonly QueuedCommand[];
+    add<T>(command: QueuedCommand): Promise<T>;
+    /** Sends waiting commands in order and resolves to how many still wait: the rest stay when the server is unreachable. */
+    drain(): Promise<number>;
+    private run;
+    subscribe(fn: (e: QueueEvent) => void): () => void;
+    private emit;
+}

package/offline.js

@@ -0,0 +1,119 @@
+/** Keeps the queue in memory only: waiting commands are lost with the page. */
+export function memoryQueue() {
+    let saved = [];
+    return { load: () => structuredClone(saved), save: (q) => void (saved = structuredClone([...q])) };
+}
+/** Keeps the queue in `localStorage` (or any storage with the same three methods) under `name`. */
+export function localStorageQueue(name = "rayfold.queue", storage = globalThis.localStorage) {
+    return {
+        load: () => {
+            const raw = storage?.getItem(name);
+            if (!raw)
+                return [];
+            try {
+                const v = JSON.parse(raw);
+                return Array.isArray(v) ? v : [];
+            }
+            catch {
+                return []; // a damaged entry is dropped rather than blocking every later command
+            }
+        },
+        save: (q) => {
+            if (!storage)
+                return;
+            if (q.length)
+                storage.setItem(name, JSON.stringify(q));
+            else
+                storage.removeItem(name);
+        },
+    };
+}
+/** Whether a failure means the server could not be reached, so the command may go out again later with its key. */
+export function isUnreachable(e) {
+    if (e instanceof TypeError)
+        return true; // what fetch throws when the network fails
+    return e?.code === "unavailable";
+}
+/** @internal The queue itself; RayfoldClient owns one when created with `offline`. */
+export class OfflineQueue {
+    storage;
+    send;
+    settle;
+    entries = [];
+    draining = null;
+    listeners = new Set();
+    restored;
+    constructor(storage, send, 
+    /** Called once a command has left the queue, sent or refused: its prediction goes. */
+    settle, 
+    /** Called for each command a reload brought back: its prediction is shown again. */
+    restore) {
+        this.storage = storage;
+        this.send = send;
+        this.settle = settle;
+        this.restored = Promise.resolve(storage.load()).then((saved) => {
+            for (const command of saved) {
+                this.entries.push({ command });
+                restore(command);
+            }
+        });
+    }
+    get size() {
+        return this.entries.length;
+    }
+    get commands() {
+        return this.entries.map((e) => e.command);
+    }
+    add(command) {
+        const p = new Promise((resolve, reject) => {
+            const at = this.entries.findIndex((e) => e.command.seq > command.seq);
+            this.entries.splice(at < 0 ? this.entries.length : at, 0, { command, resolve: resolve, reject });
+        });
+        p.catch(() => { }); // a caller that fired and forgot must not see an unhandled rejection later
+        void this.storage.save(this.commands);
+        this.emit({ type: "queued", command, pending: this.entries.length });
+        return p;
+    }
+    /** Sends waiting commands in order and resolves to how many still wait: the rest stay when the server is unreachable. */
+    drain() {
+        this.draining ??= this.run().finally(() => {
+            this.draining = null;
+        });
+        return this.draining;
+    }
+    async run() {
+        await this.restored;
+        while (this.entries.length) {
+            const e = this.entries[0];
+            let result;
+            try {
+                result = await this.send(e.command);
+            }
+            catch (err) {
+                if (isUnreachable(err))
+                    break; // still offline: it and everything behind it keep waiting
+                this.entries.shift();
+                await this.storage.save(this.commands);
+                this.settle(e.command);
+                e.reject?.(err);
+                this.emit({ type: "failed", command: e.command, error: err, pending: this.entries.length });
+                continue;
+            }
+            this.entries.shift();
+            await this.storage.save(this.commands);
+            this.settle(e.command);
+            e.resolve?.(result);
+            this.emit({ type: "sent", command: e.command, pending: this.entries.length });
+        }
+        return this.entries.length;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    emit(e) {
+        for (const fn of this.listeners)
+            fn(e);
+    }
+}
+//# sourceMappingURL=offline.js.map

package/offline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.js","sourceRoot":"","sources":["../src/offline.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The offline queue of sub-profile `sync` (spec 08 section 5): commands made while the server cannot be reached wait,\n * in the order they were made and with their idempotency keys, and go out when the connection is back. The keys make\n * the resend safe: a command the server ran before its answer was lost is replayed, not run again.\n */\nimport type { OptimisticOp } from \"./cache.ts\";\nimport type { OpOptions } from \"./client.ts\";\n\n/** A command waiting for the server: everything needed to send it again, and to show its prediction meanwhile. */\nexport interface QueuedCommand {\n  key: string;\n  op: string;\n  args: Record<string, unknown>;\n  options: OpOptions;\n  optimistic?: OptimisticOp[];\n  queuedAt: number;\n  /** Order of creation: a command queued late because its attempt failed late still goes out in its place. */\n  seq: number;\n}\n\n/** Where the queue is kept, so waiting commands survive a reload. */\nexport interface QueueStorage {\n  load(): QueuedCommand[] | Promise<QueuedCommand[]>;\n  save(queue: readonly QueuedCommand[]): void | Promise<void>;\n}\n\nexport interface QueueEvent {\n  type: \"queued\" | \"sent\" | \"failed\";\n  command: QueuedCommand;\n  /** Why the server refused a queued command (`failed`). */\n  error?: unknown;\n  /** Commands still waiting after this event. */\n  pending: number;\n}\n\n/** Keeps the queue in memory only: waiting commands are lost with the page. */\nexport function memoryQueue(): QueueStorage {\n  let saved: QueuedCommand[] = [];\n  return { load: () => structuredClone(saved), save: (q) => void (saved = structuredClone([...q])) };\n}\n\n/** Keeps the queue in `localStorage` (or any storage with the same three methods) under `name`. */\nexport function localStorageQueue(name = \"rayfold.queue\", storage: Pick<Storage, \"getItem\" | \"setItem\" | \"removeItem\"> | undefined = globalThis.localStorage): QueueStorage {\n  return {\n    load: () => {\n      const raw = storage?.getItem(name);\n      if (!raw) return [];\n      try {\n        const v: unknown = JSON.parse(raw);\n        return Array.isArray(v) ? (v as QueuedCommand[]) : [];\n      } catch {\n        return []; // a damaged entry is dropped rather than blocking every later command\n      }\n    },\n    save: (q) => {\n      if (!storage) return;\n      if (q.length) storage.setItem(name, JSON.stringify(q));\n      else storage.removeItem(name);\n    },\n  };\n}\n\n/** Whether a failure means the server could not be reached, so the command may go out again later with its key. */\nexport function isUnreachable(e: unknown): boolean {\n  if (e instanceof TypeError) return true; // what fetch throws when the network fails\n  return (e as { code?: unknown } | null)?.code === \"unavailable\";\n}\n\ninterface Entry {\n  command: QueuedCommand;\n  resolve?: (v: unknown) => void;\n  reject?: (e: unknown) => void;\n}\n\n/** @internal The queue itself; RayfoldClient owns one when created with `offline`. */\nexport class OfflineQueue {\n  private readonly entries: Entry[] = [];\n  private draining: Promise<number> | null = null;\n  private readonly listeners = new Set<(e: QueueEvent) => void>();\n  readonly restored: Promise<void>;\n\n  constructor(\n    private readonly storage: QueueStorage,\n    private readonly send: (c: QueuedCommand) => Promise<unknown>,\n    /** Called once a command has left the queue, sent or refused: its prediction goes. */\n    private readonly settle: (c: QueuedCommand) => void,\n    /** Called for each command a reload brought back: its prediction is shown again. */\n    restore: (c: QueuedCommand) => void,\n  ) {\n    this.restored = Promise.resolve(storage.load()).then((saved) => {\n      for (const command of saved) {\n        this.entries.push({ command });\n        restore(command);\n      }\n    });\n  }\n\n  get size(): number {\n    return this.entries.length;\n  }\n\n  get commands(): readonly QueuedCommand[] {\n    return this.entries.map((e) => e.command);\n  }\n\n  add<T>(command: QueuedCommand): Promise<T> {\n    const p = new Promise<T>((resolve, reject) => {\n      const at = this.entries.findIndex((e) => e.command.seq > command.seq);\n      this.entries.splice(at < 0 ? this.entries.length : at, 0, { command, resolve: resolve as (v: unknown) => void, reject });\n    });\n    p.catch(() => {}); // a caller that fired and forgot must not see an unhandled rejection later\n    void this.storage.save(this.commands);\n    this.emit({ type: \"queued\", command, pending: this.entries.length });\n    return p;\n  }\n\n  /** Sends waiting commands in order and resolves to how many still wait: the rest stay when the server is unreachable. */\n  drain(): Promise<number> {\n    this.draining ??= this.run().finally(() => {\n      this.draining = null;\n    });\n    return this.draining;\n  }\n\n  private async run(): Promise<number> {\n    await this.restored;\n    while (this.entries.length) {\n      const e = this.entries[0]!;\n      let result: unknown;\n      try {\n        result = await this.send(e.command);\n      } catch (err) {\n        if (isUnreachable(err)) break; // still offline: it and everything behind it keep waiting\n        this.entries.shift();\n        await this.storage.save(this.commands);\n        this.settle(e.command);\n        e.reject?.(err);\n        this.emit({ type: \"failed\", command: e.command, error: err, pending: this.entries.length });\n        continue;\n      }\n      this.entries.shift();\n      await this.storage.save(this.commands);\n      this.settle(e.command);\n      e.resolve?.(result);\n      this.emit({ type: \"sent\", command: e.command, pending: this.entries.length });\n    }\n    return this.entries.length;\n  }\n\n  subscribe(fn: (e: QueueEvent) => void): () => void {\n    this.listeners.add(fn);\n    return () => this.listeners.delete(fn);\n  }\n\n  private emit(e: QueueEvent): void {\n    for (const fn of this.listeners) fn(e);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rayfold/client",
+  "version": "0.1.0",
+  "description": "Rayfold client for browsers and Node.js: a normalized cache kept current by server patches, batching and live queries.",
+  "keywords": [
+    "rayfold",
+    "api",
+    "protocol",
+    "client",
+    "cache",
+    "fetch",
+    "websocket",
+    "live-queries"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://eddyboutros.github.io/rayfold/",
+  "bugs": {
+    "url": "https://github.com/eddyboutros/rayfold/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eddyboutros/rayfold.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@rayfold/schema": "^0.1.0",
+    "@rayfold/rb": "^0.1.0",
+    "@rayfold/server": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/transport.d.ts

@@ -0,0 +1,38 @@
+/** Transports deliver a batch and yield frames. Spec: spec/04. */
+import type { Frame, RequestEnvelope } from "@rayfold/server/protocol";
+import { type RayfoldSchemaIR } from "@rayfold/schema";
+export interface Transport {
+    send(envelope: RequestEnvelope, opts?: {
+        signal?: AbortSignal;
+        safe?: boolean;
+    }): AsyncIterable<Frame>;
+}
+/** A schema with the hash the server gives it, as GET /rayfold/manifest serves them. */
+export interface SchemaWithHash {
+    schema: RayfoldSchemaIR;
+    schemaHash: string;
+}
+export interface FetchTransportOptions {
+    url: string;
+    /** Extra headers per request (e.g. Authorization). */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+    /** Use the HTTP QUERY method for safe batches when the runtime supports it. Default: POST + Rayfold-Safe. */
+    useQueryMethod?: boolean;
+    /**
+     * Rayfold Binary: send and read RB instead of JSON. Pass the manifest from GET /rayfold/manifest, or the server's full
+     * schema IR. RB key numbers come from the schema, so RB is used only once a response's Rayfold-Schema header shows the
+     * server holds that same schema (spec 09 section 3). Until then, and after a response with another hash, requests go
+     * as JSON. The manifest's `schema` on its own hashes differently from the server's schema, so pass the whole manifest.
+     */
+    binary?: RayfoldSchemaIR | SchemaWithHash;
+}
+/** HTTP transport: POST (or QUERY) /rayfold, response is newline-delimited frames streamed as they arrive. */
+export declare function createFetchTransport(o: FetchTransportOptions): Transport;
+/** In-process transport over a RayfoldServer-like object (tests, SSR, workers). */
+export declare function createLocalTransport(server: {
+    execute(envelope: RequestEnvelope, opts?: {
+        viewer?: unknown;
+        signal?: AbortSignal;
+    }): AsyncIterable<Frame>;
+}, viewer?: () => unknown): Transport;

package/transport.js

@@ -0,0 +1,109 @@
+import { RbCodec, RB_CONTENT_TYPE } from "@rayfold/rb";
+import { schemaHash } from "@rayfold/schema";
+/** HTTP transport: POST (or QUERY) /rayfold, response is newline-delimited frames streamed as they arrive. */
+export function createFetchTransport(o) {
+    const f = o.fetch ?? globalThis.fetch;
+    const rb = o.binary
+        ? "schemaHash" in o.binary
+            ? { codec: new RbCodec(o.binary.schema), hash: o.binary.schemaHash }
+            : { codec: new RbCodec(o.binary), hash: schemaHash(o.binary) }
+        : null;
+    // the hash the server's last response reported; RB waits until it is known to match the codec's schema
+    let serverHash = null;
+    return {
+        send(envelope, opts = {}) {
+            return (async function* () {
+                const codec = rb !== null && serverHash === rb.hash ? rb.codec : null;
+                const headers = codec
+                    ? { "content-type": RB_CONTENT_TYPE, accept: RB_CONTENT_TYPE, ...(await o.headers?.()) }
+                    : { "content-type": "application/rayfold+json", accept: "application/rayfold-frames+json", ...(await o.headers?.()) };
+                let method = "POST";
+                if (opts.safe) {
+                    if (o.useQueryMethod)
+                        method = "QUERY";
+                    else
+                        headers["rayfold-safe"] = "true";
+                }
+                const init = { method, headers, body: codec ? codec.encode(envelope) : JSON.stringify(envelope) };
+                if (opts.signal)
+                    init.signal = opts.signal;
+                const res = await f(o.url, init);
+                const reported = res.headers.get("rayfold-schema");
+                if (reported)
+                    serverHash = reported;
+                const ct = res.headers.get("content-type") ?? "";
+                if (codec && ct.startsWith(RB_CONTENT_TYPE)) {
+                    if (reported !== rb?.hash) {
+                        // the server moved to another schema since the last response: its key numbers are not this codec's
+                        await res.body?.cancel();
+                        yield {
+                            error: { code: "unavailable", message: "The server's schema changed, so its binary answer cannot be read. Later requests use JSON; load the manifest again to use RB." },
+                            fin: true,
+                        };
+                        return;
+                    }
+                    const d = codec.decoder();
+                    if (res.body) {
+                        const reader = res.body.getReader();
+                        for (;;) {
+                            const { value, done } = await reader.read();
+                            if (done)
+                                break;
+                            for (const fr of d.feed(value))
+                                yield fr;
+                        }
+                    }
+                    else
+                        for (const fr of codec.decodeFrames(new Uint8Array(await res.arrayBuffer())))
+                            yield fr;
+                    return;
+                }
+                if (!res.ok && !ct.startsWith("application/rayfold-frames+json")) {
+                    const body = ct.includes("json") ? await res.json().catch(() => ({})) : {};
+                    const code = typeof body.code === "string" ? body.code : "unavailable";
+                    yield { error: { code, message: body.detail ?? `HTTP ${res.status}` }, fin: true };
+                    return;
+                }
+                if (!res.body) {
+                    const text = await res.text();
+                    for (const line of text.split("\n"))
+                        if (line.trim())
+                            yield JSON.parse(line);
+                    return;
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buf = "";
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buf += decoder.decode(value, { stream: true });
+                    let nl;
+                    while ((nl = buf.indexOf("\n")) >= 0) {
+                        const line = buf.slice(0, nl).trim();
+                        buf = buf.slice(nl + 1);
+                        if (line)
+                            yield JSON.parse(line);
+                    }
+                }
+                if (buf.trim())
+                    yield JSON.parse(buf);
+            })();
+        },
+    };
+}
+/** In-process transport over a RayfoldServer-like object (tests, SSR, workers). */
+export function createLocalTransport(server, viewer) {
+    return {
+        send(envelope, opts = {}) {
+            const o = {};
+            if (viewer)
+                o.viewer = viewer();
+            if (opts.signal)
+                o.signal = opts.signal;
+            return server.execute(envelope, o);
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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","sourcesContent":["/** Transports deliver a batch and yield frames. Spec: spec/04. */\nimport type { Frame, RequestEnvelope } from \"@rayfold/server/protocol\";\nimport { RbCodec, RB_CONTENT_TYPE } from \"@rayfold/rb\";\nimport { schemaHash, type RayfoldSchemaIR } from \"@rayfold/schema\";\n\nexport interface Transport {\n  send(envelope: RequestEnvelope, opts?: { signal?: AbortSignal; safe?: boolean }): AsyncIterable<Frame>;\n}\n\n/** A schema with the hash the server gives it, as GET /rayfold/manifest serves them. */\nexport interface SchemaWithHash {\n  schema: RayfoldSchemaIR;\n  schemaHash: string;\n}\n\nexport interface FetchTransportOptions {\n  url: string;\n  /** Extra headers per request (e.g. Authorization). */\n  headers?: () => Record<string, string> | Promise<Record<string, string>>;\n  fetch?: typeof fetch;\n  /** Use the HTTP QUERY method for safe batches when the runtime supports it. Default: POST + Rayfold-Safe. */\n  useQueryMethod?: boolean;\n  /**\n   * Rayfold Binary: send and read RB instead of JSON. Pass the manifest from GET /rayfold/manifest, or the server's full\n   * schema IR. RB key numbers come from the schema, so RB is used only once a response's Rayfold-Schema header shows the\n   * server holds that same schema (spec 09 section 3). Until then, and after a response with another hash, requests go\n   * as JSON. The manifest's `schema` on its own hashes differently from the server's schema, so pass the whole manifest.\n   */\n  binary?: RayfoldSchemaIR | SchemaWithHash;\n}\n\n/** HTTP transport: POST (or QUERY) /rayfold, response is newline-delimited frames streamed as they arrive. */\nexport function createFetchTransport(o: FetchTransportOptions): Transport {\n  const f = o.fetch ?? globalThis.fetch;\n  const rb = o.binary\n    ? \"schemaHash\" in o.binary\n      ? { codec: new RbCodec(o.binary.schema), hash: o.binary.schemaHash }\n      : { codec: new RbCodec(o.binary), hash: schemaHash(o.binary) }\n    : null;\n  // the hash the server's last response reported; RB waits until it is known to match the codec's schema\n  let serverHash: string | null = null;\n  return {\n    send(envelope, opts = {}) {\n      return (async function* () {\n        const codec = rb !== null && serverHash === rb.hash ? rb.codec : null;\n        const headers: Record<string, string> = codec\n          ? { \"content-type\": RB_CONTENT_TYPE, accept: RB_CONTENT_TYPE, ...(await o.headers?.()) }\n          : { \"content-type\": \"application/rayfold+json\", accept: \"application/rayfold-frames+json\", ...(await o.headers?.()) };\n        let method = \"POST\";\n        if (opts.safe) {\n          if (o.useQueryMethod) method = \"QUERY\";\n          else headers[\"rayfold-safe\"] = \"true\";\n        }\n        const init: RequestInit = { method, headers, body: codec ? (codec.encode(envelope) as BodyInit) : JSON.stringify(envelope) };\n        if (opts.signal) init.signal = opts.signal;\n        const res = await f(o.url, init);\n        const reported = res.headers.get(\"rayfold-schema\");\n        if (reported) serverHash = reported;\n        const ct = res.headers.get(\"content-type\") ?? \"\";\n        if (codec && ct.startsWith(RB_CONTENT_TYPE)) {\n          if (reported !== rb?.hash) {\n            // the server moved to another schema since the last response: its key numbers are not this codec's\n            await res.body?.cancel();\n            yield {\n              error: { code: \"unavailable\", message: \"The server's schema changed, so its binary answer cannot be read. Later requests use JSON; load the manifest again to use RB.\" },\n              fin: true,\n            } as Frame;\n            return;\n          }\n          const d = codec.decoder();\n          if (res.body) {\n            const reader = res.body.getReader();\n            for (;;) {\n              const { value, done } = await reader.read();\n              if (done) break;\n              for (const fr of d.feed(value)) yield fr as Frame;\n            }\n          } else for (const fr of codec.decodeFrames(new Uint8Array(await res.arrayBuffer()))) yield fr as Frame;\n          return;\n        }\n        if (!res.ok && !ct.startsWith(\"application/rayfold-frames+json\")) {\n          const body = ct.includes(\"json\") ? await res.json().catch(() => ({})) : {};\n          const code = typeof body.code === \"string\" ? body.code : \"unavailable\";\n          yield { error: { code, message: body.detail ?? `HTTP ${res.status}` }, fin: true } as Frame;\n          return;\n        }\n        if (!res.body) {\n          const text = await res.text();\n          for (const line of text.split(\"\\n\")) if (line.trim()) yield JSON.parse(line) as Frame;\n          return;\n        }\n        const reader = res.body.getReader();\n        const decoder = new TextDecoder();\n        let buf = \"\";\n        for (;;) {\n          const { value, done } = await reader.read();\n          if (done) break;\n          buf += decoder.decode(value, { stream: true });\n          let nl: number;\n          while ((nl = buf.indexOf(\"\\n\")) >= 0) {\n            const line = buf.slice(0, nl).trim();\n            buf = buf.slice(nl + 1);\n            if (line) yield JSON.parse(line) as Frame;\n          }\n        }\n        if (buf.trim()) yield JSON.parse(buf) as Frame;\n      })();\n    },\n  };\n}\n\n/** In-process transport over a RayfoldServer-like object (tests, SSR, workers). */\nexport function createLocalTransport(server: { execute(envelope: RequestEnvelope, opts?: { viewer?: unknown; signal?: AbortSignal }): AsyncIterable<Frame> }, viewer?: () => unknown): Transport {\n  return {\n    send(envelope, opts = {}) {\n      const o: { viewer?: unknown; signal?: AbortSignal } = {};\n      if (viewer) o.viewer = viewer();\n      if (opts.signal) o.signal = opts.signal;\n      return server.execute(envelope, o);\n    },\n  };\n}\n"]}

package/types.d.ts

@@ -0,0 +1,5 @@
+/** Schema-aware type restoration for compact frames: re-adds `$type` where the static type is an entity. */
+import { type RayfoldSchemaIR, type TypeRef } from "@rayfold/schema";
+export declare function restoreTypes(ir: RayfoldSchemaIR, t: TypeRef, v: unknown): unknown;
+/** Static type at a result path such as "items.0.author" (indices skip list levels). */
+export declare function typeAtPath(ir: RayfoldSchemaIR, root: TypeRef, path: string): TypeRef | undefined;

package/types.js

@@ -0,0 +1,48 @@
+/** Schema-aware type restoration for compact frames: re-adds `$type` where the static type is an entity. */
+import { fieldsOf } from "@rayfold/schema";
+export function restoreTypes(ir, t, v) {
+    if (v === null || typeof v !== "object")
+        return v;
+    if (t.kind === "list")
+        return Array.isArray(v) ? v.map((x) => restoreTypes(ir, t.of, x)) : v;
+    if (Array.isArray(v))
+        return v;
+    const o = v;
+    const explicit = typeof o["$type"] === "string" ? o["$type"] : undefined;
+    const def = ir.types[explicit ?? t.name];
+    if (!def)
+        return v;
+    const out = {};
+    if (def.kind === "entity")
+        out["$type"] = def.name;
+    const ref = explicit ? { kind: "named", name: explicit, nullable: false } : t;
+    const fields = fieldsOf(ir, ref) ?? [];
+    for (const [k, x] of Object.entries(o)) {
+        if (k === "$type")
+            continue;
+        const f = fields.find((fd) => fd.name === k);
+        out[k] = f ? restoreTypes(ir, f.type, x) : x;
+    }
+    return out;
+}
+/** Static type at a result path such as "items.0.author" (indices skip list levels). */
+export function typeAtPath(ir, root, path) {
+    let t = root;
+    if (path === "")
+        return t;
+    for (const seg of path.split(".")) {
+        if (/^\d+$/.test(seg)) {
+            if (t.kind === "list")
+                t = t.of;
+            continue;
+        }
+        while (t.kind === "list")
+            t = t.of;
+        const f = (fieldsOf(ir, t) ?? []).find((fd) => fd.name === seg);
+        if (!f)
+            return undefined;
+        t = f.type;
+    }
+    return t;
+}
+//# sourceMappingURL=types.js.map

package/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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","sourcesContent":["/** Schema-aware type restoration for compact frames: re-adds `$type` where the static type is an entity. */\nimport { fieldsOf, type RayfoldSchemaIR, type TypeRef } from \"@rayfold/schema\";\n\nexport function restoreTypes(ir: RayfoldSchemaIR, t: TypeRef, v: unknown): unknown {\n  if (v === null || typeof v !== \"object\") return v;\n  if (t.kind === \"list\") return Array.isArray(v) ? v.map((x) => restoreTypes(ir, t.of, x)) : v;\n  if (Array.isArray(v)) return v;\n  const o = v as Record<string, unknown>;\n  const explicit = typeof o[\"$type\"] === \"string\" ? o[\"$type\"] : undefined;\n  const def = ir.types[explicit ?? t.name];\n  if (!def) return v;\n  const out: Record<string, unknown> = {};\n  if (def.kind === \"entity\") out[\"$type\"] = def.name;\n  const ref: TypeRef = explicit ? { kind: \"named\", name: explicit, nullable: false } : t;\n  const fields = fieldsOf(ir, ref) ?? [];\n  for (const [k, x] of Object.entries(o)) {\n    if (k === \"$type\") continue;\n    const f = fields.find((fd) => fd.name === k);\n    out[k] = f ? restoreTypes(ir, f.type, x) : x;\n  }\n  return out;\n}\n\n/** Static type at a result path such as \"items.0.author\" (indices skip list levels). */\nexport function typeAtPath(ir: RayfoldSchemaIR, root: TypeRef, path: string): TypeRef | undefined {\n  let t: TypeRef = root;\n  if (path === \"\") return t;\n  for (const seg of path.split(\".\")) {\n    if (/^\\d+$/.test(seg)) {\n      if (t.kind === \"list\") t = t.of;\n      continue;\n    }\n    while (t.kind === \"list\") t = t.of;\n    const f = (fieldsOf(ir, t) ?? []).find((fd) => fd.name === seg);\n    if (!f) return undefined;\n    t = f.type;\n  }\n  return t;\n}\n"]}

package/ws-transport.d.ts

@@ -0,0 +1,16 @@
+import type { RayfoldSchemaIR } from "@rayfold/schema";
+import type { Transport } from "./transport.js";
+export interface WsTransportOptions {
+    url: string;
+    /** Subprotocols; default ["rayfold.0.1"]. */
+    protocols?: string[];
+    /** WebSocket constructor (defaults to the global one). */
+    WebSocket?: typeof WebSocket;
+    /** Called to build a fresh socket URL (e.g. to append a token) before each connect. */
+    connectUrl?: () => string | Promise<string>;
+    /** Rayfold Binary: pass the schema IR (from /rayfold/manifest) to send and receive RB messages instead of JSON text. */
+    binary?: RayfoldSchemaIR;
+}
+export declare function createWebSocketTransport(o: WsTransportOptions): Transport & {
+    close(): void;
+};