@tscomfy/client 0.0.0-stage → 0.2.0

package/src/read-outputs.ts

@@ -0,0 +1,171 @@
+import { isOutputRef, type JsonObject, type JsonValue, type NodeId } from "@tscomfy/core";
+import { isList, isObject } from "./http.ts";
+import type { FileKind, FolderType, NodeOutput, NodeRef, OutputFile, Outputs } from "./outputs.ts";
+
+/** The id of a node given by id, handle or output. */
+export function nodeIdOf(node: NodeRef): NodeId {
+  if (typeof node === "string") return node;
+  if (isOutputRef(node)) return node.node;
+  return node.id;
+}
+
+/** A node's UI output read leniently: anything unrecognized stays in `ui` only. */
+export function readNodeOutput(node: NodeId, ui: JsonObject): NodeOutput {
+  const flags = ui["animated"];
+  const animated = isList(flags) && flags.includes(true);
+  const files: OutputFile[] = [];
+  for (const [key, value] of Object.entries(ui)) {
+    if (!isList(value)) continue;
+    for (const item of value) {
+      const file = readFile(key, item, animated);
+      if (file !== undefined) files.push(file);
+    }
+  }
+  const texts = ui["text"];
+  const text = isList(texts)
+    ? texts.filter((item): item is string => typeof item === "string")
+    : [];
+  return Object.freeze({
+    node,
+    files: Object.freeze(files),
+    text: Object.freeze(text),
+    ui: deepFreeze(ui),
+  });
+}
+
+/** Builds the outputs map, in the order of `order` (the prompt's node order), unknown ids last. */
+export function outputsInOrder(
+  outputs: ReadonlyMap<NodeId, NodeOutput>,
+  order: readonly NodeId[],
+): Outputs {
+  const position = new Map(order.map((id, index) => [id, index]));
+  const sorted = [...outputs.values()].toSorted(
+    (a, b) =>
+      (position.get(a.node) ?? Number.MAX_SAFE_INTEGER) -
+      (position.get(b.node) ?? Number.MAX_SAFE_INTEGER),
+  );
+  return new FrozenMap(sorted.map((output) => [output.node, output]));
+}
+
+/** A map nobody can change: what `outcome.outputs` is. */
+class FrozenMap<K, V> implements ReadonlyMap<K, V> {
+  readonly #map: ReadonlyMap<K, V>;
+
+  constructor(entries: Iterable<readonly [K, V]>) {
+    this.#map = new Map(entries);
+    Object.freeze(this);
+  }
+
+  get size(): number {
+    return this.#map.size;
+  }
+
+  get(key: K): V | undefined {
+    return this.#map.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.#map.has(key);
+  }
+
+  forEach(callback: (value: V, key: K, map: ReadonlyMap<K, V>) => void, thisArg?: unknown): void {
+    for (const [key, value] of this.#map) callback.call(thisArg, value, key, this);
+  }
+
+  entries(): MapIterator<[K, V]> {
+    return this.#map.entries();
+  }
+
+  keys(): MapIterator<K> {
+    return this.#map.keys();
+  }
+
+  values(): MapIterator<V> {
+    return this.#map.values();
+  }
+
+  [Symbol.iterator](): MapIterator<[K, V]> {
+    return this.#map[Symbol.iterator]();
+  }
+}
+
+/** Freezes a JSON value and everything in it. */
+function deepFreeze<T extends JsonValue>(value: T): T {
+  if (typeof value === "object" && value !== null) {
+    for (const item of Object.values(value)) deepFreeze(item);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** One of the server's folder names. */
+export function isFolderType(value: JsonValue | undefined): value is FolderType {
+  return value === "output" || value === "temp" || value === "input";
+}
+
+/** A file entry: `{ filename, subfolder, type }` and maybe `metadata`. */
+function readFile(key: string, item: JsonValue, animated: boolean): OutputFile | undefined {
+  if (!isObject(item)) return undefined;
+  const { filename, subfolder, type } = item;
+  if (typeof filename !== "string" || filename === "") return undefined;
+  if (!isFolderType(type)) return undefined;
+  const metadata = isObject(item["metadata"]) ? item["metadata"] : {};
+  const kind = kindOf(key, filename, metadata["kind"], animated);
+  const file: OutputFile = {
+    filename,
+    subfolder: typeof subfolder === "string" ? subfolder : "",
+    type,
+    kind,
+    animated: animated && (kind === "image" || kind === "video"),
+    key,
+    ...dimension("width", metadata["width"]),
+    ...dimension("height", metadata["height"]),
+  };
+  return Object.freeze(file);
+}
+
+function dimension(
+  name: "width" | "height",
+  value: JsonValue | undefined,
+): { readonly width?: number; readonly height?: number } {
+  return typeof value === "number" && Number.isFinite(value) ? { [name]: value } : {};
+}
+
+const EXTENSIONS: ReadonlyMap<string, FileKind> = new Map([
+  ...["png", "jpg", "jpeg", "webp", "gif", "bmp", "tif", "tiff", "avif", "svg"].map(
+    (extension) => [extension, "image"] as const,
+  ),
+  ...["mp4", "webm", "mov", "mkv", "avi", "m4v"].map((extension) => [extension, "video"] as const),
+  ...["flac", "mp3", "wav", "ogg", "opus", "m4a", "aac"].map(
+    (extension) => [extension, "audio"] as const,
+  ),
+  ...["glb", "gltf", "obj", "fbx", "stl", "ply", "splat", "spz", "usdz"].map(
+    (extension) => [extension, "3d"] as const,
+  ),
+]);
+
+const KEYS: ReadonlyMap<string, FileKind> = new Map([
+  ["images", "image"],
+  ["audio", "audio"],
+  ["3d", "3d"],
+]);
+
+/** The server's own `metadata.kind` first, then the extension, then the key. */
+function kindOf(
+  key: string,
+  filename: string,
+  metadataKind: JsonValue | undefined,
+  animated: boolean,
+): FileKind {
+  if (metadataKind === "image" || metadataKind === "video" || metadataKind === "audio") {
+    return metadataKind;
+  }
+  const dot = filename.lastIndexOf(".");
+  const extension = dot === -1 ? "" : filename.slice(dot + 1).toLowerCase();
+  const byExtension = EXTENSIONS.get(extension);
+  if (byExtension !== undefined) return byExtension;
+  const byKey = KEYS.get(key);
+  // An animated entry with an unknown extension under `images` is a video (core's video nodes).
+  if (byKey === "image" && animated) return "video";
+  return byKey ?? "file";
+}

package/src/server-errors.ts

@@ -0,0 +1,61 @@
+import { createDiagnostic, type Diagnostic, type JsonValue } from "@tscomfy/core";
+import { isList, isObject } from "./http.ts";
+
+/**
+ * The diagnostics of the server's answer to a prompt: its top-level `error` (only on a
+ * rejection) as `E_PROMPT_REJECTED`, then each node error as `E_SERVER_VALIDATION`, by node id.
+ */
+export function serverDiagnostics(
+  error: JsonValue | undefined,
+  nodeErrors: JsonValue | undefined,
+): readonly Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  if (error !== undefined) diagnostics.push(rejection(error));
+  if (isObject(nodeErrors)) {
+    for (const [node, entry] of Object.entries(nodeErrors)) {
+      const listed = isObject(entry) ? entry["errors"] : undefined;
+      const errors = isList(listed) ? listed : [entry];
+      for (const each of errors) {
+        const inputName = isObject(each) ? inputOf(each["extra_info"]) : undefined;
+        diagnostics.push(
+          createDiagnostic(
+            "E_SERVER_VALIDATION",
+            inputName === undefined ? [node] : [node, "inputs", inputName],
+            describe(each),
+          ),
+        );
+      }
+    }
+  }
+  return Object.freeze(diagnostics);
+}
+
+/** The top-level error: at the node it names (an unknown class), else at the prompt. */
+function rejection(error: JsonValue): Diagnostic {
+  const extra = isObject(error) && isObject(error["extra_info"]) ? error["extra_info"] : {};
+  const node = extra["node_id"];
+  return createDiagnostic(
+    "E_PROMPT_REJECTED",
+    typeof node === "string" && node !== "" ? [node] : [],
+    describe(error),
+  );
+}
+
+function inputOf(extra: JsonValue | undefined): string | undefined {
+  const name = isObject(extra) ? extra["input_name"] : undefined;
+  return typeof name === "string" && name !== "" ? name : undefined;
+}
+
+/** `type: message: details`, leaving out the parts the server didn't send. */
+function describe(error: JsonValue): string {
+  if (typeof error === "string") return error;
+  if (!isObject(error)) return "The server reported an error it didn't describe.";
+  const parts = [error["type"], error["message"], error["details"]].filter(
+    (part): part is string => typeof part === "string" && part !== "",
+  );
+  // The server repeats the message as the details for some errors.
+  const unique = parts.filter((part, index) => parts.indexOf(part) === index);
+  return unique.length === 0
+    ? "The server reported an error it didn't describe."
+    : unique.join(": ");
+}

package/src/server.ts

@@ -0,0 +1,29 @@
+/**
+ * A ComfyUI server: where it is and how to talk to it. Plain data; every function that needs no
+ * websocket takes one, and a {@link Connection} is one too.
+ */
+export interface Server {
+  /**
+   * The server's http(s) URL. It may have a path prefix and a query (a token, say), which every
+   * request and the websocket URL keep: `http://host/comfy/?token=t` gives
+   * `http://host/comfy/prompt?token=t`. Credentials (`user:password@`) are refused, because
+   * runtimes disagree on them; send them in `headers`.
+   */
+  readonly url: string;
+  /**
+   * Headers for every HTTP request, such as `Authorization`. Not sent on the websocket
+   * handshake, which browsers can't give headers; see {@link Server.webSocket}.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Replaces the global `fetch`: the global itself, or a function wrapping it (to add a proxy, a
+   * cookie, logging). It is called with a URL and an init.
+   */
+  readonly fetch?: (url: URL, init: RequestInit) => Promise<Response>;
+  /**
+   * Opens the websocket instead of `new WebSocket(url)`. Bun, Node and Deno accept handshake
+   * headers this way: `(url) => new WebSocket(url, { headers })` (not standard, so not in the
+   * types; browsers throw).
+   */
+  readonly webSocket?: (url: string) => WebSocket;
+}

package/src/timers.ts

@@ -0,0 +1,35 @@
+/**
+ * Waits `ms` milliseconds, or less if `signal` aborts; never rejects. Its timer goes with it, so
+ * nothing outlives an abort and keeps a process running.
+ */
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/**
+ * `promise`, or the signal's reason as soon as it aborts. The promise keeps running either way
+ * and is marked handled, so a rejection after the abort goes unreported.
+ */
+export function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return promise;
+  promise.catch(() => undefined);
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const abort = (): void => {
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener("abort", abort);
+    });
+  });
+}

package/src/url.ts

@@ -0,0 +1,41 @@
+import type { Server } from "./server.ts";
+
+/**
+ * The server's base URL, checked. Throws a `TypeError` for a URL that isn't http(s), has
+ * credentials or a fragment. The URL isn't echoed: it may hold a token.
+ */
+export function baseUrl(server: Server): URL {
+  if (typeof server.url !== "string" || !URL.canParse(server.url)) {
+    throw new TypeError("server.url is not a valid URL");
+  }
+  const url = new URL(server.url);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError("server.url must be an http(s) URL");
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new TypeError("server.url can't hold credentials; send them in server.headers");
+  }
+  if (url.hash !== "") {
+    throw new TypeError("server.url can't have a #fragment: it never reaches the server");
+  }
+  return url;
+}
+
+/** An endpoint under the server's path, keeping its query: `http://h/api/?t=1` → `…/api/x?t=1`. */
+export function endpoint(base: URL, path: string, query?: Readonly<Record<string, string>>): URL {
+  const url = new URL(base.href);
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/${path}`;
+  for (const [key, value] of Object.entries(query ?? {})) url.searchParams.set(key, value);
+  return url;
+}
+
+/**
+ * A URL fit for messages: without query or fragment, which is where servers expect tokens.
+ * `http://host/api?token=t` → `http://host/api`.
+ */
+export function shownUrl(url: URL): string {
+  const shown = new URL(url.href);
+  shown.search = "";
+  shown.hash = "";
+  return shown.href;
+}

package/src/uuid.ts

@@ -0,0 +1,12 @@
+/**
+ * A random UUID (version 4) in the canonical lowercase form ComfyUI requires of a prompt id.
+ * Built from `crypto.getRandomValues`, which, unlike `crypto.randomUUID`, browsers also offer on
+ * pages that aren't a secure context (`http://192.168.…`).
+ */
+export function randomUuid(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}