@tscomfy/client 0.0.0-stage → 0.1.2

package/src/frames.ts

@@ -0,0 +1,87 @@
+import { type NodeId, parse } from "@tscomfy/core";
+import { isObject } from "./http.ts";
+
+/** A preview image: binary type 4, which carries the node and prompt it belongs to. */
+export interface PreviewFrame {
+  readonly kind: "preview";
+  readonly promptId: string;
+  readonly node: NodeId;
+  readonly mime: string;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+
+/** Progress text: binary type 3. Only newer servers say which prompt it belongs to. */
+export interface TextFrame {
+  readonly kind: "text";
+  readonly promptId: string | undefined;
+  readonly node: NodeId;
+  readonly text: string;
+}
+
+const TEXT = 3;
+const PREVIEW_WITH_METADATA = 4;
+
+/**
+ * Decodes a binary websocket frame: a big-endian `uint32` type, then the payload. Type 1 (a
+ * preview without ids) isn't decoded: the client asks for type 4 instead, and an unattributed
+ * image can't be given to a job. Unknown types and malformed frames give `undefined`.
+ * `textHasPromptId` is the server's `supports_progress_text_metadata` flag.
+ */
+export function decodeFrame(
+  data: ArrayBuffer,
+  textHasPromptId: boolean,
+): PreviewFrame | TextFrame | undefined {
+  if (data.byteLength < 4) return undefined;
+  const view = new DataView(data);
+  const type = view.getUint32(0);
+  if (type === PREVIEW_WITH_METADATA) return preview(data, view);
+  if (type === TEXT) return text(data, view, textHasPromptId);
+  return undefined;
+}
+
+function preview(data: ArrayBuffer, view: DataView): PreviewFrame | undefined {
+  const length = readLength(view, 4);
+  if (length === undefined) return undefined;
+  const metadata = parse(decoder.decode(new Uint8Array(data, 8, length))).value;
+  if (!isObject(metadata)) return undefined;
+  const promptId = metadata["prompt_id"];
+  const node = metadata["display_node_id"] ?? metadata["node_id"];
+  const mime = metadata["image_type"];
+  if (typeof promptId !== "string" || typeof node !== "string") return undefined;
+  return {
+    kind: "preview",
+    promptId,
+    node,
+    mime: typeof mime === "string" ? mime : "image/jpeg",
+    bytes: new Uint8Array(data.slice(8 + length)),
+  };
+}
+
+function text(data: ArrayBuffer, view: DataView, hasPromptId: boolean): TextFrame | undefined {
+  let offset = 4;
+  let promptId: string | undefined;
+  if (hasPromptId) {
+    const length = readLength(view, offset);
+    if (length === undefined) return undefined;
+    promptId = decoder.decode(new Uint8Array(data, offset + 4, length));
+    offset += 4 + length;
+  }
+  const length = readLength(view, offset);
+  if (length === undefined) return undefined;
+  const node = decoder.decode(new Uint8Array(data, offset + 4, length));
+  return {
+    kind: "text",
+    promptId,
+    node,
+    text: decoder.decode(new Uint8Array(data, offset + 4 + length)),
+  };
+}
+
+/** A `uint32` length at `offset` whose bytes fit in the frame after it. */
+function readLength(view: DataView, offset: number): number | undefined {
+  if (view.byteLength < offset + 4) return undefined;
+  const length = view.getUint32(offset);
+  return offset + 4 + length <= view.byteLength ? length : undefined;
+}
+
+const decoder = new TextDecoder();

package/src/http.ts

@@ -0,0 +1,113 @@
+import { type JsonObject, type JsonValue, parse } from "@tscomfy/core";
+import { ClientError } from "./client-error.ts";
+import type { Server } from "./server.ts";
+import { baseUrl, endpoint, shownUrl } from "./url.ts";
+
+/** One HTTP request to a server. */
+export interface Request {
+  readonly method: "GET" | "POST";
+  /** Under the server's path: `prompt`, `api/jobs/<id>`. */
+  readonly path: string;
+  readonly query?: Readonly<Record<string, string>>;
+  readonly body?: string | FormData;
+  readonly signal?: AbortSignal | undefined;
+}
+
+/**
+ * Sends a request and returns the response, whatever its status. A failure to reach the server
+ * is a {@link ClientError}; an aborted signal rejects with the signal's reason, as `fetch` does.
+ */
+export async function send(server: Server, request: Request): Promise<Response> {
+  const url = endpoint(baseUrl(server), request.path, request.query);
+  const headers = new Headers(server.headers);
+  if (typeof request.body === "string") headers.set("content-type", "application/json");
+  const fetcher = server.fetch ?? globalThis.fetch;
+  try {
+    return await fetcher(url, {
+      method: request.method,
+      headers,
+      body: request.body ?? null,
+      signal: request.signal ?? null,
+    });
+  } catch (error) {
+    if (request.signal?.aborted === true) throw request.signal.reason;
+    // The runtime's message may quote the URL, query and all.
+    const why = describe(error).replaceAll(url.href, shownUrl(url));
+    throw new ClientError(`Could not reach ${shownUrl(url)}: ${why}`, { cause: error });
+  }
+}
+
+/** The response's body as JSON, read losslessly (big integers stay exact). */
+export async function readJson(response: Response): Promise<JsonValue> {
+  const text = await response.text();
+  const { value } = parse(text);
+  if (value === undefined) {
+    throw new ClientError(`${where(response)} answered with a body that isn't JSON`, {
+      status: response.status,
+    });
+  }
+  return value;
+}
+
+/** The response's body as a JSON object; anything else is a {@link ClientError}. */
+export async function readObject(response: Response): Promise<JsonObject> {
+  const value = await readJson(response);
+  if (!isObject(value)) {
+    throw new ClientError(`${where(response)} answered with JSON that isn't an object`, {
+      status: response.status,
+    });
+  }
+  return value;
+}
+
+/** A {@link ClientError} for an answer the protocol doesn't expect, with the body's message. */
+export async function unexpected(response: Response): Promise<ClientError> {
+  const answer = `${String(response.status)} ${response.statusText}`.trimEnd();
+  // Best effort: the status says what went wrong; the body may say why.
+  const body = await response.text().catch(() => "");
+  const detail = bodyMessage(body);
+  return new ClientError(
+    `${where(response)} answered ${answer}${detail === undefined ? "" : `: ${detail}`}`,
+    { status: response.status },
+  );
+}
+
+/** A JSON list. */
+export function isList(value: JsonValue | undefined): value is readonly JsonValue[] {
+  return Array.isArray(value);
+}
+
+/** A JSON object, not an array or `null`. */
+export function isObject(value: JsonValue | undefined): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The response's URL without its query, or a fallback when the runtime gives none. */
+function where(response: Response): string {
+  return URL.canParse(response.url) ? shownUrl(new URL(response.url)) : "The server";
+}
+
+/** The message of an error body (`{"error": …}`, `{"detail": …}`), at most 200 characters. */
+function bodyMessage(text: string): string | undefined {
+  const value = parse(text).value;
+  if (!isObject(value)) return undefined;
+  const message = value["error"] ?? value["detail"] ?? value["message"];
+  const shown =
+    typeof message === "string"
+      ? message
+      : isObject(message) && typeof message["message"] === "string"
+        ? message["message"]
+        : undefined;
+  if (shown === undefined) return undefined;
+  // oxlint-disable-next-line no-control-regex -- control characters are what it removes
+  const printable = shown.replaceAll(/[\u0000-\u001f\u007f]/g, " ");
+  return printable.length <= 200 ? printable : `${printable.slice(0, 200)}…`;
+}
+
+/** Why something failed. Node's `fetch` says only "fetch failed"; the reason is in its `cause`. */
+function describe(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const cause: unknown = error instanceof Error ? error.cause : undefined;
+  if (!(cause instanceof Error) || message.includes(cause.message)) return message;
+  return `${message} (${cause.message})`;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @module @tscomfy/client
+ *
+ * Runs tscomfy workflows on a ComfyUI server: `connect` opens a websocket, `submit` queues a
+ * workflow and returns a job whose events stream progress, live previews and outputs, and whose
+ * outcome the server's record of the job decides. `uploadFile` and `fetchFile` move files.
+ * Runtime-agnostic: it uses only `fetch`, `WebSocket` and their companions.
+ */
+
+export { ClientError } from "./client-error.ts";
+export { type Connection, type ConnectOptions, connect } from "./connection.ts";
+export type {
+  BlockedEvent,
+  CachedEvent,
+  ExecutingEvent,
+  JobEvent,
+  OutputEvent,
+  PreviewEvent,
+  ProgressEvent,
+  StartedEvent,
+  TextEvent,
+} from "./events.ts";
+export {
+  type FetchFileOptions,
+  fetchFile,
+  type FileData,
+  fileUrl,
+  type UploadedFile,
+  uploadFile,
+  type UploadOptions,
+  type UploadSource,
+} from "./files.ts";
+export { type Job, type PreviewMethod, submit, type SubmitOptions } from "./job.ts";
+export type {
+  CancelledOutcome,
+  ExecutionError,
+  FailedOutcome,
+  Outcome,
+  RejectedOutcome,
+  SuccessOutcome,
+} from "./outcome.ts";
+export {
+  type FileKind,
+  type FileRef,
+  type FolderType,
+  type NodeOutput,
+  type NodeRef,
+  type OutputFile,
+  outputFiles,
+  outputOf,
+  type Outputs,
+} from "./outputs.ts";
+export type { Server } from "./server.ts";