dalila 1.4.2 → 1.4.4

package/dist/core/persist.js

@@ -0,0 +1,371 @@
+import { effect } from './signal.js';
+import { getCurrentScope } from './scope.js';
+const defaultSerializer = {
+    serialize: JSON.stringify,
+    deserialize: JSON.parse,
+};
+function isPromiseLike(v) {
+    return !!v && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
+}
+function safeDefaultStorage() {
+    if (typeof window === 'undefined')
+        return undefined;
+    try {
+        return window.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function parseVersion(v) {
+    if (typeof v !== 'string')
+        return 0;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+function isPlainObject(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    if (Array.isArray(v))
+        return false;
+    return Object.getPrototypeOf(v) === Object.prototype;
+}
+/**
+ * Create a persisted signal that automatically syncs with storage.
+ */
+export function persist(baseSignal, options) {
+    const { name, storage = safeDefaultStorage(), serializer = defaultSerializer, version, merge = 'replace', onRehydrate, onError, migrate, } = options;
+    if (!name) {
+        throw new Error('[Dalila] persist() requires a "name" option');
+    }
+    if (!storage) {
+        console.warn(`[Dalila] persist(): storage not available for "${name}", persistence disabled`);
+        return baseSignal;
+    }
+    const storageKey = name;
+    const versionKey = version !== undefined ? `${name}:version` : undefined;
+    // ---- Core safety flags ----
+    // hydrated=false blocks writes so we don't overwrite storage before async read resolves.
+    let hydrated = false;
+    // becomes true if user changes signal before hydration completes
+    let dirtyBeforeHydrate = false;
+    /**
+     * Hydration write guard:
+     * The dirty listener below uses baseSignal.on(), which would also fire for the
+     * hydration set() itself. This guard prevents hydration from counting as "user dirty".
+     */
+    let isHydrationWrite = false;
+    // temporary listener to detect changes before hydration completes
+    let removeDirtyListener = null;
+    /**
+     * Write-back dedupe (best effort):
+     * Avoid rewriting the same serialized value back to storage after hydration.
+     *
+     * - lastSaved: what we believe is currently in storage
+     * - pendingSaved: what we've already queued to write
+     *
+     * This prevents: storage -> hydrate -> effect runs -> serialize -> setItem(same value)
+     */
+    let lastSaved = null;
+    let pendingSaved = null;
+    // Same idea for version key (when enabled)
+    let lastSavedVersion = null;
+    let pendingSavedVersion = null;
+    const handleError = (err, ctx) => {
+        const e = toError(err);
+        if (onError)
+            onError(e);
+        else
+            console.error(`[Dalila] persist(): ${ctx} "${name}"`, e);
+    };
+    const applyHydration = (value) => {
+        // Ensure dirty listener does not treat hydration as user mutation.
+        const setHydratedValue = (next) => {
+            isHydrationWrite = true;
+            try {
+                baseSignal.set(next);
+            }
+            finally {
+                isHydrationWrite = false;
+            }
+        };
+        if (merge === 'shallow' && isPlainObject(value)) {
+            const current = baseSignal.peek();
+            if (isPlainObject(current)) {
+                setHydratedValue({ ...current, ...value });
+                return;
+            }
+        }
+        setHydratedValue(value);
+    };
+    // Ensure async writes don't land out-of-order (queue them)
+    let writeChain = Promise.resolve();
+    const queueWrite = (fn) => {
+        writeChain = writeChain
+            .then(() => fn())
+            .catch((err) => {
+            // If a queued write fails, clear pending so future writes aren't blocked.
+            pendingSaved = null;
+            pendingSavedVersion = null;
+            handleError(err, 'failed to save');
+        });
+    };
+    /**
+     * Enqueue write with dedupe:
+     * - if value/version already matches what's saved (or already queued), no-op.
+     */
+    const enqueuePersist = (serialized, versionStr) => {
+        const needsValue = serialized !== lastSaved && serialized !== pendingSaved;
+        const needsVersion = !!versionKey &&
+            versionStr !== null &&
+            versionStr !== lastSavedVersion &&
+            versionStr !== pendingSavedVersion;
+        if (!needsValue && !needsVersion)
+            return;
+        if (needsValue)
+            pendingSaved = serialized;
+        if (needsVersion)
+            pendingSavedVersion = versionStr;
+        queueWrite(async () => {
+            // Write value
+            if (needsValue) {
+                const r1 = storage.setItem(storageKey, serialized);
+                if (isPromiseLike(r1))
+                    await r1;
+                lastSaved = serialized;
+                if (pendingSaved === serialized)
+                    pendingSaved = null;
+            }
+            // Write version
+            if (needsVersion && versionKey && versionStr !== null) {
+                const r2 = storage.setItem(versionKey, versionStr);
+                if (isPromiseLike(r2))
+                    await r2;
+                lastSavedVersion = versionStr;
+                if (pendingSavedVersion === versionStr)
+                    pendingSavedVersion = null;
+            }
+        });
+    };
+    const persistValue = (value) => {
+        // Don't write until hydration finishes (prevents overwriting stored state).
+        if (!hydrated)
+            return;
+        let serialized;
+        try {
+            serialized = serializer.serialize(value);
+        }
+        catch (err) {
+            handleError(err, 'failed to serialize');
+            return;
+        }
+        const versionStr = versionKey ? String(version) : null;
+        enqueuePersist(serialized, versionStr);
+    };
+    /**
+     * Hydrate from already-read storage strings.
+     * For sync storage we can read versionKey synchronously too.
+     */
+    const hydrateFromStored = (storedValue, storedVersionRaw) => {
+        // Track current storage contents to avoid immediate write-back.
+        lastSaved = storedValue;
+        pendingSaved = null;
+        if (versionKey) {
+            lastSavedVersion = storedVersionRaw;
+            pendingSavedVersion = null;
+        }
+        const deserialized = serializer.deserialize(storedValue);
+        if (version !== undefined && versionKey && migrate) {
+            const storedVersion = parseVersion(storedVersionRaw);
+            if (storedVersion !== version) {
+                const migrated = migrate(deserialized, storedVersion);
+                applyHydration(migrated);
+                // Save migrated data to storage (don't leave old data with new version)
+                let migratedSerialized;
+                try {
+                    migratedSerialized = serializer.serialize(baseSignal.peek());
+                }
+                catch (err) {
+                    handleError(err, 'failed to serialize migrated data');
+                    return;
+                }
+                enqueuePersist(migratedSerialized, String(version));
+                return;
+            }
+        }
+        applyHydration(deserialized);
+    };
+    const finalizeHydration = (didUserChangeBefore) => {
+        hydrated = true;
+        // Remove temporary dirty listener (no longer needed after hydration)
+        if (removeDirtyListener) {
+            removeDirtyListener();
+            removeDirtyListener = null;
+        }
+        // If user changed before hydrate finished, we must persist current value at least once,
+        // because the change already happened while hydrated=false and won't re-trigger.
+        if (didUserChangeBefore) {
+            persistValue(baseSignal.peek());
+        }
+        if (onRehydrate) {
+            try {
+                onRehydrate(baseSignal.peek());
+            }
+            catch (err) {
+                handleError(err, 'onRehydrate threw');
+            }
+        }
+    };
+    const hydrate = () => {
+        try {
+            const stored = storage.getItem(storageKey);
+            // async storage
+            if (isPromiseLike(stored)) {
+                return stored
+                    .then(async (storedValue) => {
+                    if (storedValue === null) {
+                        finalizeHydration(dirtyBeforeHydrate);
+                        return;
+                    }
+                    // Track value even if we skip applying due to dirty (helps dedupe correctness).
+                    lastSaved = storedValue;
+                    pendingSaved = null;
+                    // If user changed before hydration finished, prefer local state:
+                    // do NOT apply storedValue (prevents "rollback" to old storage).
+                    if (dirtyBeforeHydrate) {
+                        // Best-effort track version too (if enabled), not required for correctness.
+                        if (versionKey) {
+                            try {
+                                const v = await storage.getItem(versionKey);
+                                lastSavedVersion = typeof v === 'string' ? v : null;
+                                pendingSavedVersion = null;
+                            }
+                            catch {
+                                // ignore
+                            }
+                        }
+                        finalizeHydration(true);
+                        return;
+                    }
+                    let storedVersionRaw = null;
+                    if (versionKey) {
+                        const v = await storage.getItem(versionKey);
+                        storedVersionRaw = typeof v === 'string' ? v : null;
+                    }
+                    hydrateFromStored(storedValue, storedVersionRaw);
+                    finalizeHydration(false);
+                })
+                    .catch((err) => {
+                    handleError(err, 'failed to hydrate');
+                    // Even on error, allow future writes (otherwise persist becomes inert)
+                    finalizeHydration(dirtyBeforeHydrate);
+                });
+            }
+            // sync storage
+            if (stored === null) {
+                finalizeHydration(false);
+                return;
+            }
+            let storedVersionRaw = null;
+            if (versionKey) {
+                const v = storage.getItem(versionKey);
+                storedVersionRaw = isPromiseLike(v) ? null : typeof v === 'string' ? v : null;
+            }
+            hydrateFromStored(stored, storedVersionRaw);
+            finalizeHydration(false);
+        }
+        catch (err) {
+            handleError(err, 'failed to hydrate');
+            finalizeHydration(dirtyBeforeHydrate);
+        }
+    };
+    // ---- Set up persistence + dirty tracking ----
+    // Perfect dirty detection: track any changes before hydration completes.
+    // This catches even synchronous sets before the effect's first run.
+    if (!hydrated) {
+        removeDirtyListener = baseSignal.on(() => {
+            // Ignore hydration writes (hydration must NOT count as "user dirty").
+            if (!hydrated && !isHydrationWrite)
+                dirtyBeforeHydrate = true;
+        });
+    }
+    const scope = getCurrentScope();
+    if (scope) {
+        effect(() => {
+            const value = baseSignal();
+            // After hydration completes, persist normally
+            if (hydrated) {
+                persistValue(value);
+            }
+        });
+        // Clean up temporary dirty listener when scope disposes (if still active)
+        if (removeDirtyListener) {
+            scope.onCleanup(removeDirtyListener);
+        }
+    }
+    else {
+        // No scope: use manual subscription.
+        // Dirty-before-hydrate is still handled by the temporary dirty listener above.
+        baseSignal.on((value) => {
+            if (hydrated) {
+                persistValue(value);
+            }
+        });
+    }
+    // Hydrate after wiring subscribers so async hydration sets can trigger persist if needed.
+    const hydration = hydrate();
+    if (isPromiseLike(hydration)) {
+        hydration.catch((err) => {
+            // already handled inside hydrate(), but keep as last-resort safety
+            console.error(`[Dalila] persist(): hydration promise rejected for "${name}"`, err);
+        });
+    }
+    return baseSignal;
+}
+/**
+ * Helper to create JSON storage wrapper
+ */
+export function createJSONStorage(getStorage) {
+    return getStorage();
+}
+/**
+ * Clear persisted data for a given key
+ */
+export function clearPersisted(name, storage = safeDefaultStorage() ?? {}) {
+    if (!storage.removeItem) {
+        console.warn(`[Dalila] clearPersisted(): storage.removeItem not available for "${name}"`);
+        return;
+    }
+    try {
+        void storage.removeItem(name);
+        void storage.removeItem(`${name}:version`);
+    }
+    catch (err) {
+        console.error(`[Dalila] clearPersisted(): failed for "${name}"`, err);
+    }
+}
+/**
+ * Generate a minimal inline script to prevent FOUC.
+ *
+ * NOTE: Assumes the value in storage was JSON serialized (default serializer).
+ */
+export function createPreloadScript(options) {
+    const { storageKey, defaultValue, target = 'documentElement', attribute = 'data-theme', storageType = 'localStorage', } = options;
+    // Use JSON.stringify to safely embed strings (avoid breaking quotes / injection)
+    const k = JSON.stringify(storageKey);
+    const d = JSON.stringify(defaultValue);
+    const a = JSON.stringify(attribute);
+    // Still minified
+    return `(function(){try{var s=${storageType}.getItem(${k});var v=s==null?${d}:JSON.parse(s);document.${target}.setAttribute(${a},v)}catch(e){document.${target}.setAttribute(${a},${d})}})();`;
+}
+export function createThemeScript(storageKey, defaultTheme = 'light') {
+    return createPreloadScript({
+        storageKey,
+        defaultValue: defaultTheme,
+        target: 'documentElement',
+        attribute: 'data-theme',
+    });
+}

package/dist/core/query.d.ts

@@ -0,0 +1,72 @@
+import { key as keyBuilder, type QueryKey } from "./key.js";
+import { type MutationConfig, type MutationState } from "./mutation.js";
+export interface QueryConfig<TKey extends QueryKey, TResult> {
+    /** Reactive key (stable identity + encodable). */
+    key: () => TKey;
+    /** Optional tags registered on the cached resource (for invalidation). */
+    tags?: readonly string[];
+    /** Fetch function for the given key (AbortSignal is provided). */
+    fetch: (signal: AbortSignal, key: TKey) => Promise<TResult>;
+    /**
+     * Optional stale revalidation window (ms).
+     * After a successful fetch, schedules a refresh after `staleTime`.
+     */
+    staleTime?: number;
+    /** Optional initial value (treated as already-known data). */
+    initialValue?: TResult;
+    onSuccess?: (data: TResult) => void;
+    onError?: (error: Error) => void;
+}
+export interface QueryState<TResult> {
+    data: () => TResult | null;
+    loading: () => boolean;
+    error: () => Error | null;
+    /** Manual refresh of the underlying resource. */
+    refresh: (opts?: {
+        force?: boolean;
+    }) => Promise<void>;
+    /** Derived status for convenience. */
+    status: () => "loading" | "error" | "success";
+    /** Current encoded cache key. */
+    cacheKey: () => string;
+}
+export interface QueryClient {
+    key: typeof keyBuilder;
+    /** Safe-by-default: requires scope for caching. Outside scope, does NOT cache. */
+    query: <TKey extends QueryKey, TResult>(cfg: QueryConfig<TKey, TResult>) => QueryState<TResult>;
+    /** Explicit global caching (persist). */
+    queryGlobal: <TKey extends QueryKey, TResult>(cfg: QueryConfig<TKey, TResult>) => QueryState<TResult>;
+    mutation: <TInput, TResult>(cfg: MutationConfig<TInput, TResult>) => MutationState<TInput, TResult>;
+    invalidateKey: (key: QueryKey, opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+    invalidateTag: (tag: string, opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+    invalidateTags: (tags: readonly string[], opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+}
+/**
+ * Query client (React Query-like API on top of Dalila resources).
+ *
+ * Design goals:
+ * - DOM-first + signals: queries are just resources exposed as reactive getters.
+ * - Cache safety: by default, caching requires a scope; global cache is opt-in.
+ * - Keyed caching: results are cached by encoded key.
+ * - Stale revalidation: optionally schedule a refresh after a successful fetch.
+ *
+ * Implementation notes:
+ * - The underlying cached resource is created inside a computed() so it can react
+ *   to key changes.
+ * - computed() is lazy, so we "kick" it once and also install an effect() that
+ *   re-reads it, ensuring key changes recreate the resource even if nobody reads
+ *   data() yet.
+ * - staleTime revalidation is guarded by `expectedCk` so a timer from an old key
+ *   cannot refresh a new key’s resource.
+ * - If created inside a scope, staleTime timers are cleared on scope cleanup.
+ */
+export declare function createQueryClient(): QueryClient;

package/dist/core/query.js

@@ -0,0 +1,184 @@
+import { computed, effect } from "./signal.js";
+import { getCurrentScope, createScope, withScope } from "./scope.js";
+import { key as keyBuilder, encodeKey } from "./key.js";
+import { createCachedResource, invalidateResourceCache, invalidateResourceTag, invalidateResourceTags, } from "./resource.js";
+import { createMutation } from "./mutation.js";
+import { isInDevMode } from "./dev.js";
+/**
+ * Query client (React Query-like API on top of Dalila resources).
+ *
+ * Design goals:
+ * - DOM-first + signals: queries are just resources exposed as reactive getters.
+ * - Cache safety: by default, caching requires a scope; global cache is opt-in.
+ * - Keyed caching: results are cached by encoded key.
+ * - Stale revalidation: optionally schedule a refresh after a successful fetch.
+ *
+ * Implementation notes:
+ * - The underlying cached resource is created inside a computed() so it can react
+ *   to key changes.
+ * - computed() is lazy, so we "kick" it once and also install an effect() that
+ *   re-reads it, ensuring key changes recreate the resource even if nobody reads
+ *   data() yet.
+ * - staleTime revalidation is guarded by `expectedCk` so a timer from an old key
+ *   cannot refresh a new key’s resource.
+ * - If created inside a scope, staleTime timers are cleared on scope cleanup.
+ */
+export function createQueryClient() {
+    function makeQuery(cfg, behavior) {
+        const scope = getCurrentScope();
+        const parentScope = scope;
+        const staleTime = cfg.staleTime ?? 0;
+        let staleTimer = null;
+        let cleanupRegistered = false;
+        let keyScope = null;
+        let keyScopeCk = null;
+        if (isInDevMode() && !parentScope && behavior.persist === false) {
+            console.warn(`[Dalila] q.query() called outside a scope. ` +
+                `It will not cache and may leak. Use within a scope or q.queryGlobal().`);
+        }
+        function ensureKeyScope(ck) {
+            if (!parentScope)
+                return null;
+            if (keyScope && keyScopeCk === ck)
+                return keyScope;
+            // cancel any pending stale timer from the previous key
+            if (staleTimer != null) {
+                clearTimeout(staleTimer);
+                staleTimer = null;
+            }
+            keyScope?.dispose();
+            keyScopeCk = ck;
+            keyScope = createScope(parentScope);
+            return keyScope;
+        }
+        /**
+         * Schedules a stale-time revalidation after success.
+         *
+         * Race safety:
+         * - Captures `expectedCk` so a timer created for an old key cannot refresh
+         *   after the key changes.
+         *
+         * Lifetime:
+         * - If in a scope, the timer is cleared on scope cleanup.
+         */
+        const scheduleStaleRevalidate = (r, expectedCk) => {
+            if (staleTime <= 0)
+                return;
+            if (!scope) {
+                if (isInDevMode()) {
+                    console.warn(`[Dalila] staleTime requires a scope for cleanup. ` +
+                        `Run the query inside a scope or disable staleTime.`);
+                }
+                return;
+            }
+            if (encodeKey(cfg.key()) !== expectedCk)
+                return;
+            // Register cleanup once (if we have a scope).
+            if (!cleanupRegistered) {
+                cleanupRegistered = true;
+                scope.onCleanup(() => {
+                    if (staleTimer != null)
+                        clearTimeout(staleTimer);
+                    staleTimer = null;
+                });
+            }
+            // Only one pending stale timer per query instance.
+            if (staleTimer != null) {
+                clearTimeout(staleTimer);
+                staleTimer = null;
+            }
+            staleTimer = setTimeout(() => {
+                // Guard against revalidating stale keys when key changed during staleTime.
+                if (encodeKey(cfg.key()) !== expectedCk)
+                    return;
+                r.refresh({ force: false }).catch(() => { });
+            }, staleTime);
+        };
+        /**
+         * Underlying cached resource.
+         *
+         * Important: we capture `r` via `let r!` so `onSuccess` can schedule the
+         * stale revalidation against the correct instance.
+         */
+        const resource = computed(() => {
+            const k = cfg.key();
+            const ck = encodeKey(k);
+            let r;
+            const ks = ensureKeyScope(ck);
+            const opts = {
+                onError: cfg.onError,
+                onSuccess: (data) => {
+                    cfg.onSuccess?.(data);
+                    scheduleStaleRevalidate(r, ck);
+                },
+                persist: behavior.persist,
+                warnPersistWithoutTtl: behavior.warnPersistWithoutTtl,
+                fetchScope: ks ?? undefined,
+            };
+            if (cfg.initialValue !== undefined)
+                opts.initialValue = cfg.initialValue;
+            // Keyed cache entry (scope-safe unless persist is enabled).
+            const make = () => createCachedResource(ck, async (sig) => {
+                await Promise.resolve(); // break reactive tracking
+                return cfg.fetch(sig, k);
+            }, { ...opts, tags: cfg.tags });
+            r = ks ? withScope(ks, make) : make();
+            return r;
+        });
+        /** Convenience derived status from the underlying resource. */
+        const status = computed(() => {
+            const r = resource();
+            if (r.loading())
+                return "loading";
+            if (r.error())
+                return "error";
+            return "success";
+        });
+        /** Expose the current encoded key as a computed signal. */
+        const cacheKeySig = computed(() => encodeKey(cfg.key()));
+        /**
+         * Kick once so the initial query starts immediately.
+         * Then keep it reactive so key changes recreate the resource
+         * even if nobody reads data() / loading() / error().
+         */
+        resource();
+        effect(() => {
+            resource();
+        });
+        return {
+            data: () => resource().data(),
+            loading: () => resource().loading(),
+            error: () => resource().error(),
+            refresh: (opts) => resource().refresh(opts),
+            status: () => status(),
+            cacheKey: () => cacheKeySig(),
+        };
+    }
+    function query(cfg) {
+        return makeQuery(cfg, { persist: false });
+    }
+    function queryGlobal(cfg) {
+        return makeQuery(cfg, { persist: true, warnPersistWithoutTtl: false });
+    }
+    function mutation(cfg) {
+        return createMutation(cfg);
+    }
+    function invalidateKey(k, opts = {}) {
+        invalidateResourceCache(encodeKey(k), opts);
+    }
+    function invalidateTag(tag, opts = {}) {
+        invalidateResourceTag(tag, opts);
+    }
+    function invalidateTags(tags, opts = {}) {
+        invalidateResourceTags(tags, opts);
+    }
+    return {
+        key: keyBuilder,
+        query,
+        queryGlobal,
+        mutation,
+        invalidateKey,
+        invalidateTag,
+        invalidateTags,
+    };
+}