@vizejs/composable 0.426.3 → 0.427.0

package/dist/until.d.mts

@@ -0,0 +1,177 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/until.d.ts
+/** Options shared by every {@link until} matcher. */
+interface UntilOptions {
+  /**
+   * Reject when the condition is not met within this many milliseconds.
+   * `undefined` waits indefinitely (until the owning scope stops watching).
+   *
+   * @default undefined
+   */
+  readonly timeout?: number;
+  /**
+   * Abort the wait; the promise rejects with the signal's reason.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Watch flush timing. `"sync"` also works during server rendering.
+   *
+   * @default "sync"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+  /**
+   * Watch nested properties of the value.
+   *
+   * @default false
+   */
+  readonly deep?: boolean;
+  /**
+   * Owns the timeout timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Error code carried by the rejection when an {@link until} wait times out. */
+type UntilTimeoutCode = "VIZE_COMPOSE_UNTIL_TIMEOUT";
+/** Rejection reason used when an {@link until} wait times out. */
+interface UntilTimeoutError extends Error {
+  /** Stable machine-readable code. */
+  readonly code: UntilTimeoutCode;
+}
+/** Values treated as falsy by `toBeTruthy`. */
+type UntilFalsy = false | 0 | 0n | "" | null | undefined;
+/** Matchers that wait for the source to satisfy a condition. */
+interface UntilMatchers<Value> {
+  /**
+   * Resolve once the value satisfies the type guard, narrowing the result.
+   *
+   * @returns The narrowed value.
+   */
+  toMatch<Narrowed extends Value>(condition: (value: Value) => value is Narrowed, options?: UntilOptions): Promise<Narrowed>;
+  /**
+   * Resolve once the value satisfies the predicate.
+   *
+   * @returns The matching value.
+   */
+  toMatch(condition: (value: Value) => boolean, options?: UntilOptions): Promise<Value>;
+  /**
+   * Resolve once the value is `Object.is`-equal to `expected` (itself
+   * possibly reactive).
+   *
+   * @returns The expected value.
+   */
+  toBe<const Expected extends Value>(expected: MaybeRefOrGetter<Expected>, options?: UntilOptions): Promise<Expected>;
+  /**
+   * Resolve once the value is truthy.
+   *
+   * @returns The value without its falsy members.
+   */
+  toBeTruthy(options?: UntilOptions): Promise<Exclude<Value, UntilFalsy>>;
+  /**
+   * Resolve once the value is `null`.
+   *
+   * @returns `null`.
+   */
+  toBeNull(options?: UntilOptions): Promise<Extract<Value, null>>;
+  /**
+   * Resolve once the value is `undefined`.
+   *
+   * @returns `undefined`.
+   */
+  toBeUndefined(options?: UntilOptions): Promise<Extract<Value, undefined>>;
+  /**
+   * Resolve once the value is `NaN`.
+   *
+   * @returns `NaN`.
+   */
+  toBeNaN(options?: UntilOptions): Promise<Value>;
+  /**
+   * Resolve once an array or string value includes `element`.
+   *
+   * @returns The containing value.
+   */
+  toContain(element: Value extends readonly (infer Element)[] ? Element : Value extends string ? string : never, options?: UntilOptions): Promise<Value>;
+  /**
+   * Resolve after the value changed once.
+   *
+   * @returns The new value.
+   */
+  changed(options?: UntilOptions): Promise<Value>;
+  /**
+   * Resolve after the value changed `count` times.
+   *
+   * @returns The value after the last counted change.
+   */
+  changedTimes(count: number, options?: UntilOptions): Promise<Value>;
+}
+/** Negated matchers available through {@link UntilChain.not}. */
+interface UntilNegatedMatchers<Value> {
+  /**
+   * Resolve once the value is no longer `Object.is`-equal to `unexpected`.
+   *
+   * @returns The value.
+   */
+  toBe(unexpected: MaybeRefOrGetter<Value>, options?: UntilOptions): Promise<Value>;
+  /**
+   * Resolve once the value is falsy.
+   *
+   * @returns The falsy value.
+   */
+  toBeTruthy(options?: UntilOptions): Promise<Extract<Value, UntilFalsy>>;
+  /**
+   * Resolve once the value is not `null`.
+   *
+   * @returns The value without `null`.
+   */
+  toBeNull(options?: UntilOptions): Promise<Exclude<Value, null>>;
+  /**
+   * Resolve once the value is not `undefined`.
+   *
+   * @returns The value without `undefined`.
+   */
+  toBeUndefined(options?: UntilOptions): Promise<Exclude<Value, undefined>>;
+  /**
+   * Resolve once the value no longer satisfies the predicate.
+   *
+   * @returns The value.
+   */
+  toMatch(condition: (value: Value) => boolean, options?: UntilOptions): Promise<Value>;
+}
+/** Fluent wait builder returned by {@link until}. */
+interface UntilChain<Value> extends UntilMatchers<Value> {
+  /** Inverted matchers. */
+  readonly not: UntilNegatedMatchers<Value>;
+}
+/**
+ * Await a reactive source reaching a condition.
+ *
+ * Every matcher resolves immediately when the current value already
+ * satisfies it (except `changed`/`changedTimes`), and otherwise watches the
+ * source (`flush: "sync"` by default, which also works inside server-side
+ * `setup`). Result types are narrowed by the matcher: `toBeTruthy()` strips
+ * falsy members, `not.toBeNull()` strips `null`, `toMatch(guard)` follows the
+ * guard. Because a timeout rejects (it never resolves with an unmatched
+ * value), the narrowing is always sound. Watchers and timers are released
+ * as soon as the promise settles.
+ *
+ * @example
+ * ```ts
+ * const user = await until(currentUser).not.toBeNull({ timeout: 5_000 });
+ * const ready = await until(status).toBe("ready");
+ * ```
+ *
+ * @param source Ref or getter to observe.
+ * @throws Returned promises reject with an {@link UntilTimeoutError} on
+ * timeout, with the abort reason when the signal aborts, and with a
+ * `RangeError` tagged `VIZE_COMPOSE_UNTIL_INVALID_OPTION` for a negative or
+ * non-finite timeout or change count.
+ * @returns The fluent matcher chain.
+ */
+declare function until<Value>(source: MaybeRefOrGetter<Value>): UntilChain<Value>;
+//#endregion
+export { UntilChain, UntilMatchers, UntilNegatedMatchers, UntilOptions, UntilTimeoutCode, UntilTimeoutError, until };

package/dist/until.mjs

@@ -0,0 +1,111 @@
+import { toValue, watch } from "vue";
+//#region src/until.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function createTimeoutError(timeout) {
+	return Object.assign(/* @__PURE__ */ new Error(`[VIZE_COMPOSE_UNTIL_TIMEOUT] condition not met within ${timeout}ms`), { code: "VIZE_COMPOSE_UNTIL_TIMEOUT" });
+}
+/**
+* Await a reactive source reaching a condition.
+*
+* Every matcher resolves immediately when the current value already
+* satisfies it (except `changed`/`changedTimes`), and otherwise watches the
+* source (`flush: "sync"` by default, which also works inside server-side
+* `setup`). Result types are narrowed by the matcher: `toBeTruthy()` strips
+* falsy members, `not.toBeNull()` strips `null`, `toMatch(guard)` follows the
+* guard. Because a timeout rejects (it never resolves with an unmatched
+* value), the narrowing is always sound. Watchers and timers are released
+* as soon as the promise settles.
+*
+* @example
+* ```ts
+* const user = await until(currentUser).not.toBeNull({ timeout: 5_000 });
+* const ready = await until(status).toBe("ready");
+* ```
+*
+* @param source Ref or getter to observe.
+* @throws Returned promises reject with an {@link UntilTimeoutError} on
+* timeout, with the abort reason when the signal aborts, and with a
+* `RangeError` tagged `VIZE_COMPOSE_UNTIL_INVALID_OPTION` for a negative or
+* non-finite timeout or change count.
+* @returns The fluent matcher chain.
+*/
+function until(source) {
+	const wait = (matches, options, checkInitial = true) => new Promise((resolve, reject) => {
+		const { timeout, signal, scheduler = defaultScheduler } = options;
+		if (timeout !== void 0 && (!Number.isFinite(timeout) || timeout < 0)) {
+			reject(/* @__PURE__ */ new RangeError(`[VIZE_COMPOSE_UNTIL_INVALID_OPTION] timeout must be finite and at least zero; received ${String(timeout)}`));
+			return;
+		}
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		let handle;
+		let timer;
+		let settled = false;
+		const onAbort = () => {
+			finish();
+			reject(signal?.reason);
+		};
+		const finish = () => {
+			settled = true;
+			handle?.stop();
+			if (timer !== void 0) scheduler.clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const accept = (value) => {
+			if (settled || !matches(value)) return;
+			finish();
+			resolve(value);
+		};
+		if (checkInitial) accept(toValue(source));
+		if (settled) return;
+		handle = watch(() => toValue(source), accept, {
+			flush: options.flush ?? "sync",
+			deep: options.deep ?? false
+		});
+		signal?.addEventListener("abort", onAbort, { once: true });
+		if (timeout !== void 0) timer = scheduler.setTimeout(() => {
+			finish();
+			reject(createTimeoutError(timeout));
+		}, timeout);
+	});
+	const any = (_value) => true;
+	const changedTimes = (count, options = {}) => {
+		if (!Number.isSafeInteger(count) || count < 1) return Promise.reject(/* @__PURE__ */ new RangeError(`[VIZE_COMPOSE_UNTIL_INVALID_OPTION] count must be a positive integer; received ${String(count)}`));
+		let seen = 0;
+		return wait((value) => {
+			seen += 1;
+			return seen >= count && any(value);
+		}, options, false);
+	};
+	const includes = (value, element) => Array.isArray(value) ? value.includes(element) : typeof value === "string" && typeof element === "string" && value.includes(element);
+	function toMatch(condition, options = {}) {
+		return wait((value) => condition(value), options);
+	}
+	return {
+		toMatch,
+		toBe: (expected, options = {}) => wait((value) => Object.is(value, toValue(expected)), options),
+		toBeTruthy: (options = {}) => wait((value) => Boolean(value), options),
+		toBeNull: (options = {}) => wait((value) => value === null, options),
+		toBeUndefined: (options = {}) => wait((value) => value === void 0, options),
+		toBeNaN: (options = {}) => wait((value) => Number.isNaN(value), options),
+		toContain: (element, options = {}) => wait((value) => includes(value, element), options),
+		changed: (options = {}) => changedTimes(1, options),
+		changedTimes,
+		not: {
+			toBe: (unexpected, options = {}) => wait((value) => !Object.is(value, toValue(unexpected)), options),
+			toBeTruthy: (options = {}) => wait((value) => !value, options),
+			toBeNull: (options = {}) => wait((value) => value !== null, options),
+			toBeUndefined: (options = {}) => wait((value) => value !== void 0, options),
+			toMatch: (condition, options = {}) => wait((value) => !condition(value), options)
+		}
+	};
+}
+//#endregion
+export { until };

package/dist/use-array.d.mts

@@ -0,0 +1,112 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-array.d.ts
+/** Callback shape shared by the reactive array helpers. */
+type ArrayCallback<Item, Result> = (item: Item, index: number, array: readonly Item[]) => Result;
+/**
+ * Reactive `Array.prototype.filter`. A type-guard predicate narrows the
+ * element type.
+ *
+ * @example
+ * ```ts
+ * const active = useArrayFilter(users, (user) => user.active);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param predicate Keeps items for which it returns `true`.
+ * @returns Computed filtered copy.
+ */
+declare function useArrayFilter<Item, Narrowed extends Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: (item: Item, index: number, array: readonly Item[]) => item is Narrowed): ComputedRef<Narrowed[]>;
+declare function useArrayFilter<Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>): ComputedRef<Item[]>;
+/**
+ * Reactive `Array.prototype.map`.
+ *
+ * @example
+ * ```ts
+ * const names = useArrayMap(users, (user) => user.name);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param mapper Produces the mapped item.
+ * @returns Computed mapped copy.
+ */
+declare function useArrayMap<Item, Mapped>(list: MaybeRefOrGetter<readonly Item[]>, mapper: ArrayCallback<Item, Mapped>): ComputedRef<Mapped[]>;
+/**
+ * Reactive `Array.prototype.find`. A type-guard predicate narrows the
+ * result.
+ *
+ * @example
+ * ```ts
+ * const admin = useArrayFind(users, (user) => user.role === "admin");
+ * ```
+ *
+ * @param list Reactive array.
+ * @param predicate Matches the wanted item.
+ * @returns Computed first match, or `undefined`.
+ */
+declare function useArrayFind<Item, Narrowed extends Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: (item: Item, index: number, array: readonly Item[]) => item is Narrowed): ComputedRef<Narrowed | undefined>;
+declare function useArrayFind<Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>): ComputedRef<Item | undefined>;
+/**
+ * Reactive `Array.prototype.reduce`.
+ *
+ * With an initial value the result has the accumulator type. Without one,
+ * the first item seeds the accumulator and an empty array yields
+ * `undefined` (instead of throwing like `reduce`).
+ *
+ * @example
+ * ```ts
+ * const total = useArrayReduce(cart, (sum, line) => sum + line.price, 0);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param reducer Folds one item into the accumulator.
+ * @param initial Reactive initial accumulator.
+ * @returns Computed accumulated value.
+ */
+declare function useArrayReduce<Item, Accumulator>(list: MaybeRefOrGetter<readonly Item[]>, reducer: (accumulator: Accumulator, item: Item, index: number, array: readonly Item[]) => Accumulator, initial: MaybeRefOrGetter<Accumulator>): ComputedRef<Accumulator>;
+declare function useArrayReduce<Item>(list: MaybeRefOrGetter<readonly Item[]>, reducer: (accumulator: Item, item: Item, index: number, array: readonly Item[]) => Item): ComputedRef<Item | undefined>;
+/**
+ * Reactive `Array.prototype.some`.
+ *
+ * @example
+ * ```ts
+ * const hasErrors = useArraySome(fields, (field) => field.error !== null);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param predicate Condition tested per item.
+ * @returns Computed flag.
+ */
+declare function useArraySome<Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>): ComputedRef<boolean>;
+/**
+ * Reactive `Array.prototype.every`.
+ *
+ * @example
+ * ```ts
+ * const allDone = useArrayEvery(tasks, (task) => task.done);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param predicate Condition tested per item.
+ * @returns Computed flag.
+ */
+declare function useArrayEvery<Item>(list: MaybeRefOrGetter<readonly Item[]>, predicate: ArrayCallback<Item, boolean>): ComputedRef<boolean>;
+/**
+ * Reactive de-duplication that keeps the first occurrence of each item.
+ *
+ * Without `isSame`, items are compared with `SameValueZero` (like `Set`) in
+ * linear time; with it, pairwise in quadratic time.
+ *
+ * @example
+ * ```ts
+ * const tags = useArrayUnique(allTags);
+ * const people = useArrayUnique(rows, (left, right) => left.id === right.id);
+ * ```
+ *
+ * @param list Reactive array.
+ * @param isSame Custom equality.
+ * @returns Computed de-duplicated copy.
+ */
+declare function useArrayUnique<Item>(list: MaybeRefOrGetter<readonly Item[]>, isSame?: (left: Item, right: Item) => boolean): ComputedRef<Item[]>;
+//#endregion
+export { ArrayCallback, useArrayEvery, useArrayFilter, useArrayFind, useArrayMap, useArrayReduce, useArraySome, useArrayUnique };

package/dist/use-array.mjs

@@ -0,0 +1,90 @@
+import { computed, toValue } from "vue";
+//#region src/use-array.ts
+function useArrayFilter(list, predicate) {
+	return computed(() => toValue(list).filter(predicate));
+}
+/**
+* Reactive `Array.prototype.map`.
+*
+* @example
+* ```ts
+* const names = useArrayMap(users, (user) => user.name);
+* ```
+*
+* @param list Reactive array.
+* @param mapper Produces the mapped item.
+* @returns Computed mapped copy.
+*/
+function useArrayMap(list, mapper) {
+	return computed(() => toValue(list).map(mapper));
+}
+function useArrayFind(list, predicate) {
+	return computed(() => toValue(list).find(predicate));
+}
+function useArrayReduce(list, reducer, ...initial) {
+	return computed(() => {
+		const items = toValue(list);
+		const seeded = initial.length === 1;
+		if (!seeded && items.length === 0) return void 0;
+		let accumulator = seeded ? toValue(initial[0]) : items[0];
+		for (const [index, item] of items.entries()) if (seeded || index > 0) accumulator = reducer(accumulator, item, index, items);
+		return accumulator;
+	});
+}
+/**
+* Reactive `Array.prototype.some`.
+*
+* @example
+* ```ts
+* const hasErrors = useArraySome(fields, (field) => field.error !== null);
+* ```
+*
+* @param list Reactive array.
+* @param predicate Condition tested per item.
+* @returns Computed flag.
+*/
+function useArraySome(list, predicate) {
+	return computed(() => toValue(list).some(predicate));
+}
+/**
+* Reactive `Array.prototype.every`.
+*
+* @example
+* ```ts
+* const allDone = useArrayEvery(tasks, (task) => task.done);
+* ```
+*
+* @param list Reactive array.
+* @param predicate Condition tested per item.
+* @returns Computed flag.
+*/
+function useArrayEvery(list, predicate) {
+	return computed(() => toValue(list).every(predicate));
+}
+/**
+* Reactive de-duplication that keeps the first occurrence of each item.
+*
+* Without `isSame`, items are compared with `SameValueZero` (like `Set`) in
+* linear time; with it, pairwise in quadratic time.
+*
+* @example
+* ```ts
+* const tags = useArrayUnique(allTags);
+* const people = useArrayUnique(rows, (left, right) => left.id === right.id);
+* ```
+*
+* @param list Reactive array.
+* @param isSame Custom equality.
+* @returns Computed de-duplicated copy.
+*/
+function useArrayUnique(list, isSame) {
+	return computed(() => {
+		const items = toValue(list);
+		if (isSame === void 0) return [...new Set(items)];
+		const unique = [];
+		for (const item of items) if (!unique.some((kept) => isSame(kept, item))) unique.push(item);
+		return unique;
+	});
+}
+//#endregion
+export { useArrayEvery, useArrayFilter, useArrayFind, useArrayMap, useArrayReduce, useArraySome, useArrayUnique };

package/dist/use-async-queue.d.mts

@@ -0,0 +1,109 @@
+import { ComputedRef, ShallowRef } from "vue";
+
+//#region src/use-async-queue.d.ts
+/** Lifecycle of one queued task. */
+type AsyncQueueTaskState = "pending" | "running" | "fulfilled" | "rejected" | "aborted";
+/** Outcome record of one queued task. */
+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. */
+interface AsyncQueueContext {
+  /** Aborted when the queue is aborted. */
+  readonly signal: AbortSignal;
+}
+/** Result of the task before position `Index` (`undefined` for the first). */
+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. */
+type AsyncQueueTask<Previous, Result> = (previous: Previous, context: AsyncQueueContext) => Result | Promise<Result>;
+/** Task tuple whose parameters chain the previous task's result. */
+type AsyncQueueTasks<Results extends readonly unknown[]> = { readonly [Index in keyof Results]: (previous: AsyncQueuePrevious<Results, Index>, context: AsyncQueueContext) => Results[Index] | Promise<Results[Index]> };
+/** Options for {@link useAsyncQueue}. */
+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}. */
+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.
+ */
+declare function useAsyncQueue<R1>(tasks: readonly [AsyncQueueTask<undefined, R1>], options?: UseAsyncQueueOptions): AsyncQueue<[R1]>;
+declare function useAsyncQueue<R1, R2>(tasks: readonly [AsyncQueueTask<undefined, R1>, AsyncQueueTask<R1, R2>], options?: UseAsyncQueueOptions): AsyncQueue<[R1, R2]>;
+declare function useAsyncQueue<R1, R2, R3>(tasks: readonly [AsyncQueueTask<undefined, R1>, AsyncQueueTask<R1, R2>, AsyncQueueTask<R2, R3>], options?: UseAsyncQueueOptions): AsyncQueue<[R1, R2, R3]>;
+declare 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]>;
+declare 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]>;
+declare 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]>;
+declare function useAsyncQueue<Results extends readonly unknown[]>(tasks: AsyncQueueTasks<Results>, options?: UseAsyncQueueOptions): AsyncQueue<Results>;
+//#endregion
+export { AsyncQueue, AsyncQueueContext, AsyncQueuePrevious, AsyncQueueTask, AsyncQueueTaskResult, AsyncQueueTaskState, AsyncQueueTasks, UseAsyncQueueOptions, useAsyncQueue };

package/dist/use-async-queue.mjs

@@ -0,0 +1,96 @@
+import { computed, shallowRef } from "vue";
+//#region src/use-async-queue.ts
+function useAsyncQueue(tasks, options = {}) {
+	const pendingRecords = () => tasks.map(() => ({
+		state: "pending",
+		data: void 0,
+		error: void 0
+	}));
+	const activeIndex = shallowRef(-1);
+	const results = shallowRef(pendingRecords());
+	const isFinished = computed(() => activeIndex.value >= tasks.length);
+	let controller;
+	const update = (index, record) => {
+		results.value = results.value.map((current, position) => position === index ? record : current);
+	};
+	const abortRemaining = (from) => {
+		results.value = results.value.map((current, position) => position >= from && (current.state === "pending" || current.state === "running") ? {
+			state: "aborted",
+			data: void 0,
+			error: current.error
+		} : current);
+	};
+	const finish = () => {
+		activeIndex.value = tasks.length;
+		options.onFinished?.();
+	};
+	const abortRun = (run, reason) => {
+		if (run.signal.aborted) return;
+		run.abort(reason);
+		if (controller !== run) return;
+		abortRemaining(0);
+		finish();
+	};
+	const run = async () => {
+		controller?.abort();
+		const own = new AbortController();
+		controller = own;
+		results.value = pendingRecords();
+		const external = options.signal;
+		const onExternalAbort = () => abortRun(own, external?.reason);
+		if (external?.aborted === true) {
+			abortRun(own, external.reason);
+			return results.value;
+		}
+		external?.addEventListener("abort", onExternalAbort, { once: true });
+		let previous;
+		try {
+			for (const [index, task] of tasks.entries()) {
+				activeIndex.value = index;
+				update(index, {
+					state: "running",
+					data: void 0,
+					error: void 0
+				});
+				try {
+					previous = await task(previous, { signal: own.signal });
+					if (own.signal.aborted) return results.value;
+					update(index, {
+						state: "fulfilled",
+						data: previous,
+						error: void 0
+					});
+				} catch (error) {
+					if (own.signal.aborted) return results.value;
+					update(index, {
+						state: "rejected",
+						data: void 0,
+						error
+					});
+					options.onError?.(error, index);
+					if (options.interrupt ?? true) {
+						abortRemaining(index + 1);
+						break;
+					}
+					previous = void 0;
+				}
+			}
+			finish();
+			return results.value;
+		} finally {
+			external?.removeEventListener("abort", onExternalAbort);
+		}
+	};
+	if (options.immediate ?? true) run();
+	return {
+		activeIndex,
+		results,
+		isFinished,
+		run,
+		abort: (reason) => {
+			if (controller !== void 0) abortRun(controller, reason);
+		}
+	};
+}
+//#endregion
+export { useAsyncQueue };