@jini-ai/ui 0.4.7 → 0.4.8

package/dist/features/panel-kit/fetch-query/cache.js

@@ -1,232 +0,0 @@
-/**
- * Ten seconds covers reading, closing and reopening a record or bouncing between screens
- * without paying for another identical request. Five seconds was too short for that read
- * cycle; thirty seconds exposed more other-operator staleness than the conservative initial
- * shared default should allow. There is no default polling/focus refresh, so this bounds
- * the extra exposure on a quick revisit. Write invalidation bypasses freshness; reads that
- * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
- */
-export const DEFAULT_STALE_TIME = 10_000;
-/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
-export const IDLE_RETENTION = 5 * 60_000;
-const browserScheduler = {
-    schedule: ({ callback, delayMs }) => setTimeout(callback, delayMs),
-    cancel: ({ handle }) => clearTimeout(handle),
-};
-// Normalize unknown promise rejections once so consumers receive Error without repeating
-// the same narrowing boilerplate at every read and write call site.
-export function toQueryError(value) {
-    return value instanceof Error ? value : new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
-}
-/** One provider-owned cache. Requests are shared by structural primitive keys.
- * Failed reads retain earlier data; replacement writes supersede older requests.
- * Idle entries live for at least five minutes or their declared freshness period. */
-export class FetchQueryCache {
-    entries = new Map();
-    disposed = false;
-    clock;
-    scheduler;
-    environment;
-    online;
-    onlineWaiters = new Set();
-    releaseEnvironment;
-    constructor(_required = {}, { clock = { nowMs: () => Date.now() }, scheduler = browserScheduler, environment } = {}) {
-        this.clock = clock;
-        this.scheduler = scheduler;
-        this.environment = environment;
-        this.online = environment?.isOnline() ?? true;
-    }
-    entry({ key }, { staleTime = DEFAULT_STALE_TIME } = {}) {
-        const hash = JSON.stringify(key);
-        let entry = this.entries.get(hash);
-        if (!entry) {
-            entry = {
-                key: [...key], state: { data: undefined, error: null, status: 'pending', isFetching: false },
-                updatedAt: 0, invalidated: false, replacement: 0, pending: undefined,
-                refreshAfterPending: false, listeners: new Set(), observers: new Set(),
-                retention: IDLE_RETENTION, eviction: undefined,
-            };
-            this.entries.set(hash, entry);
-        }
-        // An imperative load has no standing observer: idle eviction must not drop a value
-        // earlier than its declared freshness and unexpectedly force another network request.
-        entry.retention = Math.max(entry.retention, staleTime);
-        return entry;
-    }
-    fresh({ entry, staleTime }) {
-        return entry.state.data !== undefined && !entry.invalidated && this.clock.nowMs() - entry.updatedAt < staleTime;
-    }
-    subscribe({ entry, listener }) {
-        this.cancelEviction(entry);
-        entry.listeners.add(listener);
-        return () => { entry.listeners.delete(listener); this.scheduleEviction(entry); };
-    }
-    observe({ entry, observer }) {
-        entry.observers.add(observer);
-        return () => { entry.observers.delete(observer); this.scheduleEviction(entry); };
-    }
-    /** Cache hits respect freshness; explicit refreshes restart background reads.
-     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
-    load({ entry, fetch, staleTime }, { force = false } = {}) {
-        this.cancelEviction(entry);
-        if (entry.pending && (!force || entry.state.data === undefined))
-            return entry.pending;
-        if (!force && this.fresh({ entry: entry, staleTime: staleTime })) {
-            this.scheduleEviction(entry);
-            return Promise.resolve(entry.state.data);
-        }
-        // Shared per key across loader instances: a replacement while this request is out
-        // must win over its older answer, not just protect the instance that issued the write.
-        const replacement = entry.replacement;
-        const run = () => {
-            // A queued offline refresh may have been superseded before reconnection.
-            if (entry.pending !== pending)
-                return (entry.pending ?? Promise.resolve(entry.state.data));
-            this.publish(entry, { ...entry.state, isFetching: true });
-            return fetch();
-        };
-        const pending = Promise.resolve().then(() => {
-            if (this.online)
-                return run();
-            this.publish(entry, { ...entry.state, isFetching: false });
-            return this.runOnline({ run });
-        }).then(value => {
-            const data = replacement === entry.replacement ? value : entry.state.data;
-            // Undefined is never successful query data, including an initial or background read.
-            if (data === undefined)
-                throw new Error(`${JSON.stringify(entry.key)} data is undefined`);
-            return data;
-        }).then(data => {
-            // Only the current request may publish or clear invalidation. An older transport
-            // need not support abort: its callers follow the replacement request instead.
-            if (entry.pending !== pending)
-                return (entry.pending ?? entry.state.data);
-            entry.updatedAt = this.clock.nowMs();
-            entry.invalidated = false;
-            this.publish(entry, { data, error: null, status: 'success', isFetching: false });
-            return data;
-        }, error => {
-            if (entry.pending !== pending)
-                return (entry.pending ?? entry.state.data);
-            // A replacement write is newer than this read's failure as well as its data.
-            // Keep the write's timestamp and freshness; only settle the obsolete fetch flag.
-            if (replacement !== entry.replacement) {
-                this.publish(entry, { ...entry.state, isFetching: false });
-                return entry.state.data;
-            }
-            entry.invalidated = true;
-            this.publish(entry, { ...entry.state, error: toQueryError(error), status: 'error', isFetching: false });
-            throw error;
-        }).finally(() => {
-            if (entry.pending !== pending)
-                return;
-            entry.pending = undefined;
-            if (entry.refreshAfterPending) {
-                entry.refreshAfterPending = false;
-                this.refresh(entry);
-            }
-            this.scheduleEviction(entry);
-        });
-        entry.pending = pending;
-        // Mark handled even when a UI caller deliberately discards the promise.
-        void pending.catch(() => { });
-        // Like TanStack's background refetches, retain the last error until success clears it
-        // or another failure replaces it. Extend that rule to retries without cached data:
-        // starting a request is not evidence of recovery; isFetching reports its progress.
-        const state = entry.state.data === undefined ? { ...entry.state, status: 'pending' } : entry.state;
-        this.publish(entry, { ...state, isFetching: this.online });
-        return pending;
-    }
-    replace({ entry, data }) {
-        entry.replacement += 1;
-        entry.updatedAt = this.clock.nowMs();
-        entry.invalidated = false;
-        this.publish(entry, { data, error: null, status: 'success', isFetching: entry.state.isFetching });
-        this.scheduleEviction(entry);
-    }
-    invalidate({ prefix }) {
-        for (const entry of this.entries.values()) {
-            if (!prefix.every((part, index) => entry.key[index] === part))
-                continue;
-            entry.invalidated = true;
-            this.refresh(entry);
-        }
-    }
-    onFocus() {
-        for (const entry of this.entries.values()) {
-            const observer = [...entry.observers].find(value => value.focus && !this.fresh({ entry: entry, staleTime: value.staleTime }));
-            // Environmental refreshes share a request already underway, unlike an explicit gesture.
-            if (observer && !entry.pending)
-                void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime });
-        }
-    }
-    /** Execute a read/write once connectivity returns; failures are not retried.
-     * @param required.run Operation to invoke online.
-     * @returns The operation's original result or rejection. */
-    runOnline({ run }) {
-        if (this.online)
-            return Promise.resolve().then(() => {
-                // Connectivity may change between queuing the operation and its invocation.
-                if (!this.online)
-                    return this.runOnline({ run });
-                return run();
-            });
-        return new Promise(resolve => { this.onlineWaiters.add(resolve); }).then(() => this.runOnline({ run }));
-    }
-    /** Stop timers on provider disposal; reactivate for React's effect replay. */
-    activate() {
-        this.disposed = false;
-        if (!this.environment || this.releaseEnvironment)
-            return;
-        const releaseOnline = this.environment.subscribeOnline({ listener: online => this.onOnline({ online }) });
-        const releaseFocus = this.environment.subscribeFocus({ listener: () => this.onFocus() });
-        this.releaseEnvironment = () => { releaseOnline(); releaseFocus(); };
-        this.onOnline({ online: this.environment.isOnline() });
-    }
-    dispose() {
-        this.disposed = true;
-        this.releaseEnvironment?.();
-        this.releaseEnvironment = undefined;
-        for (const entry of this.entries.values())
-            this.cancelEviction(entry);
-    }
-    onOnline({ online }) {
-        const reconnect = online && !this.online;
-        this.online = online;
-        if (!online)
-            return;
-        for (const resume of this.onlineWaiters)
-            resume();
-        this.onlineWaiters.clear();
-        if (!reconnect)
-            return;
-        for (const entry of this.entries.values()) {
-            const observer = [...entry.observers].find(value => !this.fresh({ entry, staleTime: value.staleTime }));
-            // A paused request already owns its resumption; restarting it here would double-fetch.
-            if (observer && !entry.pending)
-                void this.load({ entry, fetch: observer.fetch, staleTime: observer.staleTime });
-        }
-    }
-    refresh(entry) {
-        const observer = entry.observers.values().next().value;
-        if (observer)
-            void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime }, { force: true });
-    }
-    publish(entry, state) {
-        entry.state = state;
-        for (const listener of entry.listeners)
-            listener();
-    }
-    cancelEviction(entry) {
-        if (entry.eviction !== undefined)
-            this.scheduler.cancel({ handle: entry.eviction });
-        entry.eviction = undefined;
-    }
-    scheduleEviction(entry) {
-        this.cancelEviction(entry);
-        if (this.disposed || entry.listeners.size || entry.observers.size || entry.pending || !Number.isFinite(entry.retention))
-            return;
-        entry.eviction = this.scheduler.schedule({ callback: () => this.entries.delete(JSON.stringify(entry.key)), delayMs: entry.retention });
-    }
-}
-//# sourceMappingURL=cache.js.map

package/dist/features/panel-kit/fetch-query/types.d.ts

@@ -1,93 +0,0 @@
-/**
- * Keep the contract independent of any query library so an adapter swap does not require
- * rewriting callers. Add narrow required capabilities here rather than exporting library
- * result/client types that would bypass this boundary.
- */
-/**
- * Keys contain primitive array parts so parameterised resources compose without fragile
- * string formatting or object-identity mismatches. Invalidation matches by PREFIX: a list
- * key also refreshes its derived child keys. Exact-key equality would compile while quietly
- * breaking that guarantee; avoid a shared prefix for resources that merely sound related,
- * or writes will fan out unnecessary refetches.
- * Stay primitive-only: the built-in cache matches each part with === while TanStack deep-matches,
- * so an object part would invalidate under one adapter and silently not under the other.
- */
-export type QueryKey = readonly (string | number)[];
-export type QueryStatus = "loading" | "success" | "error";
-export interface QueryResult<T> {
-    data: T | undefined;
-    error: Error | null;
-    status: QueryStatus;
-    isFetching: boolean;
-    refetch: () => void;
-}
-export interface FetchQueryOptions<T> {
-    key: QueryKey;
-    fetch: () => Promise<T>;
-    /**
-     * Gate on user intent or prerequisites to avoid fetching an undefined id. Disabling does
-     * not erase cached failures: without any successful data, report loading/error:null so
-     * a gesture-gated read cannot show an old failure before the user asks for it. With
-     * earlier data, report success but retain a later background error so known-stale data
-     * need not be presented as an unqualified success.
-     */
-    enabled?: boolean;
-    staleTime?: number;
-    refetchOnWindowFocus?: boolean;
-}
-export type MutationStatus = "idle" | "pending" | "success" | "error";
-export interface MutationResult<TInput, TOutput> {
-    /**
-     * Awaiting the write receives its result or rejection; discarding the same promise and
-     * reading state is safe because it already has a rejection handler. Returning a bare
-     * rejecting promise would make only the awaiting form safe. Node unhandledRejection
-     * can verify this contract even where a DOM unhandledrejection event does not fire.
-     */
-    mutate: (required: {
-        input: TInput;
-    }) => Promise<TOutput>;
-    status: MutationStatus;
-    error: Error | null;
-    reset: () => void;
-}
-export interface FetchMutationOptions<TInput, TOutput> {
-    run: (required: {
-        input: TInput;
-    }) => Promise<TOutput>;
-    invalidates?: readonly QueryKey[];
-}
-/**
- * Keep key and fetch references stable: they are memo dependencies of the loader handle.
- * Failed fetches reject and are not cached, so the next load retries instead of replaying
- * a failure as data. Retain an idle value at least as long as its declared freshness: an
- * imperative loader has no persistent observer to keep it alive.
- */
-export interface CachedLoaderOptions<T> {
-    key: QueryKey;
-    fetch: () => Promise<T>;
-    staleTime?: number;
-}
-/**
- * A plain promise loader serves components that own their loading UI rather than consuming
- * a hook result. It shares the provider cache, including one in-flight request per key.
- */
-export interface CachedLoader<T> {
-    peek: () => T | undefined;
-    load: () => Promise<T>;
-    replace: (required: {
-        value: T;
-    }) => void;
-}
-/**
- * Keep the provider-facing hooks, loader and invalidator behind one binding so replacing
- * the cache implementation does not leave different consumers on different adapters.
- */
-export interface FetchQueryAdapter {
-    useFetchQuery: <T>(required: Pick<FetchQueryOptions<T>, "key" | "fetch">, optional?: Omit<FetchQueryOptions<T>, "key" | "fetch">) => QueryResult<T>;
-    useFetchMutation: <TInput, TOutput>(required: Pick<FetchMutationOptions<TInput, TOutput>, "run">, optional?: Omit<FetchMutationOptions<TInput, TOutput>, "run">) => MutationResult<TInput, TOutput>;
-    useInvalidate: () => (required: {
-        key: QueryKey;
-    }) => void;
-    useCachedLoader: <T>(required: Pick<CachedLoaderOptions<T>, "key" | "fetch">, optional?: Omit<CachedLoaderOptions<T>, "key" | "fetch">) => CachedLoader<T>;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/features/panel-kit/fetch-query/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map