@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-worker-fn.mjs

@@ -0,0 +1,162 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { readonly, shallowRef, toValue } from "vue";
+//#region src/use-worker-fn.ts
+function browserHost() {
+	if (typeof window === "undefined" || typeof window.Worker !== "function") return void 0;
+	const { URL: url } = window;
+	return {
+		Worker: window.Worker,
+		createObjectURL: (script) => url.createObjectURL(script),
+		revokeObjectURL: (target) => url.revokeObjectURL(target)
+	};
+}
+function defaultScheduler() {
+	return {
+		setTimeout: (callback, delayMs) => {
+			const handle = globalThis.setTimeout(callback, delayMs);
+			return () => globalThis.clearTimeout(handle);
+		},
+		clearTimeout: (cancel) => {
+			if (typeof cancel === "function") cancel();
+		}
+	};
+}
+function workerError(code, message, cause) {
+	return cause === void 0 ? /* @__PURE__ */ 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.
+*/
+function createWorkerFnScript(fn, options = {}) {
+	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.
+*/
+function useWorkerFn(fn, options = {}) {
+	const { timeoutMs } = options;
+	if (timeoutMs !== void 0 && (!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("idle");
+	const resolveHost = () => options.host === void 0 ? browserHost() : toValue(options.host) ?? void 0;
+	const supported = shallowRef(resolveHost() !== void 0);
+	const scheduler = options.scheduler ?? defaultScheduler();
+	let cancelActive;
+	const run = (...arguments_) => {
+		const host = resolveHost();
+		supported.value = host !== void 0;
+		if (host === void 0) return Promise.reject(workerError("VIZE_COMPOSE_WORKER_FN_UNSUPPORTED", "workers are not available"));
+		if (cancelActive !== void 0) 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;
+		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((resolve, reject) => {
+			let timer;
+			const cleanup = () => {
+				cancelActive = void 0;
+				if (timer !== void 0) scheduler.clearTimeout(timer);
+				worker.removeEventListener("message", onMessage);
+				worker.removeEventListener("messageerror", onFailure);
+				worker.removeEventListener("error", onFailure);
+				worker.terminate();
+				host.revokeObjectURL(url);
+			};
+			const settleError = (error, next) => {
+				cleanup();
+				status.value = next;
+				reject(error);
+			};
+			const onMessage = (event) => {
+				const payload = "data" in event ? event.data : void 0;
+				if (!Array.isArray(payload) || payload.length !== 2) return;
+				const [kind, value] = payload;
+				if (kind === "success") {
+					cleanup();
+					status.value = "success";
+					resolve(workerResult(value));
+				} else settleError(workerError("VIZE_COMPOSE_WORKER_FN_FAILED", String(value)), "error");
+			};
+			const onFailure = (event) => {
+				settleError(workerError("VIZE_COMPOSE_WORKER_FN_FAILED", "message" in event && typeof event.message === "string" ? event.message : event.type, event), "error");
+			};
+			cancelActive = settleError;
+			worker.addEventListener("message", onMessage);
+			worker.addEventListener("messageerror", onFailure);
+			worker.addEventListener("error", onFailure);
+			if (timeoutMs !== void 0) timer = scheduler.setTimeout(() => {
+				timer = void 0;
+				settleError(workerError("VIZE_COMPOSE_WORKER_FN_TIMEOUT", `the run exceeded ${String(timeoutMs)} ms`), "timeout");
+			}, timeoutMs);
+			worker.postMessage(arguments_);
+		});
+	};
+	const terminate = () => {
+		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(value) {
+	return value;
+}
+//#endregion
+export { createWorkerFnScript, useWorkerFn };

package/dist/virtual-list.d.mts

@@ -0,0 +1,105 @@
+import { ResizeObserverHost } from "./resize-observer.mjs";
+import { ElementRefSetter } from "./element-ref.mjs";
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/virtual-list.d.ts
+/** Item size: a fixed size in CSS pixels or a per-item function. */
+type VirtualItemSize<Item> = number | ((index: number, item: Item) => number);
+/** Scroll axis of {@link useVirtualList}. */
+type VirtualListOrientation = "vertical" | "horizontal";
+/** Options for {@link useVirtualList}. */
+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}. */
+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. */
+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. */
+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}. */
+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;
+}
+/**
+ * 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.
+ */
+declare function useVirtualList<Item>(items: MaybeRefOrGetter<readonly Item[]>, options: UseVirtualListOptions<Item>): VirtualListControls<Item>;
+//#endregion
+export { UseVirtualListOptions, VirtualContainerStyle, VirtualItemSize, VirtualListControls, VirtualListItem, VirtualListOrientation, VirtualWrapperStyle, useVirtualList };

package/dist/virtual-list.mjs

@@ -0,0 +1,128 @@
+import { useResizeObserver } from "./resize-observer.mjs";
+import { useElementRef } from "./element-ref.mjs";
+import { computed, shallowRef, toValue } from "vue";
+//#region src/virtual-list.ts
+/**
+* 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.
+*/
+function useVirtualList(items, options) {
+	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(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 = () => {
+		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 === void 0 ? { 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(() => {
+		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" : "flex"
+		} };
+	});
+	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 offset = offsets[Math.min(Math.max(0, Math.floor(index)), source.length)] ?? 0;
+			if (vertical) element.scrollTop = offset;
+			else element.scrollLeft = offset;
+			measure();
+		}
+	};
+}
+/** Largest index whose start offset is ≤ `position`. */
+function findIndex(offsets, count, position) {
+	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) {
+	return "scrollTop" in element && "clientHeight" in element;
+}
+//#endregion
+export { useVirtualList };

package/dist/watch-debounced.d.mts

@@ -0,0 +1,84 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { WatchHelperCallback, WatchSources } from "./watch-source.mjs";
+import { MaybeRefOrGetter, WatchOptions } from "vue";
+
+//#region src/watch-debounced.d.ts
+/** Options for {@link watchDebounced}. */
+interface WatchDebouncedOptions<Immediate extends boolean = false> extends WatchOptions<Immediate> {
+  /**
+   * Quiet period in milliseconds after the last change before the callback
+   * runs. Reactive; read whenever a call is scheduled.
+   *
+   * @default 0
+   */
+  readonly debounce?: MaybeRefOrGetter<number>;
+  /**
+   * Longest time a call may be postponed by continuous changes. When it
+   * elapses, the newest pending call runs even if changes keep coming.
+   *
+   * @default undefined (no ceiling)
+   */
+  readonly maxWait?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * Applies the timing policy when no browser `window` is available. When
+   * disabled, the callback runs synchronously on the server.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the single-shot timers.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Stop handle plus timing controls returned by the debounced/throttled watchers. */
+interface TimedWatchHandle {
+  /** Stop watching and discard any pending call. */
+  readonly stop: () => void;
+  /**
+   * Run the pending call now instead of waiting.
+   *
+   * @returns Whether a pending call was run.
+   */
+  readonly flush: () => boolean;
+  /**
+   * Discard the pending call; later changes schedule again.
+   *
+   * @returns Whether a pending call was discarded.
+   */
+  readonly cancel: () => boolean;
+}
+/**
+ * Watch sources like Vue's `watch`, but run the callback only after the
+ * sources stayed quiet for `debounce` milliseconds.
+ *
+ * The callback receives the newest value together with the old value from
+ * before the first change of the burst, so it always describes the whole
+ * settled transition. `onCleanup` registered by a callback runs before the
+ * next call, as with `watch`. `maxWait` bounds starvation under continuous
+ * changes. Source typing mirrors `watch`, including tuples and the
+ * `immediate` flag (an immediate first call is debounced too).
+ *
+ * Without a browser `window` (and without `runOnServer`) the callback runs
+ * synchronously, so server-side effects are not silently dropped. Timers are
+ * cleared when the watcher stops or the owning scope is disposed.
+ *
+ * @example
+ * ```ts
+ * watchDebounced(query, (value) => search(value), { debounce: 300, maxWait: 1_000 });
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Debounced watch callback.
+ * @param options Watch options plus the debounce policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_WATCH_DEBOUNCED_INVALID_DELAY`
+ * when `debounce` or `maxWait` resolve to a negative or non-finite value,
+ * synchronously at creation and whenever a call is scheduled.
+ * @returns Stop, flush, and cancel controls.
+ */
+declare function watchDebounced<const Sources extends WatchSources, Immediate extends Readonly<boolean> = false>(source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchDebouncedOptions<Immediate>): TimedWatchHandle;
+//#endregion
+export { TimedWatchHandle, WatchDebouncedOptions, watchDebounced };

package/dist/watch-debounced.mjs

@@ -0,0 +1,84 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { toValue, watch } from "vue";
+//#region src/watch-debounced.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function resolveMs(value, name) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_WATCH_DEBOUNCED_INVALID_DELAY] ${name} must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+function watchDebounced(source, callback, options = {}) {
+	const { debounce = 0, maxWait, runOnServer = false, scheduler = defaultScheduler, ...watchOptions } = options;
+	resolveMs(toValue(debounce), "debounce");
+	const initialMaxWait = toValue(maxWait);
+	if (initialMaxWait !== void 0) resolveMs(initialMaxWait, "maxWait");
+	let timer;
+	let maxTimer;
+	let pending;
+	let burstOld;
+	let cleanup;
+	const clearTimers = () => {
+		if (timer !== void 0) scheduler.clearTimeout(timer);
+		if (maxTimer !== void 0) scheduler.clearTimeout(maxTimer);
+		timer = void 0;
+		maxTimer = void 0;
+	};
+	const invoke = (value, oldValue) => {
+		const runCleanup = cleanup;
+		cleanup = void 0;
+		runCleanup?.();
+		const onCleanup = (fn) => {
+			cleanup = fn;
+		};
+		callback(value, oldValue, onCleanup);
+	};
+	const flush = () => {
+		const run = pending;
+		if (run === void 0) return false;
+		clearTimers();
+		pending = void 0;
+		run();
+		return true;
+	};
+	const cancel = () => {
+		if (pending === void 0) return false;
+		clearTimers();
+		pending = void 0;
+		return true;
+	};
+	const handle = watch(source, (value, oldValue) => {
+		if (typeof window === "undefined" && !runOnServer) {
+			invoke(value, oldValue);
+			return;
+		}
+		if (pending === void 0) burstOld = oldValue;
+		const settledOld = burstOld;
+		pending = () => {
+			invoke(value, settledOld);
+		};
+		const delay = resolveMs(toValue(debounce), "debounce");
+		if (timer !== void 0) scheduler.clearTimeout(timer);
+		timer = scheduler.setTimeout(flush, delay);
+		const ceiling = toValue(maxWait);
+		if (ceiling !== void 0 && maxTimer === void 0) maxTimer = scheduler.setTimeout(flush, resolveMs(ceiling, "maxWait"));
+	}, watchOptions);
+	const stop = () => {
+		handle.stop();
+		cancel();
+		const runCleanup = cleanup;
+		cleanup = void 0;
+		runCleanup?.();
+	};
+	tryOnScopeDispose(stop);
+	return {
+		stop,
+		flush,
+		cancel
+	};
+}
+//#endregion
+export { watchDebounced };

package/dist/watch-ignorable.d.mts

@@ -0,0 +1,47 @@
+import { WatchHelperCallback, WatchSources } from "./watch-source.mjs";
+import { WatchOptions } from "vue";
+
+//#region src/watch-ignorable.d.ts
+/** Controls returned by {@link watchIgnorable}. */
+interface IgnorableWatchHandle {
+  /**
+   * Run `updater` so that the source changes it makes synchronously do not
+   * trigger the callback.
+   */
+  readonly ignoreUpdates: (updater: () => void) => void;
+  /**
+   * Swallow the changes already queued for the next (non-sync) flush. A
+   * no-op for `flush: "sync"` watchers, which have nothing queued.
+   */
+  readonly ignorePrevAsyncUpdates: () => void;
+  /** Stop watching permanently. */
+  readonly stop: () => void;
+}
+/**
+ * Watch sources like Vue's `watch`, with a way to make changes the callback
+ * should not see.
+ *
+ * Typical use is two-way syncing: writes performed inside `ignoreUpdates`
+ * (for example applying a server echo) do not bounce back. Works with every
+ * `flush` mode: for `"pre"`/`"post"`, a synchronous side watcher counts
+ * changes so that a batch made only of ignored writes is skipped, while a
+ * batch that mixes ignored and regular writes is still delivered. Stops
+ * with the owning reactive scope; safe during server rendering.
+ *
+ * @example
+ * ```ts
+ * const { ignoreUpdates } = watchIgnorable(draft, (value) => save(value));
+ * ignoreUpdates(() => {
+ *   draft.value = fromServer; // not saved again
+ * });
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Watch callback for non-ignored changes.
+ * @param options Vue watch options.
+ * @default options {}
+ * @returns Ignore helpers and the stop handle.
+ */
+declare function watchIgnorable<const Sources extends WatchSources, Immediate extends Readonly<boolean> = false>(source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchOptions<Immediate>): IgnorableWatchHandle;
+//#endregion
+export { IgnorableWatchHandle, watchIgnorable };

package/dist/watch-ignorable.mjs

@@ -0,0 +1,61 @@
+import { watch } from "vue";
+//#region src/watch-ignorable.ts
+function watchIgnorable(source, callback, options = {}) {
+	if (options.flush === "sync") {
+		let ignoring = false;
+		const handle = watch(source, (value, oldValue, onCleanup) => {
+			if (!ignoring) callback(value, oldValue, onCleanup);
+		}, options);
+		return {
+			ignoreUpdates: (updater) => {
+				const previous = ignoring;
+				ignoring = true;
+				try {
+					updater();
+				} finally {
+					ignoring = previous;
+				}
+			},
+			ignorePrevAsyncUpdates: () => void 0,
+			stop: () => {
+				handle.stop();
+			}
+		};
+	}
+	let ignoredCount = 0;
+	let changeCount = 0;
+	const counter = watch(source, () => {
+		changeCount += 1;
+	}, {
+		...options,
+		flush: "sync",
+		immediate: false,
+		once: false
+	});
+	const handle = watch(source, (value, oldValue, onCleanup) => {
+		const ignore = ignoredCount > 0 && ignoredCount === changeCount;
+		ignoredCount = 0;
+		changeCount = 0;
+		if (options.once === true) counter.stop();
+		if (!ignore) callback(value, oldValue, onCleanup);
+	}, options);
+	return {
+		ignoreUpdates: (updater) => {
+			const before = changeCount;
+			try {
+				updater();
+			} finally {
+				ignoredCount += changeCount - before;
+			}
+		},
+		ignorePrevAsyncUpdates: () => {
+			ignoredCount = changeCount;
+		},
+		stop: () => {
+			counter.stop();
+			handle.stop();
+		}
+	};
+}
+//#endregion
+export { watchIgnorable };