dalila 1.4.2 → 1.4.4

package/dist/core/index.js

@@ -0,0 +1,14 @@
+export * from "./scope.js";
+export * from "./signal.js";
+export * from "./watch.js";
+export * from "./when.js";
+export * from "./match.js";
+export * from "./for.js";
+export * from "./virtual.js";
+export * from "./dev.js";
+export * from "./key.js";
+export * from "./resource.js";
+export * from "./query.js";
+export * from "./mutation.js";
+export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";
+export { persist, createJSONStorage, clearPersisted, createPreloadScript, createThemeScript } from "./persist.js";

package/dist/core/key.d.ts

@@ -0,0 +1,33 @@
+export type QueryKeyPart = string | number | boolean | null | undefined | symbol;
+export type QueryKey = readonly QueryKeyPart[] | string;
+/**
+ * Enable or disable dev mode warnings for key encoding.
+ */
+export declare function setKeyDevMode(enabled: boolean): void;
+/**
+ * Helper to build an array key with good inference and stable readonly typing.
+ *
+ * Example:
+ *   key("user", userId())
+ *
+ * Note: Objects are not valid key parts. Use primitive values only.
+ */
+export declare function key<const T extends readonly QueryKeyPart[]>(...parts: T): T;
+/**
+ * Encoded string form of a query key.
+ * This is what the cache uses internally as the Map key.
+ */
+export type EncodedKey = string;
+/**
+ * Encode a query key to a stable string (ES2020-safe).
+ *
+ * We avoid JSON.stringify because:
+ * - it can be unstable for some values
+ * - it is slower
+ * - it doesn't encode NaN/-0 consistently
+ */
+export declare function encodeKey(k: QueryKey): EncodedKey;
+/**
+ * Runtime guard (handy for debugging / devtools).
+ */
+export declare function isQueryKey(v: unknown): v is QueryKey;

package/dist/core/key.js

@@ -0,0 +1,83 @@
+/** Dev mode flag for warnings. */
+let devMode = true;
+/**
+ * Enable or disable dev mode warnings for key encoding.
+ */
+export function setKeyDevMode(enabled) {
+    devMode = enabled;
+}
+/**
+ * Helper to build an array key with good inference and stable readonly typing.
+ *
+ * Example:
+ *   key("user", userId())
+ *
+ * Note: Objects are not valid key parts. Use primitive values only.
+ */
+export function key(...parts) {
+    if (devMode) {
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (part !== null && typeof part === 'object') {
+                console.warn(`[Dalila] key() received an object at index ${i}. ` +
+                    `Objects are not stable key parts and may cause cache misses. ` +
+                    `Use primitive values (string, number, boolean) instead.`);
+            }
+        }
+    }
+    return parts;
+}
+/**
+ * Encode a query key to a stable string (ES2020-safe).
+ *
+ * We avoid JSON.stringify because:
+ * - it can be unstable for some values
+ * - it is slower
+ * - it doesn't encode NaN/-0 consistently
+ */
+export function encodeKey(k) {
+    if (typeof k === "string")
+        return "k|str|" + escapeKeyString(k);
+    return "k|arr|" + k.map(encodeKeyPart).join(";");
+}
+/**
+ * Runtime guard (handy for debugging / devtools).
+ */
+export function isQueryKey(v) {
+    return typeof v === "string" || Array.isArray(v);
+}
+function escapeKeyString(s) {
+    // No replaceAll: keep ES2020 typing compatibility.
+    // Escape characters used by our encoding format: \ ; | :
+    return s
+        .split("\\")
+        .join("\\\\")
+        .split(";")
+        .join("\\;")
+        .split("|")
+        .join("\\|")
+        .split(":")
+        .join("\\:");
+}
+function encodeKeyPart(v) {
+    switch (typeof v) {
+        case "string":
+            return "str:" + escapeKeyString(v);
+        case "number":
+            if (Object.is(v, -0))
+                return "num:-0";
+            if (Number.isNaN(v))
+                return "num:NaN";
+            return "num:" + String(v);
+        case "boolean":
+            return "bool:" + (v ? "1" : "0");
+        case "undefined":
+            return "undef";
+        case "symbol":
+            // Symbol descriptions are not guaranteed unique, but this is stable for a single runtime.
+            // For truly stable keys, prefer strings/numbers/booleans.
+            return "sym:" + escapeKeyString(String(v));
+        default:
+            return "null";
+    }
+}

package/dist/core/match.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Multi-branch conditional DOM primitive with per-case lifetime.
+ *
+ * `match()` renders exactly one case at a time, chosen by `value()`.
+ * It returns a stable DOM "slot" delimited by two comment markers:
+ *
+ *   <!-- match:start --> ...active case... <!-- match:end -->
+ *
+ * Design goals:
+ * - DOM-first: direct Node insertion/removal (no VDOM).
+ * - No "flash": initial case is mounted synchronously.
+ * - Correct reactivity: the reactive driver tracks only `value()`.
+ * - Isolation: each case runs inside its own `Scope`, so effects/listeners/timers
+ *   created by a case are disposed when that case unmounts.
+ * - Safety: swaps are scheduled via microtask to avoid accidental dependency
+ *   tracking from inside the case render function.
+ *
+ * Cases:
+ * - `cases[v]` runs when `value()` equals `v`.
+ * - `cases["_"]` is an optional fallback when there is no exact match.
+ */
+export declare function match<T extends string | number | symbol>(value: () => T, cases: Record<T | "_", () => Node | Node[]>): DocumentFragment;

package/dist/core/match.js

@@ -0,0 +1,175 @@
+import { effect } from "./signal.js";
+import { createScope, getCurrentScope, isScopeDisposed, withScope } from "./scope.js";
+import { scheduleMicrotask } from "./scheduler.js";
+/**
+ * Multi-branch conditional DOM primitive with per-case lifetime.
+ *
+ * `match()` renders exactly one case at a time, chosen by `value()`.
+ * It returns a stable DOM "slot" delimited by two comment markers:
+ *
+ *   <!-- match:start --> ...active case... <!-- match:end -->
+ *
+ * Design goals:
+ * - DOM-first: direct Node insertion/removal (no VDOM).
+ * - No "flash": initial case is mounted synchronously.
+ * - Correct reactivity: the reactive driver tracks only `value()`.
+ * - Isolation: each case runs inside its own `Scope`, so effects/listeners/timers
+ *   created by a case are disposed when that case unmounts.
+ * - Safety: swaps are scheduled via microtask to avoid accidental dependency
+ *   tracking from inside the case render function.
+ *
+ * Cases:
+ * - `cases[v]` runs when `value()` equals `v`.
+ * - `cases["_"]` is an optional fallback when there is no exact match.
+ */
+export function match(value, cases) {
+    /** Stable range markers that define the insertion point. */
+    const start = document.createComment("match:start");
+    const end = document.createComment("match:end");
+    /** Nodes currently mounted between `start` and `end`. */
+    let currentNodes = [];
+    /** Scope owning the currently mounted case (disposed on swap). */
+    let caseScope = null;
+    /** Last resolved case key (exact match or "_"). */
+    let lastKey = undefined;
+    /** Microtask coalescing: allow only one pending swap per tick. */
+    let swapScheduled = false;
+    let pendingKey = undefined;
+    /** Parent scope captured at creation time (if any). */
+    const parentScope = getCurrentScope();
+    const resolveParentScope = () => {
+        if (!parentScope)
+            return null;
+        return isScopeDisposed(parentScope) ? null : parentScope;
+    };
+    /**
+     * Guard to prevent "orphan" microtasks from touching DOM after this match()
+     * is disposed by a parent scope.
+     */
+    let disposed = false;
+    /** Own-property check (works with symbols and ignores prototype chain). */
+    const has = (k) => Object.prototype.hasOwnProperty.call(cases, k);
+    /**
+     * Unmount current case:
+     * - Dispose scope to run cleanups (effects/listeners/timers).
+     * - Remove DOM nodes currently mounted in the slot.
+     */
+    const clear = () => {
+        if (caseScope) {
+            caseScope.dispose();
+            caseScope = null;
+        }
+        for (const n of currentNodes) {
+            if (n.parentNode)
+                n.parentNode.removeChild(n);
+        }
+        currentNodes = [];
+    };
+    /**
+     * Mount nodes right before the end marker and bind them to `scope`.
+     * Keeping the markers stable makes swaps predictable and cheap.
+     */
+    const mount = (nodes, scope) => {
+        currentNodes = nodes;
+        caseScope = scope;
+        end.before(...nodes);
+    };
+    /**
+     * Resolve a runtime value to an actual render key:
+     * - exact match if present,
+     * - otherwise "_" fallback if present,
+     * - otherwise throws (explicit + debuggable failure).
+     */
+    const resolveKey = (v) => {
+        const key = (has(v) ? v : "_");
+        if (!has(key)) {
+            throw new Error(`No case found for value: ${String(v)} (and no "_" fallback)`);
+        }
+        return key;
+    };
+    /**
+     * Swap the mounted DOM to the given key.
+     * This function is intentionally called outside reactive tracking.
+     *
+     * Important: the case render function runs inside a fresh `Scope`,
+     * so anything created by that case is automatically cleaned up on swap.
+     */
+    const swap = (key) => {
+        clear();
+        const nextScope = createScope(resolveParentScope());
+        try {
+            const fn = cases[key];
+            if (!fn) {
+                // Should be unreachable if resolveKey is used, but keep it defensive.
+                nextScope.dispose();
+                throw new Error(`No case found for key: ${String(key)}`);
+            }
+            const result = withScope(nextScope, () => fn());
+            if (!result) {
+                // Allow "empty" cases: nothing is mounted, scope is discarded.
+                nextScope.dispose();
+                return;
+            }
+            const nodes = Array.isArray(result) ? result : [result];
+            mount(nodes, nextScope);
+        }
+        catch (err) {
+            // Never leak the newly created scope on errors.
+            nextScope.dispose();
+            throw err;
+        }
+    };
+    /** The returned fragment contains only stable markers; content lives between them. */
+    const frag = document.createDocumentFragment();
+    frag.append(start, end);
+    /**
+     * Initial mount is synchronous to avoid content flash.
+     *
+     * CRITICAL: markers must already be in the fragment before `swap()`,
+     * because `swap()` inserts using `end.before(...)`.
+     */
+    const initialKey = resolveKey(value());
+    lastKey = initialKey;
+    swap(initialKey);
+    /**
+     * Reactive driver:
+     * - Tracks only `value()`.
+     * - If the selected key doesn't change, we do nothing (no remount).
+     * - If it changes, we schedule a microtask swap (coalesced).
+     *
+     * Why microtask?
+     * - It prevents any reads inside a case render function from becoming
+     *   dependencies of this outer effect.
+     */
+    effect(() => {
+        const key = resolveKey(value());
+        if (lastKey === key)
+            return;
+        lastKey = key;
+        pendingKey = key;
+        if (swapScheduled)
+            return;
+        swapScheduled = true;
+        scheduleMicrotask(() => {
+            swapScheduled = false;
+            if (disposed)
+                return;
+            const next = pendingKey;
+            pendingKey = undefined;
+            swap(next);
+        });
+    });
+    /**
+     * If this match() is created inside a parent scope, we auto-cleanup:
+     * - prevent pending microtasks from doing work,
+     * - dispose current case scope,
+     * - remove mounted nodes.
+     */
+    if (parentScope) {
+        parentScope.onCleanup(() => {
+            disposed = true;
+            clear();
+        });
+    }
+    return frag;
+}

package/dist/core/mutation.d.ts

@@ -0,0 +1,55 @@
+import { type QueryKey } from "./key.js";
+export interface MutationConfig<TInput, TResult> {
+    mutate: (signal: AbortSignal, input: TInput) => Promise<TResult>;
+    /**
+     * Optional invalidation (runs on success).
+     * - Tags revalidate all cached resources that registered those tags.
+     * - Keys revalidate a specific cached resource by key.
+     */
+    invalidateTags?: readonly string[];
+    invalidateKeys?: readonly QueryKey[];
+    onSuccess?: (result: TResult, input: TInput) => void;
+    onError?: (error: Error, input: TInput) => void;
+    onSettled?: (input: TInput) => void;
+}
+export interface MutationState<TInput, TResult> {
+    data: () => TResult | null;
+    loading: () => boolean;
+    error: () => Error | null;
+    /**
+     * Runs the mutation.
+     * - Dedupe: if already loading and not forced, it awaits the current run.
+     * - Force: aborts the current run and starts a new request.
+     */
+    run: (input: TInput, opts?: {
+        force?: boolean;
+    }) => Promise<TResult | null>;
+    /**
+     * Resets local mutation state.
+     * Does not affect the query cache.
+     */
+    reset: () => void;
+}
+/**
+ * Mutation primitive (scope-safe).
+ *
+ * Design goals:
+ * - DOM-first friendly: mutations are just async actions with reactive state.
+ * - Scope-safe: abort on scope disposal (best-effort cleanup).
+ * - Dedupe-by-default: concurrent `run()` calls share the same in-flight promise.
+ * - Force re-run: abort the current request and start a new one.
+ * - React Query-like behavior: keep the last successful `data()` until overwritten or reset.
+ *
+ * Semantics:
+ * - Each run uses its own AbortController.
+ * - If a run is aborted:
+ *   - it returns null,
+ *   - it MUST NOT call onSuccess/onError/onSettled,
+ *   - and it MUST NOT overwrite state from a newer run.
+ *
+ * Invalidation:
+ * - Runs only after a successful, non-aborted mutation.
+ * - invalidateTags: revalidates all cached resources registered for those tags.
+ * - invalidateKeys: revalidates specific cached resources by encoded key.
+ */
+export declare function createMutation<TInput, TResult>(cfg: MutationConfig<TInput, TResult>): MutationState<TInput, TResult>;

package/dist/core/mutation.js

@@ -0,0 +1,128 @@
+import { signal } from "./signal.js";
+import { getCurrentScope } from "./scope.js";
+import { encodeKey } from "./key.js";
+import { invalidateResourceCache, invalidateResourceTags } from "./resource.js";
+/**
+ * Mutation primitive (scope-safe).
+ *
+ * Design goals:
+ * - DOM-first friendly: mutations are just async actions with reactive state.
+ * - Scope-safe: abort on scope disposal (best-effort cleanup).
+ * - Dedupe-by-default: concurrent `run()` calls share the same in-flight promise.
+ * - Force re-run: abort the current request and start a new one.
+ * - React Query-like behavior: keep the last successful `data()` until overwritten or reset.
+ *
+ * Semantics:
+ * - Each run uses its own AbortController.
+ * - If a run is aborted:
+ *   - it returns null,
+ *   - it MUST NOT call onSuccess/onError/onSettled,
+ *   - and it MUST NOT overwrite state from a newer run.
+ *
+ * Invalidation:
+ * - Runs only after a successful, non-aborted mutation.
+ * - invalidateTags: revalidates all cached resources registered for those tags.
+ * - invalidateKeys: revalidates specific cached resources by encoded key.
+ */
+export function createMutation(cfg) {
+    const data = signal(null);
+    const loading = signal(false);
+    const error = signal(null);
+    /** In-flight promise for dedupe (represents the latest started run). */
+    let inFlight = null;
+    /** AbortController for the latest started run (used for force + scope cleanup). */
+    let controller = null;
+    /**
+     * If created inside a scope, abort the active run when the scope is disposed.
+     * This prevents orphan network work and avoids updating dead UI.
+     */
+    const scope = getCurrentScope();
+    if (scope) {
+        scope.onCleanup(() => {
+            controller?.abort();
+            controller = null;
+            inFlight = null;
+        });
+    }
+    async function run(input, opts = {}) {
+        /**
+         * Dedupe:
+         * - If a run is already loading and we're not forcing, await the current promise.
+         * - Snapshot `inFlight` to avoid races if a forced run starts mid-await.
+         */
+        if (loading() && !opts.force) {
+            const p0 = inFlight;
+            return (await (p0 ?? Promise.resolve(null)));
+        }
+        /**
+         * Start a new run:
+         * - Abort previous run (if any).
+         * - Create a fresh controller/signal for this run.
+         * - Capture controller identity so older runs cannot clobber newer state.
+         */
+        controller?.abort();
+        controller = new AbortController();
+        const sig = controller.signal;
+        const localController = controller;
+        loading.set(true);
+        error.set(null);
+        inFlight = (async () => {
+            try {
+                const result = await cfg.mutate(sig, input);
+                // Aborted runs never commit state or call callbacks.
+                if (sig.aborted)
+                    return null;
+                data.set(result);
+                cfg.onSuccess?.(result, input);
+                // Invalidate only after a successful, non-aborted mutation.
+                if (cfg.invalidateTags && cfg.invalidateTags.length > 0) {
+                    invalidateResourceTags(cfg.invalidateTags, { revalidate: true, force: true });
+                }
+                if (cfg.invalidateKeys && cfg.invalidateKeys.length > 0) {
+                    for (const k of cfg.invalidateKeys) {
+                        invalidateResourceCache(encodeKey(k), { revalidate: true, force: true });
+                    }
+                }
+                return result;
+            }
+            catch (e) {
+                // Aborted runs are treated as null (no error state, no callbacks).
+                if (sig.aborted)
+                    return null;
+                const err = e instanceof Error ? e : new Error(String(e));
+                error.set(err);
+                cfg.onError?.(err, input);
+                return null;
+            }
+            finally {
+                /**
+                 * Only the latest run is allowed to update `loading`.
+                 *
+                 * Why?
+                 * - If run A is aborted because run B starts, A's finally will still execute.
+                 * - Without this guard, A could flip loading(false) while B is still running.
+                 */
+                const stillCurrent = controller === localController;
+                if (stillCurrent)
+                    loading.set(false);
+                // Keep onSettled consistent with onSuccess/onError: never run it for aborted runs.
+                if (!sig.aborted)
+                    cfg.onSettled?.(input);
+            }
+        })();
+        return await inFlight;
+    }
+    /**
+     * Resets local state and aborts any active run.
+     * Does not touch the resource/query cache.
+     */
+    function reset() {
+        controller?.abort();
+        controller = null;
+        inFlight = null;
+        loading.set(false);
+        error.set(null);
+        data.set(null);
+    }
+    return { data, loading, error, run, reset };
+}

package/dist/core/persist.d.ts

@@ -0,0 +1,63 @@
+import { type Signal } from './signal.js';
+/**
+ * Storage interface (compatible with localStorage, sessionStorage, etc.)
+ */
+export interface StateStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+/**
+ * Serialization interface
+ */
+export interface Serializer<T> {
+    serialize(value: T): string;
+    deserialize(value: string): T;
+}
+/**
+ * Persist options
+ */
+export interface PersistOptions<T> {
+    name: string;
+    storage?: StateStorage;
+    serializer?: Serializer<T>;
+    version?: number;
+    migrate?: (persistedState: unknown, version: number) => T;
+    merge?: 'replace' | 'shallow';
+    onRehydrate?: (state: T) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Dev-server only hint (not used by runtime yet).
+     * Kept for forward-compat with preload injection.
+     */
+    preload?: boolean;
+}
+/**
+ * Create a persisted signal that automatically syncs with storage.
+ */
+export declare function persist<T>(baseSignal: Signal<T>, options: PersistOptions<T>): Signal<T>;
+/**
+ * Helper to create JSON storage wrapper
+ */
+export declare function createJSONStorage(getStorage: () => StateStorage): StateStorage;
+/**
+ * Clear persisted data for a given key
+ */
+export declare function clearPersisted(name: string, storage?: StateStorage): void;
+/**
+ * Options for preload script generation
+ */
+export interface PreloadScriptOptions {
+    storageKey: string;
+    defaultValue: string;
+    target?: 'documentElement' | 'body';
+    attribute?: string;
+    storageType?: 'localStorage' | 'sessionStorage';
+}
+/**
+ * Generate a minimal inline script to prevent FOUC.
+ *
+ * NOTE: Assumes the value in storage was JSON serialized (default serializer).
+ */
+export declare function createPreloadScript(options: PreloadScriptOptions): string;
+export declare function createThemeScript(storageKey: string, defaultTheme?: string): string;