@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-worker-fn.ts

@@ -0,0 +1,306 @@
+import { readonly, shallowRef, toValue } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Lifecycle status of a {@link useWorkerFn} worker. */
+export type WorkerFnStatus = "idle" | "running" | "success" | "error" | "timeout";
+
+/** Minimal dedicated worker used by {@link useWorkerFn}. */
+export interface WorkerLike {
+  /** Send a structured-clonable message to the worker. */
+  postMessage(message: unknown): void;
+  /** Stop the worker immediately. */
+  terminate(): void;
+  /** Subscribe to `message`, `messageerror`, or `error`. */
+  addEventListener(type: "message" | "messageerror" | "error", listener: EventListener): void;
+  /** Remove a listener registered with `addEventListener`. */
+  removeEventListener(type: "message" | "messageerror" | "error", listener: EventListener): void;
+}
+
+/** Constructor creating {@link WorkerLike} instances from a script URL. */
+export type WorkerConstructorLike = new (url: string) => WorkerLike;
+
+/** Capabilities needed to run a function in a Blob-URL worker. */
+export interface WorkerFnHost {
+  /** Worker constructor (e.g. `Worker`). */
+  readonly Worker: WorkerConstructorLike;
+  /** Create a URL for the generated worker script (e.g. `URL.createObjectURL`). */
+  readonly createObjectURL: (script: Blob) => string;
+  /** Release a URL returned by `createObjectURL`. */
+  readonly revokeObjectURL: (url: string) => void;
+}
+
+/** Stable error codes used in {@link useWorkerFn} rejection messages. */
+export type WorkerFnErrorCode =
+  | "VIZE_COMPOSE_WORKER_FN_UNSUPPORTED"
+  | "VIZE_COMPOSE_WORKER_FN_BUSY"
+  | "VIZE_COMPOSE_WORKER_FN_TIMEOUT"
+  | "VIZE_COMPOSE_WORKER_FN_TERMINATED"
+  | "VIZE_COMPOSE_WORKER_FN_FAILED";
+
+/** Options for {@link useWorkerFn}. */
+export interface UseWorkerFnOptions {
+  /**
+   * Reject and terminate a run after this many milliseconds.
+   *
+   * @default undefined (no timeout)
+   */
+  readonly timeoutMs?: number;
+
+  /**
+   * Absolute script URLs loaded with `importScripts` before the function runs.
+   *
+   * @default []
+   */
+  readonly dependencies?: readonly string[];
+
+  /**
+   * Named standalone functions inlined into the worker so `fn` can call them.
+   *
+   * @default []
+   */
+  readonly localDependencies?: readonly ((...arguments_: never[]) => unknown)[];
+
+  /**
+   * Worker capabilities for alternate runtimes and tests.
+   *
+   * @default window.Worker and window.URL when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<WorkerFnHost | null | undefined>;
+
+  /**
+   * Timer host for `timeoutMs`.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+/** Reactive state and controls returned by {@link useWorkerFn}. */
+export interface WorkerFnControls<Arguments extends readonly unknown[], Result> {
+  /** Lifecycle status of the latest run. */
+  readonly status: Readonly<Ref<WorkerFnStatus>>;
+  /** Whether worker capabilities are available. */
+  readonly supported: Readonly<Ref<boolean>>;
+  /**
+   * Run the function in a fresh worker. Arguments and result must be
+   * structured-clonable. Rejects with a tagged `Error` whose message starts
+   * with a {@link WorkerFnErrorCode}.
+   */
+  readonly run: (...arguments_: Arguments) => Promise<Awaited<Result>>;
+  /** Terminate the running worker, rejecting its pending run. */
+  readonly terminate: () => void;
+}
+
+function browserHost(): WorkerFnHost | undefined {
+  if (typeof window === "undefined" || typeof window.Worker !== "function") return undefined;
+  const { URL: url } = window;
+  return {
+    Worker: window.Worker,
+    createObjectURL: (script) => url.createObjectURL(script),
+    revokeObjectURL: (target) => url.revokeObjectURL(target),
+  };
+}
+
+function defaultScheduler(): TimeoutScheduler {
+  return {
+    setTimeout: (callback, delayMs) => {
+      const handle = globalThis.setTimeout(callback, delayMs);
+      return () => globalThis.clearTimeout(handle);
+    },
+    clearTimeout: (cancel) => {
+      if (typeof cancel === "function") cancel();
+    },
+  };
+}
+
+function workerError(code: WorkerFnErrorCode, message: string, cause?: unknown): Error {
+  return cause === undefined
+    ? new Error(`[${code}] ${message}`)
+    : new Error(`[${code}] ${message}`, { cause });
+}
+
+/**
+ * Build the worker script for `fn`. Exposed for inspection and testing.
+ *
+ * The function source is embedded with `Function.prototype.toString`, so it
+ * must be self-contained: no closures over module variables, only its
+ * arguments, `localDependencies`, `dependencies`, and worker globals.
+ *
+ * @param fn Function to embed.
+ * @param options Imported scripts and inlined helper functions.
+ * @default options {}
+ * @returns JavaScript source for a dedicated worker.
+ */
+export function createWorkerFnScript(
+  fn: (...arguments_: never[]) => unknown,
+  options: Pick<UseWorkerFnOptions, "dependencies" | "localDependencies"> = {},
+): string {
+  const imports = (options.dependencies ?? []).map((url) => JSON.stringify(url)).join(", ");
+  const helpers = (options.localDependencies ?? [])
+    .map((helper) => {
+      if (helper.name === "") {
+        throw new TypeError(
+          "[VIZE_COMPOSE_WORKER_FN_ANONYMOUS_DEPENDENCY] localDependencies must be named functions",
+        );
+      }
+      return `const ${helper.name} = ${helper.toString()};`;
+    })
+    .join("\n");
+  return [
+    imports === "" ? "" : `importScripts(${imports});`,
+    helpers,
+    `const __vizeWorkerFn = (${fn.toString()});`,
+    "self.onmessage = async (event) => {",
+    "  try {",
+    '    self.postMessage(["success", await __vizeWorkerFn(...event.data)]);',
+    "  } catch (error) {",
+    '    self.postMessage(["error", error instanceof Error ? error.message : String(error)]);',
+    "  }",
+    "};",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Run a CPU-heavy function in a dedicated Blob-URL worker, off the main thread.
+ *
+ * Each `run` spawns a fresh worker, posts the arguments, and resolves with the
+ * function's (awaited) result; the worker is terminated and its URL revoked
+ * once the run settles, times out, or is terminated. Concurrent runs reject
+ * with `VIZE_COMPOSE_WORKER_FN_BUSY`. The running worker is terminated when
+ * the owning reactive scope stops. Server rendering never spawns workers:
+ * `supported` is `false` and `run` rejects with
+ * `VIZE_COMPOSE_WORKER_FN_UNSUPPORTED`.
+ *
+ * @example
+ * ```ts
+ * const { run, status } = useWorkerFn((values: number[]) =>
+ *   [...values].sort((a, b) => a - b),
+ * );
+ * const sorted = await run(bigArray);
+ * ```
+ *
+ * @param fn Self-contained function; see {@link createWorkerFnScript}.
+ * @param options Timeout, dependencies, host, and scheduler.
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_WORKER_FN_INVALID_TIMEOUT]` for an invalid timeout.
+ * @returns Reactive status and run controls.
+ */
+export function useWorkerFn<Arguments extends readonly unknown[], Result>(
+  fn: (...arguments_: Arguments) => Result,
+  options: UseWorkerFnOptions = {},
+): WorkerFnControls<Arguments, Result> {
+  const { timeoutMs } = options;
+  if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_WORKER_FN_INVALID_TIMEOUT] timeoutMs must be a finite non-negative number; received ${String(timeoutMs)}`,
+    );
+  }
+  const status = shallowRef<WorkerFnStatus>("idle");
+  const resolveHost = (): WorkerFnHost | undefined =>
+    options.host === undefined ? browserHost() : (toValue(options.host) ?? undefined);
+  const supported = shallowRef(resolveHost() !== undefined);
+  const scheduler = options.scheduler ?? defaultScheduler();
+  let cancelActive: ((error: Error, next: WorkerFnStatus) => void) | undefined;
+
+  const run = (...arguments_: Arguments): Promise<Awaited<Result>> => {
+    const host = resolveHost();
+    supported.value = host !== undefined;
+    if (host === undefined) {
+      return Promise.reject(
+        workerError("VIZE_COMPOSE_WORKER_FN_UNSUPPORTED", "workers are not available"),
+      );
+    }
+    if (cancelActive !== undefined) {
+      return Promise.reject(
+        workerError("VIZE_COMPOSE_WORKER_FN_BUSY", "a run is already in progress"),
+      );
+    }
+    const script = createWorkerFnScript(fn, options);
+    const url = host.createObjectURL(new Blob([script], { type: "text/javascript" }));
+    let worker: WorkerLike;
+    try {
+      worker = new host.Worker(url);
+    } catch (cause) {
+      host.revokeObjectURL(url);
+      status.value = "error";
+      return Promise.reject(
+        workerError("VIZE_COMPOSE_WORKER_FN_FAILED", "the worker could not start", cause),
+      );
+    }
+    status.value = "running";
+
+    return new Promise<Awaited<Result>>((resolve, reject) => {
+      let timer: unknown;
+      const cleanup = (): void => {
+        cancelActive = undefined;
+        if (timer !== undefined) scheduler.clearTimeout(timer);
+        worker.removeEventListener("message", onMessage);
+        worker.removeEventListener("messageerror", onFailure);
+        worker.removeEventListener("error", onFailure);
+        worker.terminate();
+        host.revokeObjectURL(url);
+      };
+      const settleError = (error: Error, next: WorkerFnStatus): void => {
+        cleanup();
+        status.value = next;
+        reject(error);
+      };
+      const onMessage: EventListener = (event) => {
+        const payload: unknown = "data" in event ? event.data : undefined;
+        if (!Array.isArray(payload) || payload.length !== 2) return;
+        const [kind, value]: readonly unknown[] = payload;
+        if (kind === "success") {
+          cleanup();
+          status.value = "success";
+          resolve(workerResult<Result>(value));
+        } else {
+          settleError(workerError("VIZE_COMPOSE_WORKER_FN_FAILED", String(value)), "error");
+        }
+      };
+      const onFailure: EventListener = (event) => {
+        const message =
+          "message" in event && typeof event.message === "string" ? event.message : event.type;
+        settleError(workerError("VIZE_COMPOSE_WORKER_FN_FAILED", message, event), "error");
+      };
+      cancelActive = settleError;
+      worker.addEventListener("message", onMessage);
+      worker.addEventListener("messageerror", onFailure);
+      worker.addEventListener("error", onFailure);
+      if (timeoutMs !== undefined) {
+        timer = scheduler.setTimeout(() => {
+          timer = undefined;
+          settleError(
+            workerError(
+              "VIZE_COMPOSE_WORKER_FN_TIMEOUT",
+              `the run exceeded ${String(timeoutMs)} ms`,
+            ),
+            "timeout",
+          );
+        }, timeoutMs);
+      }
+      worker.postMessage(arguments_);
+    });
+  };
+
+  const terminate = (): void => {
+    cancelActive?.(
+      workerError("VIZE_COMPOSE_WORKER_FN_TERMINATED", "the worker was terminated"),
+      "idle",
+    );
+  };
+
+  tryOnScopeDispose(terminate);
+
+  return { status: readonly(status), supported: readonly(supported), run, terminate };
+}
+
+function workerResult<Result>(value: unknown): Awaited<Result> {
+  // The worker executes `fn` itself and posts back its awaited return value
+  // through structured cloning; the type cannot be re-checked at runtime.
+  return value as Awaited<Result>;
+}

package/registry/files/virtual-list.ts

@@ -0,0 +1,230 @@
+import { computed, shallowRef, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useElementRef } from "./element-ref.ts";
+import type { ElementRefSetter } from "./element-ref.ts";
+import { useResizeObserver } from "./resize-observer.ts";
+import type { ResizeObserverHost } from "./resize-observer.ts";
+
+/** Item size: a fixed size in CSS pixels or a per-item function. */
+export type VirtualItemSize<Item> = number | ((index: number, item: Item) => number);
+
+/** Scroll axis of {@link useVirtualList}. */
+export type VirtualListOrientation = "vertical" | "horizontal";
+
+/** Options for {@link useVirtualList}. */
+export interface UseVirtualListOptions<Item> {
+  /** Item size along the scroll axis. */
+  readonly itemSize: VirtualItemSize<Item>;
+
+  /**
+   * Extra items rendered before and after the visible range.
+   *
+   * @default 5
+   */
+  readonly overscan?: number;
+
+  /**
+   * Scroll axis.
+   *
+   * @default "vertical"
+   */
+  readonly orientation?: VirtualListOrientation;
+
+  /**
+   * Items rendered before the container is measured (every server render).
+   * Keeps SSR output deterministic and non-empty for crawlers.
+   *
+   * @default 10
+   */
+  readonly initialItemCount?: number;
+
+  /**
+   * Resize-observer capability used to measure the container.
+   *
+   * @default globalThis when it provides `ResizeObserver`
+   */
+  readonly host?: MaybeRefOrGetter<ResizeObserverHost | null | undefined>;
+}
+
+/** One rendered row/column of {@link useVirtualList}. */
+export interface VirtualListItem<Item> {
+  /** Source item. */
+  readonly data: Item;
+  /** Index in the source list. */
+  readonly index: number;
+  /** Start offset along the scroll axis. */
+  readonly offset: number;
+  /** Size along the scroll axis. */
+  readonly size: number;
+}
+
+/** Inline style for the scroll container. */
+export interface VirtualContainerStyle {
+  /** Vertical overflow. */
+  readonly overflowY: "auto" | "hidden";
+  /** Horizontal overflow. */
+  readonly overflowX: "auto" | "hidden";
+}
+
+/** Inline style for the inner wrapper that holds the rendered items. */
+export interface VirtualWrapperStyle {
+  /** Wrapper width. */
+  readonly width: string;
+  /** Wrapper height. */
+  readonly height: string;
+  /** Leading offset (`margin-top` or `margin-left`). */
+  readonly marginTop: string;
+  /** Leading offset for horizontal lists. */
+  readonly marginLeft: string;
+  /** Horizontal lists lay items out in a row. */
+  readonly display: "block" | "flex";
+}
+
+/** State and bindings returned by {@link useVirtualList}. */
+export interface VirtualListControls<Item> {
+  /** Items to render. */
+  readonly list: ComputedRef<readonly VirtualListItem<Item>[]>;
+  /** Total content size along the scroll axis. */
+  readonly totalSize: ComputedRef<number>;
+  /** Bind on the scroll container: `v-bind="containerProps"`. */
+  readonly containerProps: {
+    readonly ref: ElementRefSetter;
+    readonly onScroll: () => void;
+    readonly style: VirtualContainerStyle;
+  };
+  /** Bind on the inner wrapper: `v-bind="wrapperProps"`. */
+  readonly wrapperProps: ComputedRef<{ readonly style: VirtualWrapperStyle }>;
+  /** Scroll so that the item at `index` starts at the container edge. */
+  readonly scrollTo: (index: number) => void;
+}
+
+interface ScrollableElement extends Element {
+  scrollTop: number;
+  scrollLeft: number;
+  readonly clientHeight: number;
+  readonly clientWidth: number;
+}
+
+/**
+ * Render only the visible slice of a long list (fixed or variable item sizes).
+ *
+ * Offsets are prefix sums recomputed when the items change; the visible range
+ * is found by binary search, so scrolling is O(log n). Until the container is
+ * measured (always on the server) the first `initialItemCount` items render,
+ * so server and first client render match. The container is measured on
+ * scroll and via `ResizeObserver`, released with the owning reactive scope.
+ *
+ * @param items Reactive source list.
+ * @param options Item size, overscan, axis, initial count, and capability.
+ * @returns Items to render plus container/wrapper bindings.
+ */
+export function useVirtualList<Item>(
+  items: MaybeRefOrGetter<readonly Item[]>,
+  options: UseVirtualListOptions<Item>,
+): VirtualListControls<Item> {
+  const overscan = Math.max(0, Math.floor(options.overscan ?? 5));
+  const vertical = (options.orientation ?? "vertical") === "vertical";
+  const initialCount = Math.max(0, Math.floor(options.initialItemCount ?? 10));
+  const { element: container, setRef } = useElementRef();
+  const viewport = shallowRef<number | null>(null);
+  const scrollOffset = shallowRef(0);
+
+  const layout = computed(() => {
+    const source = toValue(items);
+    const offsets = new Float64Array(source.length + 1);
+    const size = options.itemSize;
+    for (const [index, item] of source.entries()) {
+      const next = typeof size === "number" ? size : size(index, item);
+      offsets[index + 1] = (offsets[index] ?? 0) + Math.max(0, next);
+    }
+    return { source, offsets };
+  });
+  const totalSize = computed(() => layout.value.offsets[layout.value.source.length] ?? 0);
+
+  const measure = (): void => {
+    const element = container.value;
+    if (!element || !isScrollable(element)) return;
+    viewport.value = vertical ? element.clientHeight : element.clientWidth;
+    scrollOffset.value = vertical ? element.scrollTop : element.scrollLeft;
+  };
+  useResizeObserver(
+    container,
+    measure,
+    options.host === undefined ? { flush: "sync" } : { host: options.host, flush: "sync" },
+  );
+
+  const range = computed(() => {
+    const { source, offsets } = layout.value;
+    if (viewport.value === null) return { start: 0, end: Math.min(source.length, initialCount) };
+    const first = findIndex(offsets, source.length, scrollOffset.value);
+    const last = findIndex(offsets, source.length, scrollOffset.value + viewport.value);
+    return {
+      start: Math.max(0, first - overscan),
+      end: Math.min(source.length, last + 1 + overscan),
+    };
+  });
+
+  const list = computed<readonly VirtualListItem<Item>[]>(() => {
+    const { source, offsets } = layout.value;
+    const { start, end } = range.value;
+    return source.slice(start, end).map((data, position) => {
+      const index = start + position;
+      const offset = offsets[index] ?? 0;
+      return { data, index, offset, size: (offsets[index + 1] ?? offset) - offset };
+    });
+  });
+
+  const wrapperProps = computed(() => {
+    const leading = layout.value.offsets[range.value.start] ?? 0;
+    const remaining = `${totalSize.value - leading}px`;
+    return {
+      style: {
+        width: vertical ? "100%" : remaining,
+        height: vertical ? remaining : "100%",
+        marginTop: vertical ? `${leading}px` : "0px",
+        marginLeft: vertical ? "0px" : `${leading}px`,
+        display: vertical ? ("block" as const) : ("flex" as const),
+      },
+    };
+  });
+
+  return {
+    list,
+    totalSize,
+    containerProps: {
+      ref: setRef,
+      onScroll: measure,
+      style: vertical
+        ? { overflowY: "auto", overflowX: "hidden" }
+        : { overflowY: "hidden", overflowX: "auto" },
+    },
+    wrapperProps,
+    scrollTo: (index) => {
+      const element = container.value;
+      if (!element || !isScrollable(element)) return;
+      const { offsets, source } = layout.value;
+      const clamped = Math.min(Math.max(0, Math.floor(index)), source.length);
+      const offset = offsets[clamped] ?? 0;
+      if (vertical) element.scrollTop = offset;
+      else element.scrollLeft = offset;
+      measure();
+    },
+  };
+}
+
+/** Largest index whose start offset is ≤ `position`. */
+function findIndex(offsets: Float64Array, count: number, position: number): number {
+  let low = 0;
+  let high = Math.max(0, count - 1);
+  while (low < high) {
+    const middle = (low + high + 1) >> 1;
+    if ((offsets[middle] ?? 0) <= position) low = middle;
+    else high = middle - 1;
+  }
+  return low;
+}
+
+function isScrollable(element: Element): element is ScrollableElement {
+  return "scrollTop" in element && "clientHeight" in element;
+}