@vizejs/composable 0.343.0 → 0.347.7

package/dist/use-throttled.d.mts

@@ -0,0 +1,107 @@
+import { TimeoutScheduler } from "./timeout-scheduler.mjs";
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-throttled.d.ts
+/** Options for {@link useThrottled}. */
+interface UseThrottledOptions {
+  /**
+   * Apply the first change of a cooldown window immediately.
+   *
+   * @default true
+   */
+  readonly leading?: boolean;
+  /**
+   * Apply the newest change collected during a cooldown window when the
+   * window ends. When disabled, changes inside a window are dropped.
+   *
+   * @default true
+   */
+  readonly trailing?: boolean;
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the throttled 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 cooldown timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive throttled view and controls returned by {@link useThrottled}. */
+interface ThrottledControls<Value> {
+  /** Readonly view of the source updated at most once per cooldown window. */
+  readonly throttled: Readonly<ShallowRef<Value>>;
+  /** Whether a trailing update is waiting for the current window to end. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+  /**
+   * Discard the waiting trailing update and close the cooldown window, so
+   * the next change starts fresh on a leading edge.
+   *
+   * @returns Whether a waiting trailing update was discarded.
+   */
+  readonly cancel: () => boolean;
+  /**
+   * Apply the waiting trailing update immediately and close the cooldown
+   * window. Without a waiting update the window is left untouched.
+   *
+   * @returns Whether a waiting trailing update was applied.
+   */
+  readonly flush: () => boolean;
+}
+/**
+ * Create a readonly throttled view of a reactive source.
+ *
+ * Changes are observed with `flush: "sync"`, so every synchronous write
+ * counts. Outside a cooldown window, a change applies immediately when
+ * {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
+ * trailing update) and opens a window of `waitMs` milliseconds. Changes
+ * inside a window are collected as the trailing candidate; when the window
+ * ends with a candidate waiting, the source value current at that moment is
+ * applied and the next window opens back to back, keeping applications
+ * spaced by `waitMs`. A window that ends without a candidate closes silently.
+ * `waitMs` is reactive and is read each time a window opens; changing it
+ * never disturbs an already-open window. A wait of `0` still defers trailing
+ * updates to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseThrottledOptions.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 open window 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 window.
+ *
+ * @example
+ * ```ts
+ * const scrollY = shallowRef(0);
+ * const { throttled } = useThrottled(scrollY, 100);
+ * scrollY.value = 40; // applied immediately (leading edge)
+ * scrollY.value = 80; // applied when the 100ms window ends
+ * ```
+ *
+ * @param source Reactive source to throttle.
+ * @param waitMs Reactive cooldown in milliseconds; must be finite and at
+ * least zero. Fractions are truncated.
+ * @param options Edge policy and runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again each time a window opens.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
+ * `leading` and `trailing` are disabled, because updates could then never
+ * propagate.
+ * @returns Readonly throttled view, pending flag, and cancel/flush controls.
+ */
+declare function useThrottled<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseThrottledOptions): ThrottledControls<Value>;
+//#endregion
+export { ThrottledControls, UseThrottledOptions, useThrottled };

package/dist/use-throttled.mjs

@@ -0,0 +1,124 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { shallowRef, toValue, watch } from "vue";
+//#region src/use-throttled.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Create a readonly throttled view of a reactive source.
+*
+* Changes are observed with `flush: "sync"`, so every synchronous write
+* counts. Outside a cooldown window, a change applies immediately when
+* {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
+* trailing update) and opens a window of `waitMs` milliseconds. Changes
+* inside a window are collected as the trailing candidate; when the window
+* ends with a candidate waiting, the source value current at that moment is
+* applied and the next window opens back to back, keeping applications
+* spaced by `waitMs`. A window that ends without a candidate closes silently.
+* `waitMs` is reactive and is read each time a window opens; changing it
+* never disturbs an already-open window. A wait of `0` still defers trailing
+* updates to the next scheduler tick.
+*
+* Server rendering is explicit: without a browser `window` (and with
+* {@link UseThrottledOptions.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 open window 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 window.
+*
+* @example
+* ```ts
+* const scrollY = shallowRef(0);
+* const { throttled } = useThrottled(scrollY, 100);
+* scrollY.value = 40; // applied immediately (leading edge)
+* scrollY.value = 80; // applied when the 100ms window ends
+* ```
+*
+* @param source Reactive source to throttle.
+* @param waitMs Reactive cooldown in milliseconds; must be finite and at
+* least zero. Fractions are truncated.
+* @param options Edge policy and runtime scheduling overrides.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
+* resolved wait is not finite or is negative, both synchronously at creation
+* (even in mirror mode) and again each time a window opens.
+* @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
+* `leading` and `trailing` are disabled, because updates could then never
+* propagate.
+* @returns Readonly throttled view, pending flag, and cancel/flush controls.
+*/
+function useThrottled(source, waitMs, options = {}) {
+	const leading = options.leading ?? true;
+	const trailing = options.trailing ?? true;
+	if (!leading && !trailing) throw new TypeError("[VIZE_COMPOSE_THROTTLE_INVALID_EDGES] at least one of leading or trailing must be enabled");
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const throttled = shallowRef(toValue(source));
+	const pending = shallowRef(false);
+	let windowHandle;
+	let windowOpen = false;
+	resolveWaitMs(toValue(waitMs));
+	const openWindow = () => {
+		windowOpen = true;
+		windowHandle = scheduler.setTimeout(() => {
+			windowHandle = void 0;
+			if (!pending.value) {
+				windowOpen = false;
+				return;
+			}
+			pending.value = false;
+			throttled.value = toValue(source);
+			openWindow();
+		}, resolveWaitMs(toValue(waitMs)));
+	};
+	const closeWindow = () => {
+		if (windowOpen) scheduler.clearTimeout(windowHandle);
+		windowHandle = void 0;
+		windowOpen = false;
+		pending.value = false;
+	};
+	const cancel = () => {
+		const hadTrailing = pending.value;
+		closeWindow();
+		return hadTrailing;
+	};
+	const flush = () => {
+		if (!pending.value) return false;
+		closeWindow();
+		throttled.value = toValue(source);
+		return true;
+	};
+	watch(() => toValue(source), (next) => {
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+			throttled.value = next;
+			return;
+		}
+		if (windowOpen) {
+			if (trailing) pending.value = true;
+			return;
+		}
+		if (leading) throttled.value = next;
+		else pending.value = true;
+		openWindow();
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		cancel();
+	});
+	return {
+		throttled,
+		pending,
+		cancel,
+		flush
+	};
+}
+function resolveWaitMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_THROTTLE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+//#endregion
+export { useThrottled };

package/dist/use-toggle.d.mts

@@ -0,0 +1,45 @@
+import { Ref } from "vue";
+
+//#region src/use-toggle.d.ts
+/** Reactive controls returned by {@link useToggle}. */
+interface ToggleControls {
+  /**
+   * Owned boolean state.
+   *
+   * Deliberately writable: unlike the derived views elsewhere in this
+   * package, the toggle owns its state, so assigning the ref directly (for
+   * example through `v-model`) is equivalent to calling
+   * {@link ToggleControls.toggle} with a forced value.
+   */
+  readonly state: Ref<boolean>;
+  /**
+   * Invert the state, or force it to `force` when the argument is given.
+   * Passing an explicit `undefined` behaves like passing no argument.
+   *
+   * @param force Value assigned instead of inverting.
+   * @returns The state after the change.
+   */
+  readonly toggle: (force?: boolean) => boolean;
+}
+/**
+ * Create owned boolean state with an inverting control.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const { state: open, toggle } = useToggle();
+ * toggle(); // true
+ * toggle(false); // false
+ * open.value; // false
+ * ```
+ *
+ * @param initial State before the first toggle.
+ * @default initial false
+ * @returns The writable state and its toggle control.
+ */
+declare function useToggle(initial?: boolean): ToggleControls;
+//#endregion
+export { ToggleControls, useToggle };

package/dist/use-toggle.mjs

@@ -0,0 +1,34 @@
+import { shallowRef } from "vue";
+//#region src/use-toggle.ts
+/**
+* Create owned boolean state with an inverting control.
+*
+* 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.
+*
+* @example
+* ```ts
+* const { state: open, toggle } = useToggle();
+* toggle(); // true
+* toggle(false); // false
+* open.value; // false
+* ```
+*
+* @param initial State before the first toggle.
+* @default initial false
+* @returns The writable state and its toggle control.
+*/
+function useToggle(initial = false) {
+	const state = shallowRef(initial);
+	const toggle = (force) => {
+		state.value = force ?? !state.value;
+		return state.value;
+	};
+	return {
+		state,
+		toggle
+	};
+}
+//#endregion
+export { useToggle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizejs/composable",
-  "version": "0.343.0",
+  "version": "0.347.7",
   "description": "Lifecycle-safe composable foundations for Vize applications",
   "keywords": [
     "composables",
@@ -32,10 +32,100 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./abort-signal": {
+      "types": "./dist/abort-signal.d.mts",
+      "import": "./dist/abort-signal.mjs",
+      "default": "./dist/abort-signal.mjs"
+    },
+    "./async-resource": {
+      "types": "./dist/async-resource.d.mts",
+      "import": "./dist/async-resource.mjs",
+      "default": "./dist/async-resource.mjs"
+    },
+    "./capability": {
+      "types": "./dist/capability.d.mts",
+      "import": "./dist/capability.mjs",
+      "default": "./dist/capability.mjs"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.mts",
+      "import": "./dist/catalog.mjs",
+      "default": "./dist/catalog.mjs"
+    },
+    "./disposal-scope": {
+      "types": "./dist/disposal-scope.d.mts",
+      "import": "./dist/disposal-scope.mjs",
+      "default": "./dist/disposal-scope.mjs"
+    },
+    "./event-listener": {
+      "types": "./dist/event-listener.d.mts",
+      "import": "./dist/event-listener.mjs",
+      "default": "./dist/event-listener.mjs"
+    },
+    "./locale": {
+      "types": "./dist/locale.d.mts",
+      "import": "./dist/locale.mjs",
+      "default": "./dist/locale.mjs"
+    },
+    "./media-query": {
+      "types": "./dist/media-query.d.mts",
+      "import": "./dist/media-query.mjs",
+      "default": "./dist/media-query.mjs"
+    },
+    "./retry-async": {
+      "types": "./dist/retry-async.d.mts",
+      "import": "./dist/retry-async.mjs",
+      "default": "./dist/retry-async.mjs"
+    },
+    "./retry-delay": {
+      "types": "./dist/retry-delay.d.mts",
+      "import": "./dist/retry-delay.mjs",
+      "default": "./dist/retry-delay.mjs"
+    },
+    "./scope": {
+      "types": "./dist/scope.d.mts",
+      "import": "./dist/scope.mjs",
+      "default": "./dist/scope.mjs"
+    },
     "./temporal": {
       "types": "./dist/temporal.d.mts",
       "import": "./dist/temporal.mjs",
       "default": "./dist/temporal.mjs"
+    },
+    "./timeout-scheduler": {
+      "types": "./dist/timeout-scheduler.d.mts",
+      "import": "./dist/timeout-scheduler.mjs",
+      "default": "./dist/timeout-scheduler.mjs"
+    },
+    "./use-counter": {
+      "types": "./dist/use-counter.d.mts",
+      "import": "./dist/use-counter.mjs",
+      "default": "./dist/use-counter.mjs"
+    },
+    "./use-debounced": {
+      "types": "./dist/use-debounced.d.mts",
+      "import": "./dist/use-debounced.mjs",
+      "default": "./dist/use-debounced.mjs"
+    },
+    "./use-history": {
+      "types": "./dist/use-history.d.mts",
+      "import": "./dist/use-history.mjs",
+      "default": "./dist/use-history.mjs"
+    },
+    "./use-previous": {
+      "types": "./dist/use-previous.d.mts",
+      "import": "./dist/use-previous.mjs",
+      "default": "./dist/use-previous.mjs"
+    },
+    "./use-throttled": {
+      "types": "./dist/use-throttled.d.mts",
+      "import": "./dist/use-throttled.mjs",
+      "default": "./dist/use-throttled.mjs"
+    },
+    "./use-toggle": {
+      "types": "./dist/use-toggle.d.mts",
+      "import": "./dist/use-toggle.mjs",
+      "default": "./dist/use-toggle.mjs"
     }
   },
   "publishConfig": {