@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/use-async-queue.ts

@@ -0,0 +1,278 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+/** Lifecycle of one queued task. */
+export type AsyncQueueTaskState = "pending" | "running" | "fulfilled" | "rejected" | "aborted";
+
+/** Outcome record of one queued task. */
+export interface AsyncQueueTaskResult<Data> {
+  /** Current lifecycle state. */
+  readonly state: AsyncQueueTaskState;
+
+  /** Resolved value once fulfilled. */
+  readonly data: Data | undefined;
+
+  /** Failure once rejected. */
+  readonly error: unknown;
+}
+
+/** Context passed to every queued task. */
+export interface AsyncQueueContext {
+  /** Aborted when the queue is aborted. */
+  readonly signal: AbortSignal;
+}
+
+/** Result of the task before position `Index` (`undefined` for the first). */
+export type AsyncQueuePrevious<Results extends readonly unknown[], Index> = Index extends keyof [
+  undefined,
+  ...Results,
+]
+  ? [undefined, ...Results][Index]
+  : never;
+
+/** One queued task: receives the previous result and resolves the next. */
+export type AsyncQueueTask<Previous, Result> = (
+  previous: Previous,
+  context: AsyncQueueContext,
+) => Result | Promise<Result>;
+
+/** Task tuple whose parameters chain the previous task's result. */
+export type AsyncQueueTasks<Results extends readonly unknown[]> = {
+  readonly [Index in keyof Results]: (
+    previous: AsyncQueuePrevious<Results, Index>,
+    context: AsyncQueueContext,
+  ) => Results[Index] | Promise<Results[Index]>;
+};
+
+/**
+ * Task with its result chain erased. Declared through a method signature so
+ * its parameters are compared bivariantly: every typed task is assignable.
+ */
+type ErasedTask = {
+  run(previous: unknown, context: AsyncQueueContext): unknown;
+}["run"];
+
+/** Options for {@link useAsyncQueue}. */
+export interface UseAsyncQueueOptions {
+  /**
+   * Stop at the first rejection (remaining tasks become `"aborted"`).
+   *
+   * @default true
+   */
+  readonly interrupt?: boolean;
+
+  /**
+   * Start running right away.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * External cancellation; aborting it aborts the queue.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+
+  /**
+   * Called when a task rejects.
+   *
+   * @default undefined
+   */
+  readonly onError?: (error: unknown, index: number) => void;
+
+  /**
+   * Called once the queue settles.
+   *
+   * @default undefined
+   */
+  readonly onFinished?: () => void;
+}
+
+/** Queue state and controls returned by {@link useAsyncQueue}. */
+export interface AsyncQueue<Results extends readonly unknown[]> {
+  /** Index of the running task (`-1` before start, `length` when done). */
+  readonly activeIndex: Readonly<ShallowRef<number>>;
+
+  /** Per-task outcome records, typed per position. */
+  readonly results: Readonly<
+    ShallowRef<{ readonly [Index in keyof Results]: AsyncQueueTaskResult<Results[Index]> }>
+  >;
+
+  /** Whether the queue settled (all done, interrupted, or aborted). */
+  readonly isFinished: ComputedRef<boolean>;
+
+  /**
+   * Run the queue (again) from the first task.
+   *
+   * @returns Settles with the final records.
+   */
+  readonly run: () => Promise<{
+    readonly [Index in keyof Results]: AsyncQueueTaskResult<Results[Index]>;
+  }>;
+
+  /** Abort the running queue. */
+  readonly abort: (reason?: unknown) => void;
+}
+
+/**
+ * Run async tasks one after another, each receiving the previous result.
+ *
+ * Result types are inferred per position from the task tuple, and each
+ * task's `previous` parameter is contextually typed as the preceding task's
+ * result (up to six tasks; longer queues use the mapped-tuple signature with
+ * annotated parameters).
+ * Every task gets an `AbortSignal`; `abort()` (or the external signal)
+ * stops the queue and marks unfinished tasks `"aborted"`. A new `run()`
+ * aborts the one in flight. Starts on the server too when `immediate`, but
+ * nothing awaits it there, so markup shows the pending state on both sides.
+ *
+ * @example
+ * ```ts
+ * const { results } = useAsyncQueue([
+ *   async () => fetchUser(),
+ *   async (user) => fetchOrders(user.id),
+ * ]);
+ * ```
+ *
+ * @param tasks Ordered task tuple.
+ * @param options Interruption, start, cancellation, and callbacks.
+ * @default options {}
+ * @returns Queue state and controls.
+ */
+export function useAsyncQueue<R1>(
+  tasks: readonly [AsyncQueueTask<undefined, R1>],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1]>;
+export function useAsyncQueue<R1, R2>(
+  tasks: readonly [AsyncQueueTask<undefined, R1>, AsyncQueueTask<R1, R2>],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1, R2]>;
+export function useAsyncQueue<R1, R2, R3>(
+  tasks: readonly [AsyncQueueTask<undefined, R1>, AsyncQueueTask<R1, R2>, AsyncQueueTask<R2, R3>],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1, R2, R3]>;
+export function useAsyncQueue<R1, R2, R3, R4>(
+  tasks: readonly [
+    AsyncQueueTask<undefined, R1>,
+    AsyncQueueTask<R1, R2>,
+    AsyncQueueTask<R2, R3>,
+    AsyncQueueTask<R3, R4>,
+  ],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1, R2, R3, R4]>;
+export function useAsyncQueue<R1, R2, R3, R4, R5>(
+  tasks: readonly [
+    AsyncQueueTask<undefined, R1>,
+    AsyncQueueTask<R1, R2>,
+    AsyncQueueTask<R2, R3>,
+    AsyncQueueTask<R3, R4>,
+    AsyncQueueTask<R4, R5>,
+  ],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1, R2, R3, R4, R5]>;
+export function useAsyncQueue<R1, R2, R3, R4, R5, R6>(
+  tasks: readonly [
+    AsyncQueueTask<undefined, R1>,
+    AsyncQueueTask<R1, R2>,
+    AsyncQueueTask<R2, R3>,
+    AsyncQueueTask<R3, R4>,
+    AsyncQueueTask<R4, R5>,
+    AsyncQueueTask<R5, R6>,
+  ],
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<[R1, R2, R3, R4, R5, R6]>;
+export function useAsyncQueue<Results extends readonly unknown[]>(
+  tasks: AsyncQueueTasks<Results>,
+  options?: UseAsyncQueueOptions,
+): AsyncQueue<Results>;
+export function useAsyncQueue(
+  tasks: readonly ErasedTask[],
+  options: UseAsyncQueueOptions = {},
+): AsyncQueue<readonly unknown[]> {
+  const pendingRecords = (): AsyncQueueTaskResult<unknown>[] =>
+    tasks.map(() => ({ state: "pending", data: undefined, error: undefined }));
+  const activeIndex = shallowRef(-1);
+  const results = shallowRef<readonly AsyncQueueTaskResult<unknown>[]>(pendingRecords());
+  const isFinished = computed(() => activeIndex.value >= tasks.length);
+  let controller: AbortController | undefined;
+
+  const update = (index: number, record: AsyncQueueTaskResult<unknown>): void => {
+    results.value = results.value.map((current, position) =>
+      position === index ? record : current,
+    );
+  };
+  const abortRemaining = (from: number): void => {
+    results.value = results.value.map((current, position) =>
+      position >= from && (current.state === "pending" || current.state === "running")
+        ? { state: "aborted", data: undefined, error: current.error }
+        : current,
+    );
+  };
+
+  const finish = (): void => {
+    activeIndex.value = tasks.length;
+    options.onFinished?.();
+  };
+
+  const abortRun = (run: AbortController, reason?: unknown): void => {
+    if (run.signal.aborted) return;
+    run.abort(reason);
+    if (controller !== run) return;
+    abortRemaining(0);
+    finish();
+  };
+
+  const run = async (): Promise<readonly AsyncQueueTaskResult<unknown>[]> => {
+    controller?.abort();
+    const own = new AbortController();
+    controller = own;
+    results.value = pendingRecords();
+    const external = options.signal;
+    const onExternalAbort = (): void => abortRun(own, external?.reason);
+    if (external?.aborted === true) {
+      abortRun(own, external.reason);
+      return results.value;
+    }
+    external?.addEventListener("abort", onExternalAbort, { once: true });
+
+    let previous: unknown;
+    try {
+      for (const [index, task] of tasks.entries()) {
+        activeIndex.value = index;
+        update(index, { state: "running", data: undefined, error: undefined });
+        try {
+          previous = await task(previous, { signal: own.signal });
+          if (own.signal.aborted) return results.value;
+          update(index, { state: "fulfilled", data: previous, error: undefined });
+        } catch (error) {
+          if (own.signal.aborted) return results.value;
+          update(index, { state: "rejected", data: undefined, error });
+          options.onError?.(error, index);
+          if (options.interrupt ?? true) {
+            abortRemaining(index + 1);
+            break;
+          }
+          previous = undefined;
+        }
+      }
+      finish();
+      return results.value;
+    } finally {
+      external?.removeEventListener("abort", onExternalAbort);
+    }
+  };
+
+  if (options.immediate ?? true) void run();
+
+  return {
+    activeIndex,
+    results,
+    isFinished,
+    run,
+    abort: (reason) => {
+      if (controller !== undefined) abortRun(controller, reason);
+    },
+  };
+}

package/registry/files/use-async-state.ts

@@ -0,0 +1,139 @@
+import { shallowRef } from "vue";
+import type { ShallowRef } from "vue";
+
+/** Options for {@link useAsyncState}. */
+export interface UseAsyncStateOptions<Data> {
+  /**
+   * Execute once right away. Only available for producers without
+   * parameters; pass `false` to run a producer that takes arguments through
+   * {@link AsyncState.execute}.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Restore the initial state at the start of every execution.
+   *
+   * @default false
+   */
+  readonly resetOnExecute?: boolean;
+
+  /**
+   * Re-throw failures from `execute` in addition to storing them.
+   *
+   * @default false
+   */
+  readonly throwError?: boolean;
+
+  /**
+   * Called with every failure of the newest execution.
+   *
+   * @default undefined
+   */
+  readonly onError?: (error: unknown) => void;
+
+  /**
+   * Called with every successful result of the newest execution.
+   *
+   * @default undefined
+   */
+  readonly onSuccess?: (data: Data) => void;
+}
+
+/** Reactive state and controls returned by {@link useAsyncState}. */
+export interface AsyncState<Data, Initial, Parameters extends readonly unknown[]> {
+  /** Newest result, or the initial state. */
+  readonly state: Readonly<ShallowRef<Data | Initial>>;
+
+  /** Whether at least one execution succeeded. */
+  readonly isReady: Readonly<ShallowRef<boolean>>;
+
+  /** Whether an execution is in flight. */
+  readonly isLoading: Readonly<ShallowRef<boolean>>;
+
+  /** Failure of the newest execution, cleared when a new one starts. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+
+  /**
+   * Run the producer. Only the newest execution may update the state.
+   *
+   * @returns The resulting state (the previous state for failed or
+   * superseded executions unless `throwError` is set).
+   */
+  readonly execute: (...args: Parameters) => Promise<Data | Initial>;
+}
+
+/**
+ * Reactive state for an async producer.
+ *
+ * Tracks the result, loading, readiness, and error of the newest execution;
+ * out-of-order completions of older executions are ignored, so the state
+ * always reflects the latest request. The typing is arity-aware: producers
+ * with parameters require `{ immediate: false }` and `execute` keeps their
+ * parameter tuple. On the server an immediate execution starts but is not
+ * awaited, so both sides render the initial state with `isLoading: true`.
+ *
+ * @example
+ * ```ts
+ * const { state, isLoading, execute } = useAsyncState((id: string) => fetchUser(id), null, {
+ *   immediate: false,
+ * });
+ * await execute("u-1");
+ * ```
+ *
+ * @param producer Async function producing the data.
+ * @param initial State before the first success.
+ * @param options Immediate execution, reset, error, and success policy.
+ * @default options {}
+ * @returns Reactive state and the `execute` control.
+ */
+export function useAsyncState<Data, Initial>(
+  producer: () => Promise<Data>,
+  initial: Initial,
+  options?: UseAsyncStateOptions<Data>,
+): AsyncState<Data, Initial, []>;
+export function useAsyncState<Data, Initial, Parameters extends readonly unknown[]>(
+  producer: (...args: Parameters) => Promise<Data>,
+  initial: Initial,
+  options: UseAsyncStateOptions<Data> & { readonly immediate: false },
+): AsyncState<Data, Initial, Parameters>;
+export function useAsyncState(
+  producer: (...args: readonly unknown[]) => Promise<unknown>,
+  initial: unknown,
+  options: UseAsyncStateOptions<unknown> = {},
+): AsyncState<unknown, unknown, readonly unknown[]> {
+  const state = shallowRef(initial);
+  const isReady = shallowRef(false);
+  const isLoading = shallowRef(false);
+  const error = shallowRef<unknown>(undefined);
+  let generation = 0;
+
+  const execute = async (...args: readonly unknown[]): Promise<unknown> => {
+    generation += 1;
+    const own = generation;
+    if (options.resetOnExecute ?? false) state.value = initial;
+    error.value = undefined;
+    isLoading.value = true;
+    try {
+      const data = await producer(...args);
+      if (own !== generation) return state.value;
+      state.value = data;
+      isReady.value = true;
+      options.onSuccess?.(data);
+    } catch (failure) {
+      if (own !== generation) return state.value;
+      error.value = failure;
+      options.onError?.(failure);
+      if (options.throwError ?? false) throw failure;
+    } finally {
+      if (own === generation) isLoading.value = false;
+    }
+    return state.value;
+  };
+
+  // Only the zero-parameter overload may execute immediately.
+  if (options.immediate ?? true) void execute().catch(() => undefined);
+
+  return { state, isReady, isLoading, error, execute };
+}