@fluixi/reactive 1.0.0-alpha.100

package/dist/lib/signal/graph/debounced.d.ts

@@ -0,0 +1,67 @@
+import type { Accessor, Setter } from './compat.js';
+import type { ResourceFetcherInfo, ResourceReturn } from './resource.js';
+/** Controls beyond reading and writing the value. */
+export interface DebounceControls<T> {
+    /** The value as written, before the delay: bind a controlled input to this. */
+    immediate: Accessor<T>;
+    /** True while a write is waiting to settle. Distinct from a request in flight. */
+    pending: Accessor<boolean>;
+    /** Settle now, dropping the remaining delay. Returns the value that settled. */
+    flush: () => T;
+    /** Discard a pending write; the settled value keeps its last value. */
+    cancel: () => void;
+}
+/**
+ * A signal whose settled value trails writes by `delay`.
+ *
+ * @example
+ * ```ts
+ * const [query, setQuery, { immediate, pending, flush }] = createDebouncedSignal('', 300);
+ *
+ * // the input never lags: it binds the immediate value
+ * <input value={immediate()} onInput={(e) => setQuery(e.currentTarget.value)}
+ *        onKeyDown={(e) => e.key === 'Enter' && flush()} />
+ *
+ * // work keys off the settled value
+ * createEffect(() => search(query()));
+ * ```
+ */
+export declare function createDebouncedSignal<T>(initial: T, delay?: number): [Accessor<T>, Setter<T>, DebounceControls<T>];
+export interface DebouncedResourceOptions<T> {
+    /** Delay before a change reaches the fetcher. Defaults to 300ms. */
+    delay?: number;
+    /** Seed value, so the resource has something to read before the first fetch. */
+    initialValue?: T;
+    /**
+     * Whether a settled query should be fetched at all. Defaults to rejecting
+     * `undefined`, `null` and `''`, an empty search box shouldn't hit the network.
+     */
+    shouldFetch?: (query: unknown) => boolean;
+}
+export interface DebouncedResourceControls<S> extends DebounceControls<S> {
+    /** The settled query the resource is fetching for. */
+    query: Accessor<S>;
+    setQuery: Setter<S>;
+    refetch: (info?: unknown) => unknown;
+}
+/**
+ * A resource driven by a debounced query: search-as-you-type, as one primitive.
+ *
+ * Two waiting states exist and they are not the same thing: `pending` is "the user
+ * is still typing", `resource.loading` is "a request is in flight". A UI that
+ * conflates them either flickers on every keystroke or looks frozen while typing.
+ *
+ * An empty query doesn't fetch, so a cleared search box doesn't hit the network.
+ *
+ * @example
+ * ```ts
+ * const [results, { setQuery, immediate, pending, flush }] =
+ *   createDebouncedResource('', (q) => api.search(q));
+ *
+ * <input value={immediate()} onInput={(e) => setQuery(e.currentTarget.value)} />
+ * <Show when={pending()}>typing...</Show>
+ * <Show when={results.loading}>searching...</Show>
+ * ```
+ */
+export declare function createDebouncedResource<T, S>(initial: S, fetcher: (query: S, info: ResourceFetcherInfo<T>) => T | Promise<T>, options?: DebouncedResourceOptions<T>): [ResourceReturn<T>[0], DebouncedResourceControls<S>];
+//# sourceMappingURL=debounced.d.ts.map

package/dist/lib/signal/graph/debounced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounced.d.ts","sourceRoot":"","sources":["../../../../src/lib/signal/graph/debounced.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEzE,qDAAqD;AACrD,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,+EAA+E;IAC/E,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,kFAAkF;IAClF,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,CAAC;IACf,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,CAAC,EACV,KAAK,SAAM,GACV,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAqC/C;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,YAAY,CAAC,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IACvE,sDAAsD;IACtD,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAC1C,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACnE,OAAO,GAAE,wBAAwB,CAAC,CAAC,CAAM,GACxC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAetD"}

package/dist/lib/signal/graph/debounced.js

@@ -0,0 +1,92 @@
+/**
+ * Debounced reactive values.
+ *
+ * The shape that matters: a debounced input has TWO values, not one. The
+ * immediate value is what the user is typing and what a controlled input must be
+ * bound to; the settled value is what a query should run on. Collapsing them into
+ * a single delayed signal makes a controlled input lag behind the keyboard, which
+ * is why this exposes both rather than only the settled one.
+ *
+ * `flush` and `cancel` are part of the primitive, not extras: a search box needs
+ * "submit now" on Enter, and navigating away needs to drop a pending write instead
+ * of firing it into a disposed scope.
+ */
+import { createSignal, onCleanup, untrack } from './compat.js';
+import { createResource } from './resource.js';
+/**
+ * A signal whose settled value trails writes by `delay`.
+ *
+ * @example
+ * ```ts
+ * const [query, setQuery, { immediate, pending, flush }] = createDebouncedSignal('', 300);
+ *
+ * // the input never lags: it binds the immediate value
+ * <input value={immediate()} onInput={(e) => setQuery(e.currentTarget.value)}
+ *        onKeyDown={(e) => e.key === 'Enter' && flush()} />
+ *
+ * // work keys off the settled value
+ * createEffect(() => search(query()));
+ * ```
+ */
+export function createDebouncedSignal(initial, delay = 300) {
+    const [immediate, setImmediate] = createSignal(initial);
+    const [settled, setSettled] = createSignal(initial);
+    const [pending, setPending] = createSignal(false);
+    let timer;
+    const clear = () => {
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        timer = undefined;
+    };
+    const settle = () => {
+        clear();
+        // untrack, settling is a write, and must not subscribe whoever triggered it.
+        const value = untrack(immediate);
+        setSettled(() => value);
+        setPending(false);
+        return value;
+    };
+    const set = ((value) => {
+        const next = typeof value === 'function' ? value(untrack(immediate)) : value;
+        setImmediate(() => next);
+        setPending(true);
+        clear();
+        timer = setTimeout(settle, delay);
+        return next;
+    });
+    // A pending write into a disposed scope is a write nobody asked for.
+    onCleanup(clear);
+    return [settled, set, { immediate, pending, flush: settle, cancel: () => { clear(); setPending(false); } }];
+}
+function meaningful(query) {
+    return query !== undefined && query !== null && query !== '';
+}
+/**
+ * A resource driven by a debounced query: search-as-you-type, as one primitive.
+ *
+ * Two waiting states exist and they are not the same thing: `pending` is "the user
+ * is still typing", `resource.loading` is "a request is in flight". A UI that
+ * conflates them either flickers on every keystroke or looks frozen while typing.
+ *
+ * An empty query doesn't fetch, so a cleared search box doesn't hit the network.
+ *
+ * @example
+ * ```ts
+ * const [results, { setQuery, immediate, pending, flush }] =
+ *   createDebouncedResource('', (q) => api.search(q));
+ *
+ * <input value={immediate()} onInput={(e) => setQuery(e.currentTarget.value)} />
+ * <Show when={pending()}>typing...</Show>
+ * <Show when={results.loading}>searching...</Show>
+ * ```
+ */
+export function createDebouncedResource(initial, fetcher, options = {}) {
+    const { delay = 300, initialValue, shouldFetch = meaningful } = options;
+    const [query, setQuery, controls] = createDebouncedSignal(initial, delay);
+    // createResource treats a falsy source as "don't fetch", which is exactly the
+    // empty-query case, so the predicate rides on the source rather than the fetcher.
+    const source = () => (shouldFetch(query()) ? query() : false);
+    const [resource, { refetch }] = createResource(source, fetcher, initialValue === undefined ? {} : { initialValue });
+    return [resource, { ...controls, query, setQuery, refetch }];
+}