@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/watch-debounced.ts

@@ -0,0 +1,206 @@
+import { toValue, watch } from "vue";
+import type { MaybeRefOrGetter, WatchCallback, WatchHandle, WatchOptions } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+import type { WatchCleanupRegistrar, WatchHelperCallback, WatchSources } from "./watch-source.ts";
+
+/** Options for {@link watchDebounced}. */
+export 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. */
+export 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;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+function resolveMs(value: number, name: string): number {
+  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);
+}
+
+/**
+ * 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.
+ */
+export function watchDebounced<
+  const Sources extends WatchSources,
+  Immediate extends Readonly<boolean> = false,
+>(
+  source: Sources,
+  callback: WatchHelperCallback<Sources, Immediate>,
+  options?: WatchDebouncedOptions<Immediate>,
+): TimedWatchHandle;
+export function watchDebounced(
+  source: WatchSources,
+  callback: WatchCallback<unknown, unknown>,
+  options: WatchDebouncedOptions<boolean> = {},
+): TimedWatchHandle {
+  const {
+    debounce = 0,
+    maxWait,
+    runOnServer = false,
+    scheduler = defaultScheduler,
+    ...watchOptions
+  } = options;
+  resolveMs(toValue(debounce), "debounce");
+  const initialMaxWait = toValue(maxWait);
+  if (initialMaxWait !== undefined) resolveMs(initialMaxWait, "maxWait");
+
+  let timer: unknown;
+  let maxTimer: unknown;
+  let pending: (() => void) | undefined;
+  let burstOld: unknown;
+  let cleanup: (() => void) | undefined;
+
+  const clearTimers = (): void => {
+    if (timer !== undefined) scheduler.clearTimeout(timer);
+    if (maxTimer !== undefined) scheduler.clearTimeout(maxTimer);
+    timer = undefined;
+    maxTimer = undefined;
+  };
+
+  const invoke = (value: unknown, oldValue: unknown): void => {
+    const runCleanup = cleanup;
+    cleanup = undefined;
+    runCleanup?.();
+    const onCleanup: WatchCleanupRegistrar = (fn) => {
+      cleanup = fn;
+    };
+    callback(value, oldValue, onCleanup);
+  };
+
+  const flush = (): boolean => {
+    const run = pending;
+    if (run === undefined) return false;
+    clearTimers();
+    pending = undefined;
+    run();
+    return true;
+  };
+
+  const cancel = (): boolean => {
+    if (pending === undefined) return false;
+    clearTimers();
+    pending = undefined;
+    return true;
+  };
+
+  const handle: WatchHandle = watch(
+    source,
+    (value, oldValue) => {
+      if (typeof window === "undefined" && !runOnServer) {
+        invoke(value, oldValue);
+        return;
+      }
+      if (pending === undefined) burstOld = oldValue;
+      const settledOld = burstOld;
+      pending = () => {
+        invoke(value, settledOld);
+      };
+      const delay = resolveMs(toValue(debounce), "debounce");
+      if (timer !== undefined) scheduler.clearTimeout(timer);
+      timer = scheduler.setTimeout(flush, delay);
+      const ceiling = toValue(maxWait);
+      if (ceiling !== undefined && maxTimer === undefined) {
+        maxTimer = scheduler.setTimeout(flush, resolveMs(ceiling, "maxWait"));
+      }
+    },
+    watchOptions,
+  );
+
+  const stop = (): void => {
+    handle.stop();
+    cancel();
+    const runCleanup = cleanup;
+    cleanup = undefined;
+    runCleanup?.();
+  };
+
+  tryOnScopeDispose(stop);
+
+  return { stop, flush, cancel };
+}

package/registry/files/watch-ignorable.ts

@@ -0,0 +1,128 @@
+import { watch } from "vue";
+import type { WatchCallback, WatchOptions } from "vue";
+
+import type { WatchHelperCallback, WatchSources } from "./watch-source.ts";
+
+/** Controls returned by {@link watchIgnorable}. */
+export 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.
+ */
+export function watchIgnorable<
+  const Sources extends WatchSources,
+  Immediate extends Readonly<boolean> = false,
+>(
+  source: Sources,
+  callback: WatchHelperCallback<Sources, Immediate>,
+  options?: WatchOptions<Immediate>,
+): IgnorableWatchHandle;
+export function watchIgnorable(
+  source: WatchSources,
+  callback: WatchCallback<unknown, unknown>,
+  options: WatchOptions<boolean> = {},
+): IgnorableWatchHandle {
+  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: () => undefined,
+      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();
+    },
+  };
+}

package/registry/files/watch-once.ts

@@ -0,0 +1,46 @@
+import { watch } from "vue";
+import type { WatchCallback, WatchHandle, WatchOptions } from "vue";
+
+import type { WatchHelperCallback, WatchSources } from "./watch-source.ts";
+
+/** Options for {@link watchOnce}: Vue watch options without `once`. */
+export type WatchOnceOptions<Immediate extends boolean = false> = Omit<
+  WatchOptions<Immediate>,
+  "once"
+>;
+
+/**
+ * Watch sources like Vue's `watch`, delivering exactly one change and then
+ * stopping.
+ *
+ * A thin, typed shorthand for `watch(source, callback, { once: true })`:
+ * with `immediate: true` the single call is the immediate one. The returned
+ * handle can stop the watcher before it fires. Safe during server rendering
+ * and bound to the owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * watchOnce(user, (loaded) => track("first-user", loaded.id));
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Called at most once.
+ * @param options Vue watch options except `once`.
+ * @default options {}
+ * @returns Vue's watch handle.
+ */
+export function watchOnce<
+  const Sources extends WatchSources,
+  Immediate extends Readonly<boolean> = false,
+>(
+  source: Sources,
+  callback: WatchHelperCallback<Sources, Immediate>,
+  options?: WatchOnceOptions<Immediate>,
+): WatchHandle;
+export function watchOnce(
+  source: WatchSources,
+  callback: WatchCallback<unknown, unknown>,
+  options: WatchOnceOptions<boolean> = {},
+): WatchHandle {
+  return watch(source, callback, { ...options, once: true });
+}

package/registry/files/watch-pausable.ts

@@ -0,0 +1,93 @@
+import { shallowRef, watch } from "vue";
+import type { ShallowRef, WatchCallback, WatchOptions } from "vue";
+
+import type { WatchHelperCallback, WatchSources } from "./watch-source.ts";
+
+/** Controls returned by {@link watchPausable}. */
+export interface PausableWatchHandle {
+  /** Whether changes are currently delivered to the callback. */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+
+  /** Drop changes until {@link PausableWatchHandle.resume}. Idempotent. */
+  readonly pause: () => void;
+
+  /** Deliver changes again. Changes made while paused are not replayed. */
+  readonly resume: () => void;
+
+  /** Stop watching permanently. */
+  readonly stop: () => void;
+}
+
+/** Options for {@link watchPausable}. */
+export interface WatchPausableOptions<
+  Immediate extends boolean = false,
+> extends WatchOptions<Immediate> {
+  /**
+   * Start in the paused state.
+   *
+   * @default false
+   */
+  readonly initiallyPaused?: boolean;
+}
+
+/**
+ * Watch sources like Vue's `watch`, with pause and resume.
+ *
+ * Unlike the `pause()` built into Vue 3.5 watch handles, which delivers one
+ * catch-up call on resume, changes made while paused are dropped: the
+ * callback only ever sees changes that happened while active. The old value
+ * passed after a resume is the value from the most recent change Vue
+ * observed, whether or not it was delivered. The watcher follows the owning
+ * reactive scope and is safe during server rendering.
+ *
+ * @example
+ * ```ts
+ * const { pause, resume } = watchPausable(form, persist, { deep: true });
+ * pause();
+ * form.name = "x"; // not persisted
+ * resume();
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Watch callback, skipped while paused.
+ * @param options Watch options plus the initial pause state.
+ * @default options {}
+ * @returns Pause, resume, and stop controls with the active flag.
+ */
+export function watchPausable<
+  const Sources extends WatchSources,
+  Immediate extends Readonly<boolean> = false,
+>(
+  source: Sources,
+  callback: WatchHelperCallback<Sources, Immediate>,
+  options?: WatchPausableOptions<Immediate>,
+): PausableWatchHandle;
+export function watchPausable(
+  source: WatchSources,
+  callback: WatchCallback<unknown, unknown>,
+  options: WatchPausableOptions<boolean> = {},
+): PausableWatchHandle {
+  const { initiallyPaused = false, ...watchOptions } = options;
+  const isActive = shallowRef(!initiallyPaused);
+
+  const handle = watch(
+    source,
+    (value, oldValue, onCleanup) => {
+      if (isActive.value) callback(value, oldValue, onCleanup);
+    },
+    watchOptions,
+  );
+
+  return {
+    isActive,
+    pause: () => {
+      isActive.value = false;
+    },
+    resume: () => {
+      isActive.value = true;
+    },
+    stop: () => {
+      handle.stop();
+    },
+  };
+}

package/registry/files/watch-source.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared source and callback typing for the watch helpers
+ * (`watchDebounced`, `watchThrottled`, `watchPausable`, `watchIgnorable`,
+ * `watchOnce`, `whenever`).
+ *
+ * The helpers accept the same sources as Vue's `watch`: a ref, a getter, a
+ * reactive object, or a tuple of those. This module declares types only and
+ * contributes no runtime code.
+ */
+import type { WatchCallback, WatchSource } from "vue";
+
+/** A single source accepted by Vue's `watch`: ref, getter, or reactive object. */
+export type WatchSourceInput = WatchSource<unknown> | object;
+
+/** Every source shape accepted by the watch helpers, including tuples. */
+export type WatchSources = WatchSourceInput | readonly WatchSourceInput[];
+
+/**
+ * Value observed from a single source: the ref/getter value, or the reactive
+ * object itself.
+ */
+export type WatchSourceValue<Source> =
+  Source extends WatchSource<infer Value> ? Value : Source extends object ? Source : never;
+
+/**
+ * Value delivered to a watch callback for {@link WatchSources}: a tuple
+ * source maps element-wise, any other source resolves through
+ * {@link WatchSourceValue}.
+ */
+export type WatchValue<Sources> = Sources extends readonly unknown[]
+  ? { -readonly [Index in keyof Sources]: WatchSourceValue<Sources[Index]> }
+  : WatchSourceValue<Sources>;
+
+/**
+ * Previous value delivered to a watch callback: `undefined` is added only
+ * when the watcher runs immediately (tuples get it per element, as in Vue).
+ */
+export type WatchOldValue<Sources, Immediate> = Immediate extends true
+  ? Sources extends readonly unknown[]
+    ? { -readonly [Index in keyof Sources]: WatchSourceValue<Sources[Index]> | undefined }
+    : WatchSourceValue<Sources> | undefined
+  : WatchValue<Sources>;
+
+/** Callback typed from its sources and the `immediate` flag. */
+export type WatchHelperCallback<Sources, Immediate = false> = WatchCallback<
+  WatchValue<Sources>,
+  WatchOldValue<Sources, Immediate>
+>;
+
+/** Cleanup registrar passed as the third argument of a watch callback. */
+export type WatchCleanupRegistrar = Parameters<WatchCallback>[2];