@fluixi/reactive 1.0.0-alpha.100

package/dist/lib/signal/cached-resource.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `cachedResource`: a resource whose results are kept, by key, for a TTL.
+ *
+ * Fetches once and serves the cached result to later reads within the TTL; after it, the
+ * next read fetches again, showing the stale value meanwhile unless `staleWhileRevalidate`
+ * is off. Readers of the same key share one request in flight.
+ *
+ *   const workspace = cachedResource(workspaceId, (id) => api.get(`/workspaces/${id}`), {
+ *     name: 'workspace',
+ *     ttl: 5 * 60_000,
+ *   });
+ *   workspace();            // the value; suspends under <Suspense> on the first load
+ *   workspace.stale;        // true while a background refetch runs
+ *   workspace.invalidate(); // drop the entry and fetch again
+ *
+ * Where entries live is the cache's business (`ResourceCache`). By default: one cache per
+ * request on the server, so visitors never share an entry or an in-flight fetch; the page in
+ * a browser. Pass `cache` to keep them elsewhere, for instance a storage that survives a reload.
+ *
+ * A value fetched during the server render travels to the browser with the page, like a
+ * plain resource's, and seeds the first read there instead of a second fetch.
+ *
+ * It runs on the live graph. Suspense needs no bookkeeping here: the accessor throws the
+ * pending promise and the runtime finds the nearest boundary from the reading effect.
+ */
+import { type ResourceCache } from './graph/ssr-hooks.js';
+import type { Setter, Resource } from './signal.js';
+export interface CachedResourceOptions {
+    /**
+     * Cache lifetime in milliseconds.
+     * Default: `Infinity`, data lives until `invalidate()` is called.
+     */
+    ttl?: number;
+    /**
+     * Cache namespace. Two calls that share the same `name` share their cache
+     * entries. When omitted, each `cachedResource` call gets a
+     * private cache isolated from all others.
+     */
+    name?: string;
+    /**
+     * When `true` (default), stale data is returned immediately while a
+     * background re-fetch runs. The resource stays in `state='ready'` and
+     * `stale=true` during revalidation, no loading skeleton.
+     *
+     * When `false`, a foreground re-fetch is triggered that sets
+     * `state='refreshing'` (data is still visible but `loading=true`).
+     */
+    staleWhileRevalidate?: boolean;
+    /** Where entries live. Defaults to the request's cache on the server and the page's in a browser. */
+    cache?: ResourceCache;
+    /** Carry the server-fetched value to the browser with the page. Default true. */
+    transport?: boolean;
+    /**
+     * Other values the data depends on: the signed-in user, the active organisation. Each
+     * combination is cached apart and a change reads (or fetches) its own entry. The fetcher
+     * still receives only the source's key.
+     */
+    deps?: ReadonlyArray<() => unknown>;
+}
+export type CachedResource<T> = Resource<T> & {
+    /** `true` while serving stale data during a background re-fetch. */
+    stale: boolean;
+};
+export interface CachedResourceActions<T> {
+    mutate: Setter<T | undefined>;
+    /** Fetch again now, whatever the TTL. The current value stays visible. */
+    refetch: () => void;
+    /** Drop the entry for the current key and fetch again. */
+    invalidate: () => void;
+}
+/** One binding: the accessor, with the actions on it. */
+export type CachedResourceHandle<T> = CachedResource<T> & CachedResourceActions<T>;
+/** Not keyed by a reactive value. */
+export declare function cachedResource<T>(fetcher: () => Promise<T> | T, options?: CachedResourceOptions): CachedResourceHandle<T>;
+/**
+ * Keyed by `source`: a new key reads its own entry, or fetches. A falsy source holds the
+ * fetch, as for `resource`.
+ */
+export declare function cachedResource<T, S>(source: () => S | false | null | undefined, fetcher: (key: S) => Promise<T> | T, options?: CachedResourceOptions): CachedResourceHandle<T>;
+/**
+ * Drops cached entries in the current scope: those of one `name`, or all of them. On a
+ * logout or a workspace switch, so nothing fetched for the previous one is served.
+ */
+export declare function clearCachedResources(name?: string, cache?: ResourceCache): void;
+export { createResourceCache, type ResourceCache, type ResourceCacheEntry } from './graph/ssr-hooks.js';
+//# sourceMappingURL=cached-resource.d.ts.map

package/dist/lib/signal/cached-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-resource.d.ts","sourceRoot":"","sources":["../../../src/lib/signal/cached-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAiB,MAAM,aAAa,CAAC;AAMnE,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qGAAqG;IACrG,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IAC5C,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAUnF,qCAAqC;AACrC,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EACjC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,EAC1C,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACnC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CAAC,CAAC,CAAC,CAAC;AA2P3B;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,aAAsC,GAAG,IAAI,CAIvG;AAED,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/lib/signal/cached-resource.js

@@ -0,0 +1,250 @@
+/**
+ * `cachedResource`: a resource whose results are kept, by key, for a TTL.
+ *
+ * Fetches once and serves the cached result to later reads within the TTL; after it, the
+ * next read fetches again, showing the stale value meanwhile unless `staleWhileRevalidate`
+ * is off. Readers of the same key share one request in flight.
+ *
+ *   const workspace = cachedResource(workspaceId, (id) => api.get(`/workspaces/${id}`), {
+ *     name: 'workspace',
+ *     ttl: 5 * 60_000,
+ *   });
+ *   workspace();            // the value; suspends under <Suspense> on the first load
+ *   workspace.stale;        // true while a background refetch runs
+ *   workspace.invalidate(); // drop the entry and fetch again
+ *
+ * Where entries live is the cache's business (`ResourceCache`). By default: one cache per
+ * request on the server, so visitors never share an entry or an in-flight fetch; the page in
+ * a browser. Pass `cache` to keep them elsewhere, for instance a storage that survives a reload.
+ *
+ * A value fetched during the server render travels to the browser with the page, like a
+ * plain resource's, and seeds the first read there instead of a second fetch.
+ *
+ * It runs on the live graph. Suspense needs no bookkeeping here: the accessor throws the
+ * pending promise and the runtime finds the nearest boundary from the reading effect.
+ */
+import { createSignal, createEffect, onCleanup, batch, untrack, } from './graph/compat.js';
+// Graph-agnostic SSR hooks, the same ones graph/resource.ts uses.
+import { currentResourceCache, getServerData, nextResourceId, reportResourceData, trackResourcePromise, } from './graph/ssr-hooks.js';
+let _autoId = 0;
+// ── Brand symbols ─────────────────────────────────────────────────────────────
+// Registry symbols, so every copy of every graph agrees on them without importing
+// anything. graph/resource.ts stamps a resource with the same two.
+const $SIGNAL = Symbol.for('signal');
+const $RESOURCE = Symbol.for('resource');
+export function cachedResource(sourceOrFetcher, fetcherOrOptions, opts = {}) {
+    // ── Normalise overloads ──────────────────────────────────────────────────
+    let sourceFn;
+    let fetchFn;
+    let options;
+    if (typeof fetcherOrOptions === 'function') {
+        sourceFn = sourceOrFetcher;
+        fetchFn = fetcherOrOptions;
+        options = opts;
+    }
+    else {
+        // No source: treat the first arg as fetcher, source = () => true
+        sourceFn = () => true;
+        fetchFn = sourceOrFetcher;
+        options = fetcherOrOptions ?? opts;
+    }
+    const { ttl = Infinity, name = `_auto_${_autoId++}`, staleWhileRevalidate = true, } = options;
+    const ns = name;
+    const cache = options.cache ?? currentResourceCache();
+    const inflight = cache.inflight;
+    // The same transport as a plain resource: an id in creation order, matched on both sides.
+    const ssrId = options.transport === false ? undefined : nextResourceId();
+    const seed = ssrId !== undefined ? getServerData(ssrId) : undefined;
+    const deps = options.deps ?? [];
+    // Tracked inside the effect, untracked from invalidate().
+    const depValues = () => deps.map((dep) => dep());
+    const buildKey = (key, values = untrack(depValues)) => `${ns}:${JSON.stringify(key)}` + (deps.length ? `:${JSON.stringify(values)}` : '');
+    const isFresh = (entry) => ttl === Infinity || Date.now() - entry.timestamp <= ttl;
+    // ── Reactive state ────────────────────────────────────────────────────────
+    const [value, setValue] = createSignal(undefined, { equals: false });
+    const [resourceState, setResourceState] = createSignal('unresolved', { equals: false });
+    const [resourceError, setResourceError] = createSignal(undefined, { equals: false });
+    const [pendingP, setPendingP] = createSignal(undefined, { equals: false });
+    const [isStale, setIsStale] = createSignal(false);
+    const [tick, setTick] = createSignal(0, { equals: false });
+    const UNSET = Symbol('unset');
+    let prevKey = UNSET;
+    let flagRefetch = false;
+    let flagInvalidate = false;
+    // ── Fetch helper ──────────────────────────────────────────────────────────
+    function doFetch(key, ck, background, isCancelled) {
+        // Attach to an in-flight request for the same key (dedup).
+        const running = inflight.get(ck);
+        if (running) {
+            running.then((v) => { if (!isCancelled())
+                settle(v, background); }, (e) => { if (!isCancelled() && !background)
+                fail(e); });
+            if (!background) {
+                trackResourcePromise(running);
+                setPendingP(running);
+            }
+            return;
+        }
+        const promise = Promise.resolve(fetchFn(key)).then((v) => {
+            cache.set(ck, { value: v, timestamp: Date.now() });
+            inflight.delete(ck);
+            return v;
+        }, (e) => {
+            inflight.delete(ck);
+            throw e;
+        });
+        inflight.set(ck, promise);
+        if (!background) {
+            trackResourcePromise(promise); // server async SSR: collect & await
+            setPendingP(promise);
+            // No boundary bookkeeping here. The accessor throws the pending promise, and
+            // the runtime's suspend handler finds the nearest boundary from the effect that
+            // was reading. graph/resource.ts leaves it to the same path.
+        }
+        promise.then((v) => { if (!isCancelled())
+            settle(v, background); }, (e) => { if (!isCancelled() && !background)
+            fail(e); });
+    }
+    function settle(v, _background) {
+        if (ssrId !== undefined)
+            reportResourceData(ssrId, v); // serialize for hydration
+        batch(() => {
+            setValue(() => v);
+            setResourceState('ready');
+            setIsStale(false);
+            setPendingP(undefined);
+            setResourceError(undefined);
+        });
+    }
+    function fail(e) {
+        batch(() => {
+            setResourceError(e);
+            setResourceState('errored');
+            setPendingP(undefined);
+        });
+    }
+    // ── Main effect ───────────────────────────────────────────────────────────
+    createEffect(() => {
+        const key = sourceFn();
+        const values = depValues();
+        tick(); // track manual triggers
+        // Suspend fetch when source is falsy (mirrors createResource)
+        if (key === false || key === null || key === undefined) {
+            prevKey = UNSET;
+            batch(() => {
+                setResourceState('unresolved');
+                setPendingP(undefined);
+                setResourceError(undefined);
+            });
+            return;
+        }
+        const doRefetch = flagRefetch;
+        const doInvalidate = flagInvalidate;
+        flagRefetch = false;
+        flagInvalidate = false;
+        const ck = buildKey(key, values);
+        // A value the server fetched for this page: the first read takes it as fresh.
+        if (seed && prevKey === UNSET && !cache.get(ck))
+            cache.set(ck, { value: seed.value, timestamp: Date.now() });
+        // Clear cache on explicit invalidate
+        if (doInvalidate)
+            cache.delete(ck);
+        const keyChanged = prevKey === UNSET || key !== prevKey;
+        prevKey = key;
+        let cancelled = false;
+        onCleanup(() => { cancelled = true; });
+        const cached = cache.get(ck);
+        // ── Cache HIT (fresh) ─────────────────────────────────────────────────
+        if (cached && isFresh(cached) && !doRefetch && !doInvalidate) {
+            // Serve synchronously, no loading state, no fetch.
+            if (ssrId !== undefined)
+                reportResourceData(ssrId, cached.value);
+            const cur = untrack(resourceState);
+            if (cur !== 'ready' || untrack(value) !== cached.value) {
+                batch(() => {
+                    setValue(() => cached.value);
+                    setResourceState('ready');
+                    setIsStale(false);
+                    setResourceError(undefined);
+                });
+            }
+            return;
+        }
+        // ── Cache HIT (stale) + staleWhileRevalidate ──────────────────────────
+        if (cached && staleWhileRevalidate && !doInvalidate) {
+            // Show stale value immediately, background-fetch new data.
+            batch(() => {
+                setValue(() => cached.value);
+                setResourceState('ready');
+                setIsStale(true);
+                setResourceError(undefined);
+                setPendingP(undefined);
+            });
+            doFetch(key, ck, true /* background */, () => cancelled);
+            return;
+        }
+        // ── No cache / invalidated / manual-refetch / SWR=false ──────────────
+        // Show loading state (keeps current value visible during 'refreshing').
+        const cur = untrack(resourceState);
+        const isReload = cur === 'ready' || cur === 'refreshing';
+        batch(() => {
+            setResourceState(isReload ? 'refreshing' : 'pending');
+            setResourceError(undefined);
+            setIsStale(false);
+        });
+        doFetch(key, ck, false /* foreground */, () => cancelled);
+    });
+    // ── Resource accessor ─────────────────────────────────────────────────────
+    // During 'pending': throw the pending promise -> Suspense shows skeleton.
+    // During 'refreshing': return stale value (no Suspense regression).
+    // During 'ready'/'errored': return value or throw error.
+    const resource = (() => {
+        const e = resourceError();
+        if (e)
+            throw e;
+        const s = resourceState();
+        if (s === 'pending') {
+            const p = pendingP();
+            if (p)
+                throw p;
+        }
+        return value();
+    });
+    Object.defineProperty(resource, $RESOURCE, { value: true, enumerable: true });
+    Object.defineProperty(resource, $SIGNAL, { value: true, enumerable: true });
+    Object.defineProperties(resource, {
+        state: { get: resourceState },
+        loading: { get: () => { const s = resourceState(); return s === 'pending' || s === 'refreshing'; } },
+        error: { get: resourceError },
+        latest: { get: value },
+        stale: { get: isStale },
+    });
+    // ── Actions ───────────────────────────────────────────────────────────────
+    const refetch = () => {
+        flagRefetch = true;
+        setTick(v => v + 1);
+    };
+    const invalidate = () => {
+        const key = untrack(sourceFn);
+        if (key !== null && key !== undefined && key !== false) {
+            cache.delete(buildKey(key));
+        }
+        flagInvalidate = true;
+        setTick(v => v + 1);
+    };
+    return Object.assign(resource, { mutate: setValue, refetch, invalidate });
+}
+// ── Cache utilities ────────────────────────────────────────────────────────────
+/**
+ * Drops cached entries in the current scope: those of one `name`, or all of them. On a
+ * logout or a workspace switch, so nothing fetched for the previous one is served.
+ */
+export function clearCachedResources(name, cache = currentResourceCache()) {
+    if (name === undefined)
+        return cache.clear();
+    const prefix = `${name}:`;
+    for (const key of [...cache.keys()])
+        if (key.startsWith(prefix))
+            cache.delete(key);
+}
+export { createResourceCache } from './graph/ssr-hooks.js';