@vizejs/composable 0.345.0 → 0.347.7

package/dist/use-counter.d.mts

@@ -0,0 +1,91 @@
+import { ComputedRef, ShallowRef } from "vue";
+
+//#region src/use-counter.d.ts
+/** Options for {@link useCounter}. */
+interface UseCounterOptions {
+  /**
+   * Inclusive lower bound applied to every value the counter takes.
+   *
+   * @default Number.NEGATIVE_INFINITY
+   */
+  readonly min?: number;
+  /**
+   * Inclusive upper bound applied to every value the counter takes.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly max?: number;
+}
+/** Reactive controls returned by {@link useCounter}. */
+interface CounterControls {
+  /** Current count. Changes only through the controls, never by assignment. */
+  readonly count: Readonly<ShallowRef<number>>;
+  /** Whether the count currently sits on the configured lower bound. */
+  readonly atMin: ComputedRef<boolean>;
+  /** Whether the count currently sits on the configured upper bound. */
+  readonly atMax: ComputedRef<boolean>;
+  /**
+   * Add `delta` (default `1`) to the count and clamp into the bounds.
+   *
+   * @param delta Amount added; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly increment: (delta?: number) => number;
+  /**
+   * Subtract `delta` (default `1`) from the count and clamp into the bounds.
+   *
+   * @param delta Amount subtracted; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly decrement: (delta?: number) => number;
+  /**
+   * Assign a value directly, clamped into the bounds.
+   *
+   * @returns The count after clamping.
+   */
+  readonly set: (value: number) => number;
+  /**
+   * Restore the reset baseline, or establish a new one.
+   *
+   * Without an argument the count returns to the creation-time initial value
+   * (after its original clamping). With an argument, the clamped value
+   * becomes both the new count and the baseline used by later `reset()`
+   * calls.
+   *
+   * @param value Replacement baseline.
+   * @returns The count after clamping.
+   */
+  readonly reset: (value?: number) => number;
+}
+/**
+ * Create a clamped counter whose every transition stays inside `[min, max]`.
+ *
+ * All operations clamp instead of failing, including the initial value, so
+ * the count is inside the bounds at every observable moment. Only `NaN` is
+ * rejected — silently corrupting the count is never an option. Purely
+ * synchronous state: safe during server rendering (no browser globals, no
+ * timers) and nothing to dispose, so it works inside and outside reactive
+ * scopes alike. Bounds are fixed at creation and not reactive.
+ *
+ * @example
+ * ```ts
+ * const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
+ * increment(); // 10
+ * increment(); // 10 (clamped)
+ * atMax.value; // true
+ * ```
+ *
+ * @param initial Count before any operation, clamped into the bounds.
+ * @default initial 0
+ * @param options Inclusive bounds for every value the counter takes.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
+ * bound is `NaN` or `min` exceeds `max`.
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
+ * initial value, operand, or arithmetic result is `NaN` (for example
+ * incrementing `-Infinity` by `Infinity`); the count is left unchanged.
+ * @returns Reactive count, bound flags, and mutation controls.
+ */
+declare function useCounter(initial?: number, options?: UseCounterOptions): CounterControls;
+//#endregion
+export { CounterControls, UseCounterOptions, useCounter };

package/dist/use-counter.mjs

@@ -0,0 +1,67 @@
+import { computed, shallowRef } from "vue";
+//#region src/use-counter.ts
+/**
+* Create a clamped counter whose every transition stays inside `[min, max]`.
+*
+* All operations clamp instead of failing, including the initial value, so
+* the count is inside the bounds at every observable moment. Only `NaN` is
+* rejected — silently corrupting the count is never an option. Purely
+* synchronous state: safe during server rendering (no browser globals, no
+* timers) and nothing to dispose, so it works inside and outside reactive
+* scopes alike. Bounds are fixed at creation and not reactive.
+*
+* @example
+* ```ts
+* const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
+* increment(); // 10
+* increment(); // 10 (clamped)
+* atMax.value; // true
+* ```
+*
+* @param initial Count before any operation, clamped into the bounds.
+* @default initial 0
+* @param options Inclusive bounds for every value the counter takes.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
+* bound is `NaN` or `min` exceeds `max`.
+* @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
+* initial value, operand, or arithmetic result is `NaN` (for example
+* incrementing `-Infinity` by `Infinity`); the count is left unchanged.
+* @returns Reactive count, bound flags, and mutation controls.
+*/
+function useCounter(initial = 0, options = {}) {
+	const min = requireBound(options.min ?? Number.NEGATIVE_INFINITY, "min");
+	const max = requireBound(options.max ?? Number.POSITIVE_INFINITY, "max");
+	if (min > max) throw new RangeError(`[VIZE_COMPOSE_COUNTER_INVALID_RANGE] min must not exceed max; received min ${String(min)} and max ${String(max)}`);
+	const clamp = (value) => Math.min(max, Math.max(min, value));
+	const count = shallowRef(clamp(requireValue(initial)));
+	let baseline = count.value;
+	const setClamped = (next) => {
+		count.value = clamp(requireValue(next));
+		return count.value;
+	};
+	const reset = (value) => {
+		const applied = setClamped(value ?? baseline);
+		if (value !== void 0) baseline = applied;
+		return applied;
+	};
+	return {
+		count,
+		atMin: computed(() => count.value === min),
+		atMax: computed(() => count.value === max),
+		increment: (delta = 1) => setClamped(count.value + requireValue(delta)),
+		decrement: (delta = 1) => setClamped(count.value - requireValue(delta)),
+		set: setClamped,
+		reset
+	};
+}
+function requireBound(value, label) {
+	if (Number.isNaN(value)) throw new RangeError(`[VIZE_COMPOSE_COUNTER_INVALID_RANGE] ${label} must not be NaN`);
+	return value;
+}
+function requireValue(value) {
+	if (Number.isNaN(value)) throw new RangeError("[VIZE_COMPOSE_COUNTER_INVALID_VALUE] the value is NaN; counter state was left unchanged");
+	return value;
+}
+//#endregion
+export { useCounter };

package/dist/use-debounced.d.mts

@@ -0,0 +1,87 @@
+import { TimeoutScheduler } from "./timeout-scheduler.mjs";
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-debounced.d.ts
+/** Options for {@link useDebounced}. */
+interface UseDebouncedOptions {
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the debounced view
+   * mirrors the source synchronously instead of starting timers. Enable it
+   * for native, desktop, worker, and test runtimes whose scheduler is
+   * lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the single-shot timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive debounced view and controls returned by {@link useDebounced}. */
+interface DebouncedControls<Value> {
+  /** Readonly view of the source that settles `waitMs` after the last change. */
+  readonly debounced: Readonly<ShallowRef<Value>>;
+  /** Whether a trailing update is currently scheduled. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+  /**
+   * Discard the scheduled trailing update and keep the last settled value.
+   * Later source changes debounce again as usual.
+   *
+   * @returns Whether a scheduled update was discarded.
+   */
+  readonly cancel: () => boolean;
+  /**
+   * Apply the current source value immediately instead of waiting out the
+   * delay.
+   *
+   * @returns Whether a scheduled update was applied.
+   */
+  readonly flush: () => boolean;
+}
+/**
+ * Create a readonly debounced view of a reactive source.
+ *
+ * The view starts at the current source value. Each source change (observed
+ * with `flush: "sync"`, so every synchronous write counts) restarts a
+ * single-shot timer of `waitMs` milliseconds; when it fires, the view takes
+ * the source value current at that moment. `waitMs` is reactive and is read
+ * when a timer is scheduled; changing it does not restart an already-pending
+ * timer. A wait of `0` still defers to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
+ * the view mirrors the source synchronously, so server-rendered output shows
+ * current values and nothing leaks. `pending` stays `false` and the controls
+ * report `false` in that mode.
+ *
+ * Cleanup rule: the watcher and any pending timer are released when the
+ * owning reactive scope stops; call inside an active scope. Outside one, the
+ * watcher lives as long as the source and `cancel()` only clears the pending
+ * timer.
+ *
+ * @example
+ * ```ts
+ * const query = shallowRef("");
+ * const { debounced, flush } = useDebounced(query, 300);
+ * query.value = "vize"; // debounced.value still "" for 300ms
+ * flush(); // debounced.value === "vize" immediately
+ * ```
+ *
+ * @param source Reactive source to debounce.
+ * @param waitMs Reactive delay in milliseconds; must be finite and at least
+ * zero. Fractions are truncated.
+ * @param options Runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again for every scheduled delay.
+ * @returns Readonly debounced view, pending flag, and cancel/flush controls.
+ */
+declare function useDebounced<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseDebouncedOptions): DebouncedControls<Value>;
+//#endregion
+export { DebouncedControls, UseDebouncedOptions, useDebounced };

package/dist/use-debounced.mjs

@@ -0,0 +1,98 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { shallowRef, toValue, watch } from "vue";
+//#region src/use-debounced.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Create a readonly debounced view of a reactive source.
+*
+* The view starts at the current source value. Each source change (observed
+* with `flush: "sync"`, so every synchronous write counts) restarts a
+* single-shot timer of `waitMs` milliseconds; when it fires, the view takes
+* the source value current at that moment. `waitMs` is reactive and is read
+* when a timer is scheduled; changing it does not restart an already-pending
+* timer. A wait of `0` still defers to the next scheduler tick.
+*
+* Server rendering is explicit: without a browser `window` (and with
+* {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
+* the view mirrors the source synchronously, so server-rendered output shows
+* current values and nothing leaks. `pending` stays `false` and the controls
+* report `false` in that mode.
+*
+* Cleanup rule: the watcher and any pending timer are released when the
+* owning reactive scope stops; call inside an active scope. Outside one, the
+* watcher lives as long as the source and `cancel()` only clears the pending
+* timer.
+*
+* @example
+* ```ts
+* const query = shallowRef("");
+* const { debounced, flush } = useDebounced(query, 300);
+* query.value = "vize"; // debounced.value still "" for 300ms
+* flush(); // debounced.value === "vize" immediately
+* ```
+*
+* @param source Reactive source to debounce.
+* @param waitMs Reactive delay in milliseconds; must be finite and at least
+* zero. Fractions are truncated.
+* @param options Runtime scheduling overrides.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
+* resolved wait is not finite or is negative, both synchronously at creation
+* (even in mirror mode) and again for every scheduled delay.
+* @returns Readonly debounced view, pending flag, and cancel/flush controls.
+*/
+function useDebounced(source, waitMs, options = {}) {
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const debounced = shallowRef(toValue(source));
+	const pending = shallowRef(false);
+	let handle;
+	resolveWaitMs(toValue(waitMs));
+	const apply = () => {
+		handle = void 0;
+		pending.value = false;
+		debounced.value = toValue(source);
+	};
+	const cancel = () => {
+		if (!pending.value) return false;
+		scheduler.clearTimeout(handle);
+		handle = void 0;
+		pending.value = false;
+		return true;
+	};
+	const flush = () => {
+		if (!pending.value) return false;
+		scheduler.clearTimeout(handle);
+		apply();
+		return true;
+	};
+	watch(() => toValue(source), (next) => {
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+			debounced.value = next;
+			return;
+		}
+		const delayMs = resolveWaitMs(toValue(waitMs));
+		if (pending.value) scheduler.clearTimeout(handle);
+		pending.value = true;
+		handle = scheduler.setTimeout(apply, delayMs);
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		cancel();
+	});
+	return {
+		debounced,
+		pending,
+		cancel,
+		flush
+	};
+}
+function resolveWaitMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+//#endregion
+export { useDebounced };

package/dist/use-history.d.mts

@@ -0,0 +1,105 @@
+import { ComputedRef, Ref } from "vue";
+
+//#region src/use-history.d.ts
+/** Options for {@link useHistory}. */
+interface UseHistoryOptions<Value> {
+  /**
+   * Maximum number of undo entries retained; recording a change beyond it
+   * drops the oldest entry. The redo stack is bounded by construction, since
+   * redo entries only ever come from undone changes. Must be an integer
+   * greater than zero and is fixed at creation.
+   *
+   * @default 100
+   */
+  readonly capacity?: number;
+  /**
+   * Clone applied to every value captured into history and to every value
+   * restored out of it, isolating snapshots from later in-place mutation.
+   *
+   * @default identity — values are stored and restored by reference
+   */
+  readonly clone?: (value: Value) => Value;
+}
+/** Reactive undo/redo controls returned by {@link useHistory}. */
+interface HistoryControls {
+  /** Whether {@link HistoryControls.undo} currently has an entry to restore. */
+  readonly canUndo: ComputedRef<boolean>;
+  /** Whether {@link HistoryControls.redo} currently has an entry to restore. */
+  readonly canRedo: ComputedRef<boolean>;
+  /** Number of retained undo entries. */
+  readonly undoCount: ComputedRef<number>;
+  /** Number of retained redo entries. */
+  readonly redoCount: ComputedRef<number>;
+  /**
+   * Restore the newest undo entry and move the current value onto the redo
+   * stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly undo: () => boolean;
+  /**
+   * Restore the newest redo entry and move the current value back onto the
+   * undo stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly redo: () => boolean;
+  /**
+   * Group every source write inside `run` into at most one undo entry.
+   *
+   * The entry restores the value from just before the batch. It is committed
+   * only when the final value differs (`Object.is`) from the starting value,
+   * and it is committed even when `run` throws, so a partially applied batch
+   * stays undoable as one step. Nested calls collapse into the outermost
+   * batch. The callback's return value is passed through.
+   */
+  readonly batch: <Result>(run: () => Result) => Result;
+  /** Drop every undo and redo entry while keeping the current value. */
+  readonly clear: () => void;
+}
+/**
+ * Record bounded undo/redo history over the writes of a ref.
+ *
+ * Recording is shallow and identity-based, matching Vue's own change
+ * detection: assignments to `source.value` are recorded (observed with
+ * `flush: "sync"`, so every synchronous write counts), writes that are
+ * `Object.is`-equal to the current value are not changes, and in-place
+ * mutations of object values are invisible — pair mutable values with
+ * {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
+ * values through `clone` as well, so snapshots never share identity with the
+ * live value unless the default identity clone is kept. When a
+ * user-provided `clone` throws, the failed operation leaves history
+ * unchanged and the error propagates.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. Cleanup rule: when the owning reactive scope stops, recording stops
+ * and every retained snapshot is released, so `undo`/`redo` return `false`
+ * afterwards; call inside an active scope, or the watcher lives as long as
+ * the source.
+ *
+ * @example
+ * ```ts
+ * const text = shallowRef("");
+ * const { undo, redo, batch } = useHistory(text);
+ * text.value = "a";
+ * batch(() => {
+ *   text.value = "ab";
+ *   text.value = "abc";
+ * });
+ * undo(); // text.value === "a" (the batch is one step)
+ * redo(); // text.value === "abc"
+ * ```
+ *
+ * @param source Ref whose writes are recorded.
+ * @param options Retention bound and snapshot cloning.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
+ * the capacity is not an integer greater than zero.
+ * @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
+ * `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
+ * stack movement would corrupt the pending group.
+ * @returns Reactive undo/redo state and controls.
+ */
+declare function useHistory<Value>(source: Ref<Value>, options?: UseHistoryOptions<Value>): HistoryControls;
+//#endregion
+export { HistoryControls, UseHistoryOptions, useHistory };

package/dist/use-history.mjs

@@ -0,0 +1,137 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, shallowRef, watch } from "vue";
+//#region src/use-history.ts
+/**
+* Record bounded undo/redo history over the writes of a ref.
+*
+* Recording is shallow and identity-based, matching Vue's own change
+* detection: assignments to `source.value` are recorded (observed with
+* `flush: "sync"`, so every synchronous write counts), writes that are
+* `Object.is`-equal to the current value are not changes, and in-place
+* mutations of object values are invisible — pair mutable values with
+* {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
+* values through `clone` as well, so snapshots never share identity with the
+* live value unless the default identity clone is kept. When a
+* user-provided `clone` throws, the failed operation leaves history
+* unchanged and the error propagates.
+*
+* Safe during server rendering: no browser globals are read and no timers
+* start. Cleanup rule: when the owning reactive scope stops, recording stops
+* and every retained snapshot is released, so `undo`/`redo` return `false`
+* afterwards; call inside an active scope, or the watcher lives as long as
+* the source.
+*
+* @example
+* ```ts
+* const text = shallowRef("");
+* const { undo, redo, batch } = useHistory(text);
+* text.value = "a";
+* batch(() => {
+*   text.value = "ab";
+*   text.value = "abc";
+* });
+* undo(); // text.value === "a" (the batch is one step)
+* redo(); // text.value === "abc"
+* ```
+*
+* @param source Ref whose writes are recorded.
+* @param options Retention bound and snapshot cloning.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
+* the capacity is not an integer greater than zero.
+* @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
+* `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
+* stack movement would corrupt the pending group.
+* @returns Reactive undo/redo state and controls.
+*/
+function useHistory(source, options = {}) {
+	const capacity = options.capacity ?? 100;
+	if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError(`[VIZE_COMPOSE_HISTORY_INVALID_CAPACITY] capacity must be an integer greater than zero; received ${String(capacity)}`);
+	const clone = options.clone ?? ((value) => value);
+	const undoStack = shallowRef([]);
+	const redoStack = shallowRef([]);
+	let restoring = false;
+	let batchDepth = 0;
+	let activeBatch;
+	const pushUndo = (entry) => {
+		const next = [...undoStack.value, entry];
+		undoStack.value = next.length > capacity ? next.slice(next.length - capacity) : next;
+		redoStack.value = [];
+	};
+	const writeSilently = (value) => {
+		restoring = true;
+		try {
+			source.value = value;
+		} finally {
+			restoring = false;
+		}
+	};
+	const requireOutsideBatch = (operation) => {
+		if (batchDepth > 0) throw new Error(`[VIZE_COMPOSE_HISTORY_IN_BATCH] ${operation}() is not available inside batch()`);
+	};
+	const undo = () => {
+		requireOutsideBatch("undo");
+		const entry = undoStack.value.at(-1);
+		if (entry === void 0) return false;
+		const restored = clone(entry.value);
+		const recorded = { value: clone(source.value) };
+		undoStack.value = undoStack.value.slice(0, -1);
+		redoStack.value = [...redoStack.value, recorded];
+		writeSilently(restored);
+		return true;
+	};
+	const redo = () => {
+		requireOutsideBatch("redo");
+		const entry = redoStack.value.at(-1);
+		if (entry === void 0) return false;
+		const restored = clone(entry.value);
+		const recorded = { value: clone(source.value) };
+		redoStack.value = redoStack.value.slice(0, -1);
+		undoStack.value = [...undoStack.value, recorded];
+		writeSilently(restored);
+		return true;
+	};
+	const batch = (run) => {
+		if (batchDepth === 0) activeBatch = {
+			raw: source.value,
+			entry: { value: clone(source.value) }
+		};
+		batchDepth += 1;
+		try {
+			return run();
+		} finally {
+			batchDepth -= 1;
+			if (batchDepth === 0 && activeBatch !== void 0) {
+				const finished = activeBatch;
+				activeBatch = void 0;
+				if (!Object.is(finished.raw, source.value)) pushUndo(finished.entry);
+			}
+		}
+	};
+	const clear = () => {
+		requireOutsideBatch("clear");
+		undoStack.value = [];
+		redoStack.value = [];
+	};
+	const handle = watch(source, (_next, replaced) => {
+		if (restoring || batchDepth > 0) return;
+		pushUndo({ value: clone(replaced) });
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		handle.stop();
+		undoStack.value = [];
+		redoStack.value = [];
+	});
+	return {
+		canUndo: computed(() => undoStack.value.length > 0),
+		canRedo: computed(() => redoStack.value.length > 0),
+		undoCount: computed(() => undoStack.value.length),
+		redoCount: computed(() => redoStack.value.length),
+		undo,
+		redo,
+		batch,
+		clear
+	};
+}
+//#endregion
+export { useHistory };

package/dist/use-previous.d.mts

@@ -0,0 +1,43 @@
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-previous.d.ts
+/**
+ * Track the value a reactive source held before its latest change.
+ *
+ * The semantics are precise and arity-based:
+ *
+ * - Without an `initial` argument the ref holds `undefined` until the source
+ *   changes for the first time.
+ * - With an `initial` argument (including an explicit `undefined` when
+ *   `Value` allows it) the ref holds that value until the first change, and
+ *   the return type never widens with `undefined`.
+ * - Every synchronous write is observed (`flush: "sync"`), so a sequence of
+ *   writes in one tick shifts the previous value step by step instead of
+ *   collapsing into one batch.
+ * - Writes whose value is `Object.is`-equal to the current value do not
+ *   count as changes, matching Vue's own change detection.
+ * - Tracking is shallow: reassignments are observed, in-place mutations of
+ *   object values are not.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. The underlying watcher is bound to the current reactive scope and
+ * stops with it; call inside an active scope, or the watcher lives as long
+ * as the source. A plain non-reactive source never changes, so the ref stays
+ * at its initial value.
+ *
+ * @example
+ * ```ts
+ * const route = shallowRef("/home");
+ * const previousRoute = usePrevious(route, "/");
+ * route.value = "/settings";
+ * previousRoute.value; // "/home"
+ * ```
+ *
+ * @param source Reactive source to observe.
+ * @param initial Value reported before the first change.
+ * @returns Readonly shallow ref holding the previous source value.
+ */
+declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>): Readonly<ShallowRef<Value | undefined>>;
+declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>, initial: Value): Readonly<ShallowRef<Value>>;
+//#endregion
+export { usePrevious };

package/dist/use-previous.mjs

@@ -0,0 +1,11 @@
+import { shallowRef, toValue, watch } from "vue";
+//#region src/use-previous.ts
+function usePrevious(source, ...initial) {
+	const previous = shallowRef(initial.length === 1 ? initial[0] : void 0);
+	watch(() => toValue(source), (_next, replaced) => {
+		previous.value = replaced;
+	}, { flush: "sync" });
+	return previous;
+}
+//#endregion
+export { usePrevious };