octane 0.2.11 → 0.2.13

package/dist/server-rpc-batch-client.js

@@ -0,0 +1,119 @@
+import { readServerResult } from "./server-rpc-stream-client.js";
+import {
+  ServerCallUncertainError,
+  serverResultLimits,
+  validateServerCallBatch
+} from "./server-rpc-protocol.js";
+const SERVER_BATCH_CONTENT_TYPE = "application/x-octane-rpc-batch+ndjson";
+let collecting;
+function batchServerCalls(options, callback) {
+  validateServerCallBatch(options);
+  const previous = collecting;
+  collecting = { options: { ...options }, members: [] };
+  try {
+    return callback();
+  } finally {
+    collecting = previous;
+  }
+}
+function enqueueServerCall(hash, body, options, limits) {
+  const batch = collecting;
+  if (batch === void 0 || limits !== void 0) return void 0;
+  if (batch.members.length === 32) {
+    collecting = { options: batch.options, members: [] };
+    return enqueueServerCall(hash, body, options);
+  }
+  if (batch.members.length === 0)
+    queueMicrotask(() => {
+      void dispatch(batch);
+    });
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      if (member.settled) return;
+      member.settled = true;
+      member.dispose();
+      reject(new ServerCallUncertainError(options.signal?.reason));
+    };
+    const member = {
+      hash,
+      body,
+      signal: options.signal,
+      resolve,
+      reject,
+      settled: false,
+      dispose: () => options.signal?.removeEventListener("abort", abort)
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    batch.members.push(member);
+    if (options.signal?.aborted) abort();
+  });
+}
+async function dispatch(batch) {
+  const members = batch.members.filter((member) => !member.settled);
+  if (members.length === 0) return;
+  const limits = serverResultLimits(batch.options);
+  const transport = new AbortController();
+  let definitiveRejection = false;
+  const timer = setTimeout(
+    () => transport.abort(new DOMException("Server batch timed out", "TimeoutError")),
+    limits.timeoutMs
+  );
+  try {
+    const response = await fetch(
+      new URL("/_$_ripple_rpc_$_/" + members[0].hash, globalThis.location.href).href,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: SERVER_BATCH_CONTENT_TYPE },
+        body: JSON.stringify([1, members.map((member, id) => [id, member.hash, member.body])]),
+        signal: transport.signal
+      }
+    );
+    if (!response.ok || response.headers.get("content-type")?.split(";", 1)[0] !== SERVER_BATCH_CONTENT_TYPE) {
+      definitiveRejection = !response.ok && response.headers.get("Octane-RPC-Outcome") === "rejected";
+      try {
+        void response.body?.cancel().catch(() => {
+        });
+      } catch {
+      }
+      throw new Error("Server-call batching was rejected or is unavailable");
+    }
+    const result = await readServerResult(response, { ...limits, signal: transport.signal });
+    if (result === null || typeof result !== "object" || !(Symbol.asyncIterator in result)) {
+      throw new Error("Invalid server batch result");
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for await (const frame of result) {
+      if (!Array.isArray(frame) || frame.length !== 3 || !Number.isSafeInteger(frame[0]) || frame[0] < 0 || frame[0] >= members.length || seen.has(frame[0]) || !["value", "rejected", "uncertain"].includes(frame[1]) || frame[1] !== "value" && typeof frame[2] !== "string") {
+        throw new Error("Invalid or duplicate server batch member");
+      }
+      seen.add(frame[0]);
+      const member = members[frame[0]];
+      if (member.settled) continue;
+      member.settled = true;
+      member.dispose();
+      if (frame[1] === "value") member.resolve(frame[2]);
+      else {
+        const error = new Error(frame[2]);
+        member.reject(frame[1] === "rejected" ? error : new ServerCallUncertainError(error));
+      }
+    }
+    if (seen.size !== members.length) throw new Error("Server batch ended with missing members");
+  } catch (error) {
+    for (const member of members) {
+      if (member.settled) continue;
+      member.settled = true;
+      member.dispose();
+      member.reject(
+        definitiveRejection || error instanceof ServerCallUncertainError ? error : new ServerCallUncertainError(error)
+      );
+    }
+  } finally {
+    clearTimeout(timer);
+    transport.abort();
+  }
+}
+export {
+  SERVER_BATCH_CONTENT_TYPE,
+  batchServerCalls,
+  enqueueServerCall
+};

package/dist/server-rpc-client.d.ts

@@ -1,5 +1,7 @@
+import type { ServerCallOptions } from './server-call.js';
+import { type ServerResultLimits } from './server-rpc-protocol.js';
 /**
  * Compiler target for browser calls to a `module server` export.
  * @internal
  */
-export declare function __serverRpc(hash: string, args: unknown[]): Promise<unknown>;
+export declare function __serverRpc(hash: string, args: unknown[], options?: ServerCallOptions, stream?: boolean, limits?: ServerResultLimits): Promise<unknown>;

package/dist/server-rpc-client.js

@@ -1,35 +1,107 @@
 import * as devalue from "devalue";
-async function __serverRpc(hash, args) {
-  let response;
-  try {
-    response = await fetch("/_$_ripple_rpc_$_/" + hash, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: devalue.stringify(args)
-    });
-  } catch {
-    throw new Error("An error occurred while trying to call the Octane server function.");
+import {
+  SERVER_RESULT_CONTENT_TYPE,
+  ServerCallUncertainError,
+  encodeServerArguments,
+  serverResultLimits
+} from "./server-rpc-protocol.js";
+import { readServerResult } from "./server-rpc-stream-client.js";
+import { enqueueServerCall } from "./server-rpc-batch-client.js";
+async function __serverRpc(hash, args, options = {}, stream = false, limits) {
+  if (options === null || typeof options !== "object" || Object.keys(options).some((key) => key !== "signal") || options.signal !== void 0 && !(options.signal instanceof AbortSignal))
+    throw new TypeError("Server function options accept only a local AbortSignal");
+  options.signal?.throwIfAborted();
+  const resolvedLimits = stream ? serverResultLimits(limits) : void 0;
+  const payload = stream ? encodeServerArguments(args) : devalue.stringify(args);
+  if (stream) {
+    const batched = enqueueServerCall(hash, payload, options, limits);
+    if (batched !== void 0) return batched;
   }
-  if (!response.ok) {
-    let message = `Server function call failed with status ${response.status}`;
-    const body2 = await response.text().catch(() => "");
-    if (body2) {
-      try {
-        const parsed = JSON.parse(body2);
-        message = typeof parsed?.error === "string" && parsed.error ? parsed.error : body2;
-      } catch {
-        message = body2;
+  const deadline = resolvedLimits === void 0 ? void 0 : Date.now() + resolvedLimits.timeoutMs;
+  const cancellation = resolvedLimits === void 0 ? void 0 : new AbortController();
+  const timer = resolvedLimits === void 0 ? void 0 : setTimeout(() => {
+    cancellation.abort(new DOMException("Server function timed out", "TimeoutError"));
+  }, resolvedLimits.timeoutMs);
+  const signal = cancellation === void 0 ? options.signal : options.signal === void 0 ? cancellation.signal : AbortSignal.any([options.signal, cancellation.signal]);
+  try {
+    let response;
+    try {
+      response = await fetch(new URL("/_$_ripple_rpc_$_/" + hash, globalThis.location.href).href, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...stream ? { Accept: SERVER_RESULT_CONTENT_TYPE } : {}
+        },
+        body: payload,
+        signal
+      });
+    } catch (cause) {
+      throw new ServerCallUncertainError(
+        new Error("An error occurred while trying to call the Octane server function.", { cause })
+      );
+    }
+    if (!response.ok) {
+      let message = `Server function call failed with status ${response.status}`;
+      let body2 = "";
+      if (stream) {
+        try {
+          void response.body?.cancel().catch(() => {
+          });
+        } catch {
+        }
+      } else {
+        body2 = await response.text().catch(() => "");
       }
+      if (body2) {
+        try {
+          const parsed = JSON.parse(body2);
+          message = typeof parsed?.error === "string" && parsed.error ? parsed.error : body2;
+        } catch {
+          message = body2;
+        }
+      }
+      const error = Object.assign(new Error(message), { status: response.status });
+      throw response.headers.get("Octane-RPC-Outcome") === "rejected" ? error : new ServerCallUncertainError(error);
     }
-    throw new Error(message);
-  }
-  const body = await response.text();
-  if (body === "") {
-    throw new Error(
-      "The server function endpoint returned an empty response. Is the Octane server running?"
-    );
+    if (stream) {
+      if (response.headers.get("content-type")?.split(";", 1)[0] !== SERVER_RESULT_CONTENT_TYPE) {
+        void response.body?.cancel().catch(() => {
+        });
+        throw new ServerCallUncertainError(
+          new Error("The server does not support the requested result protocol")
+        );
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        void response.body?.cancel().catch(() => {
+        });
+        throw new ServerCallUncertainError(
+          new DOMException("Server function timed out", "TimeoutError")
+        );
+      }
+      return await readServerResult(response, { ...resolvedLimits, timeoutMs: remaining, signal });
+    }
+    let body;
+    try {
+      body = await response.text();
+    } catch (error) {
+      throw new ServerCallUncertainError(error);
+    }
+    if (body === "") {
+      throw new ServerCallUncertainError(
+        new Error(
+          "The server function endpoint returned an empty response. Is the Octane server running?"
+        )
+      );
+    }
+    try {
+      return devalue.parse(body).value;
+    } catch (error) {
+      throw new ServerCallUncertainError(error);
+    }
+  } finally {
+    clearTimeout(timer);
   }
-  return devalue.parse(body).value;
 }
 export {
   __serverRpc

package/dist/server-rpc-protocol.d.ts

@@ -0,0 +1,47 @@
+/** The streamed protocol is opt-in; legacy devalue RPC remains unchanged. */
+export declare const SERVER_RESULT_CONTENT_TYPE = "application/x-octane-rpc+ndjson";
+export declare function encodeServerArguments(args: unknown[]): string;
+export declare function decodeServerArguments(body: string): unknown[];
+/** No authoritative receipt arrived; retrying a mutation could execute it twice. */
+export declare class ServerCallUncertainError extends Error {
+    readonly code = "OCTANE_RPC_UNCERTAIN";
+    constructor(cause: unknown);
+}
+export interface ServerResultLimits {
+    /** Maximum encoded bytes in one complete value or terminal frame. */
+    maxFrameBytes?: number;
+    /** Maximum bytes in this invocation, independently of the request-body limit. */
+    maxTotalBytes?: number;
+    /** Total invocation lifetime, including a stalled producer or consumer. */
+    timeoutMs?: number;
+}
+export interface ServerCallBatchOptions extends ServerResultLimits {
+    /** Explicitly asserts independent, finite reads; mutations/subscriptions stay outside. */
+    kind: 'independent-reads';
+    /** Local compatibility keys, not credentials sent to or trusted by the server. */
+    authority: string;
+    document: string;
+}
+export declare function validateServerCallBatch(options: ServerCallBatchOptions): void;
+export interface ResolvedServerResultLimits {
+    maxFrameBytes: number;
+    maxTotalBytes: number;
+    timeoutMs: number;
+}
+export declare function serverResultLimits(limits?: ServerResultLimits): ResolvedServerResultLimits;
+export type ServerResultFrame = {
+    kind: 'stream' | 'complete';
+} | {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'error';
+    error: string;
+};
+export declare function encodeServerResultFrame(sequence: number, frame: ServerResultFrame): Uint8Array;
+export declare function decodeServerResultFrame(line: string, sequence: number): ServerResultFrame;
+/**
+ * Read one line at a time without concatenating the entire response or repeatedly
+ * copying a growing partial frame. A transport chunk may contain several frames.
+ */
+export declare function serverResultReader(reader: ReadableStreamDefaultReader<Uint8Array>, limits: ResolvedServerResultLimits): () => Promise<ServerResultFrame>;

package/dist/server-rpc-protocol.js

@@ -0,0 +1,109 @@
+import { decodeSignalValue, encodeSignalValue } from "./data-encoding.js";
+const SERVER_RESULT_CONTENT_TYPE = "application/x-octane-rpc+ndjson";
+function encodeServerArguments(args) {
+  return JSON.stringify([1, encodeSignalValue(args)]);
+}
+function decodeServerArguments(body) {
+  const envelope = JSON.parse(body);
+  if (!Array.isArray(envelope) || envelope.length !== 2 || envelope[0] !== 1) {
+    throw new Error("Invalid server argument protocol");
+  }
+  const args = decodeSignalValue(envelope[1]);
+  if (!Array.isArray(args)) throw new Error("Invalid server arguments");
+  return args;
+}
+class ServerCallUncertainError extends Error {
+  code = "OCTANE_RPC_UNCERTAIN";
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : "Server function outcome is uncertain", {
+      cause
+    });
+    this.name = "ServerCallUncertainError";
+  }
+}
+function validateServerCallBatch(options) {
+  if (options.kind !== "independent-reads" || !options.authority || !options.document) {
+    throw new TypeError(
+      "A server-call batch requires independent reads and authority/document keys"
+    );
+  }
+  serverResultLimits(options);
+}
+function serverResultLimits(limits = {}) {
+  const result = {
+    maxFrameBytes: limits.maxFrameBytes ?? 1024 * 1024,
+    maxTotalBytes: limits.maxTotalBytes ?? 16 * 1024 * 1024,
+    timeoutMs: limits.timeoutMs ?? 3e4
+  };
+  for (const value of Object.values(result)) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new RangeError("Server result limits must be positive safe integers");
+    }
+  }
+  if (result.maxFrameBytes > result.maxTotalBytes) {
+    throw new RangeError("A server result frame cannot exceed the total response budget");
+  }
+  return result;
+}
+function encodeServerResultFrame(sequence, frame) {
+  const payload = frame.kind === "value" ? encodeSignalValue(frame.value) : frame.kind === "error" ? frame.error : null;
+  return new TextEncoder().encode(JSON.stringify([1, sequence, frame.kind, payload]) + "\n");
+}
+function decodeServerResultFrame(line, sequence) {
+  const frame = JSON.parse(line);
+  if (!Array.isArray(frame) || frame.length !== 4 || frame[0] !== 1 || frame[1] !== sequence) {
+    throw new Error("Invalid or out-of-order server result frame");
+  }
+  const [, , kind, payload] = frame;
+  if (kind === "value") {
+    return { kind, value: decodeSignalValue(payload) };
+  }
+  if (kind === "error" && typeof payload === "string") return { kind, error: payload };
+  if ((kind === "stream" || kind === "complete") && payload === null) return { kind };
+  throw new Error("Invalid server result frame");
+}
+function serverResultReader(reader, limits) {
+  let chunk = new Uint8Array(0);
+  let offset = 0;
+  let sequence = 0;
+  let totalBytes = 0;
+  return async () => {
+    const parts = [];
+    let bytes = 0;
+    while (true) {
+      if (offset === chunk.length) {
+        const next = await reader.read();
+        if (next.done) throw new Error("Server result ended without a terminal frame");
+        chunk = next.value;
+        offset = 0;
+      }
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline + 1;
+      const part = chunk.subarray(offset, end);
+      bytes += part.length;
+      totalBytes += part.length;
+      if (bytes > limits.maxFrameBytes || totalBytes > limits.maxTotalBytes) {
+        throw new Error("Server result exceeded its response budget");
+      }
+      parts.push(part);
+      offset = end;
+      if (newline !== -1) {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        const text = parts.map((value) => decoder.decode(value, { stream: true }));
+        text.push(decoder.decode());
+        return decodeServerResultFrame(text.join(""), sequence++);
+      }
+    }
+  };
+}
+export {
+  SERVER_RESULT_CONTENT_TYPE,
+  ServerCallUncertainError,
+  decodeServerArguments,
+  decodeServerResultFrame,
+  encodeServerArguments,
+  encodeServerResultFrame,
+  serverResultLimits,
+  serverResultReader,
+  validateServerCallBatch
+};

package/dist/server-rpc-stream-client.d.ts

@@ -0,0 +1,5 @@
+import { type ServerResultLimits } from './server-rpc-protocol.js';
+/** A single-consumer result; iterator.return() cancels only this invocation. */
+export declare function readServerResult(response: Response, options?: ServerResultLimits & {
+    signal?: AbortSignal;
+}): Promise<unknown>;

package/dist/server-rpc-stream-client.js

@@ -0,0 +1,98 @@
+import {
+  serverResultLimits,
+  serverResultReader,
+  ServerCallUncertainError
+} from "./server-rpc-protocol.js";
+async function readServerResult(response, options = {}) {
+  if (response.body === null)
+    throw new ServerCallUncertainError(new Error("Server function returned an empty response"));
+  const limits = serverResultLimits(options);
+  const reader = response.body.getReader();
+  const read = serverResultReader(reader, limits);
+  let finished = false;
+  let failure;
+  const cleanup = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  };
+  const close = async () => {
+    if (finished) return;
+    finished = true;
+    cleanup();
+    try {
+      void reader.cancel().catch(() => {
+      });
+    } catch {
+    }
+    reader.releaseLock();
+  };
+  const abort = () => {
+    failure = new ServerCallUncertainError(
+      options.signal?.reason ?? new DOMException("Server function canceled", "AbortError")
+    );
+    void close();
+  };
+  const timer = setTimeout(() => {
+    failure = new ServerCallUncertainError(
+      new DOMException("Server function timed out", "TimeoutError")
+    );
+    void close();
+  }, limits.timeoutMs);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+  const next = async () => {
+    if (failure !== void 0) throw failure;
+    try {
+      const frame = await read();
+      if (failure !== void 0) throw failure;
+      if (frame.kind === "error") throw new Error(frame.error);
+      return frame;
+    } catch (error) {
+      await close();
+      throw failure ?? new ServerCallUncertainError(error);
+    }
+  };
+  try {
+    const first = await next();
+    if (first.kind === "value") {
+      if ((await next()).kind !== "complete") throw new Error("Invalid one-shot server result");
+      await close();
+      return first.value;
+    }
+    if (first.kind !== "stream") throw new Error("Invalid server result opening frame");
+    let claimed = false;
+    return {
+      [Symbol.asyncIterator]() {
+        if (claimed) throw new Error("A server result stream supports one consumer");
+        claimed = true;
+        let pulls = Promise.resolve();
+        const pull = async () => {
+          if (failure !== void 0) throw failure;
+          if (finished) return { done: true, value: void 0 };
+          const frame = await next();
+          if (frame.kind === "value") return { done: false, value: frame.value };
+          await close();
+          if (frame.kind !== "complete") throw new Error("Invalid server result continuation");
+          return { done: true, value: void 0 };
+        };
+        return {
+          next() {
+            const result = pulls.then(pull, pull);
+            pulls = result;
+            return result;
+          },
+          async return() {
+            await close();
+            return { done: true, value: void 0 };
+          }
+        };
+      }
+    };
+  } catch (error) {
+    await close();
+    throw error instanceof ServerCallUncertainError ? error : new ServerCallUncertainError(error);
+  }
+}
+export {
+  readServerResult
+};

package/dist/signals/actions.d.ts

@@ -0,0 +1,12 @@
+import { type ActionOperation, type ActionUncertain, type OptimisticOptions, type OptimisticSignal, type SignalAction, type SignalHandle } from './types.js';
+export declare class ActionUncertainError extends Error {
+    readonly operationId: string;
+    readonly code = "OCTANE_ACTION_UNCERTAIN";
+    constructor(operationId: string, options: {
+        cause: unknown;
+    });
+}
+export declare function optimistic$<T>(source$: SignalHandle<T>, options?: OptimisticOptions<T>): OptimisticSignal<T>;
+export declare function action$<F extends (operation: ActionOperation, ...args: any[]) => any>(handler: F): SignalAction<F>;
+export declare function action$<F extends (operation: ActionOperation, ...args: any[]) => any>(key: string, handler: F): SignalAction<F>;
+export declare function isActionUncertain(value: unknown): value is ActionUncertain | ActionUncertainError;