dalila 1.3.1 → 1.3.2

package/dist/context/context.js

@@ -1,66 +1,283 @@
-import { getCurrentScope } from '../core/scope.js';
-export function createContext(name) {
-    return { name };
+import { getCurrentScope } from "../core/scope.js";
+import { isInDevMode } from "../core/dev.js";
+/**
+ * Create a new context token.
+ *
+ * Notes:
+ * - Tokens are identity-based: the same token instance is the key.
+ * - `name` is for developer-facing errors and debugging only.
+ * - `defaultValue` is returned by inject/tryInject when no provider is found.
+ */
+export function createContext(name, defaultValue) {
+    return { name, defaultValue };
 }
+let globalRevision = 0;
+let warnedDeepHierarchy = false;
+/**
+ * Configurable deep hierarchy warning threshold.
+ */
+let deepHierarchyWarnDepth = 50;
+/**
+ * Configure the depth at which context lookup warns about deep hierarchies.
+ * Set to Infinity to disable the warning.
+ */
+export function setDeepHierarchyWarnDepth(depth) {
+    deepHierarchyWarnDepth = depth;
+}
+function bumpRevision() {
+    globalRevision++;
+}
+function maybeWarnDeepHierarchy(depth) {
+    if (!isInDevMode())
+        return;
+    if (warnedDeepHierarchy)
+        return;
+    if (depth < deepHierarchyWarnDepth)
+        return;
+    warnedDeepHierarchy = true;
+    console.warn(`[Dalila] Context lookup traversed ${depth} parent scopes. ` +
+        `Consider flattening scope hierarchy or caching static contexts.`);
+}
+/**
+ * Per-scope registry that stores context values and links to a parent registry.
+ *
+ * Lookup:
+ * - `get()` checks current registry first.
+ * - If not found, it delegates to the parent registry (if any).
+ */
 class ContextRegistry {
-    constructor(parent) {
+    constructor(ownerScope, parent) {
         this.contexts = new Map();
+        this.resolveCache = new Map();
+        this.ownerScope = ownerScope;
         this.parent = parent;
     }
     set(token, value) {
         this.contexts.set(token, { token, value });
+        this.resolveCache.delete(token);
     }
     get(token) {
-        const value = this.contexts.get(token);
-        if (value !== undefined) {
-            return value.value;
+        const res = this.resolve(token);
+        return res ? res.value : undefined;
+    }
+    resolve(token) {
+        const cached = this.resolveCache.get(token);
+        if (cached && cached.rev === globalRevision)
+            return cached.res;
+        const hit = this.contexts.get(token);
+        if (hit !== undefined) {
+            const res = { value: hit.value, ownerScope: this.ownerScope, depth: 0 };
+            this.resolveCache.set(token, { rev: globalRevision, res });
+            return res;
         }
         if (this.parent) {
-            return this.parent.get(token);
+            const parentRes = this.parent.resolve(token);
+            if (parentRes) {
+                const res = {
+                    value: parentRes.value,
+                    ownerScope: parentRes.ownerScope,
+                    depth: parentRes.depth + 1,
+                };
+                this.resolveCache.set(token, { rev: globalRevision, res });
+                return res;
+            }
         }
+        this.resolveCache.set(token, { rev: globalRevision, res: undefined });
         return undefined;
     }
+    listTokens(maxPerLevel) {
+        const tokens = [];
+        for (const entry of this.contexts.values()) {
+            tokens.push(entry.token);
+            if (maxPerLevel != null && tokens.length >= maxPerLevel)
+                break;
+        }
+        return tokens;
+    }
+    /**
+     * Release references eagerly.
+     *
+     * Safety:
+     * - Scopes in Dalila cascade: disposing a parent scope disposes children,
+     *   so no child scope should outlive a parent registry.
+     */
     clear() {
+        bumpRevision();
         this.contexts.clear();
         this.parent = undefined;
+        this.resolveCache.clear();
     }
 }
+/**
+ * Registry storage keyed by Scope.
+ *
+ * Why WeakMap:
+ * - Avoid keeping scopes alive through registry bookkeeping.
+ */
 const scopeRegistries = new WeakMap();
+/**
+ * Get (or lazily create) the registry for a given scope.
+ *
+ * Key detail:
+ * - Parent linkage is derived from `scope.parent` (captured at createScope time),
+ *   not from `getCurrentScope()`. This makes the hierarchy stable and explicit.
+ *
+ * Cleanup:
+ * - When the scope is disposed, we clear the registry and remove it from the WeakMap.
+ */
 function getScopeRegistry(scope) {
     let registry = scopeRegistries.get(scope);
-    if (!registry) {
-        // Use the scope's parent reference (not getCurrentScope)
-        const parentScope = scope.parent;
-        const parentRegistry = parentScope ? getScopeRegistry(parentScope) : undefined;
-        registry = new ContextRegistry(parentRegistry);
-        scopeRegistries.set(scope, registry);
-        const registryRef = registry;
-        scope.onCleanup(() => {
-            registryRef.clear();
-            scopeRegistries.delete(scope);
-        });
-    }
+    if (registry)
+        return registry;
+    const parentScope = scope.parent;
+    const parentRegistry = parentScope ? getScopeRegistry(parentScope) : undefined;
+    registry = new ContextRegistry(scope, parentRegistry);
+    scopeRegistries.set(scope, registry);
+    const registryRef = registry;
+    scope.onCleanup(() => {
+        registryRef.clear();
+        scopeRegistries.delete(scope);
+    });
     return registry;
 }
+/**
+ * Provide a context value in the current scope.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Overrides any existing value for the same token in this scope.
+ */
 export function provide(token, value) {
     const scope = getCurrentScope();
     if (!scope) {
-        throw new Error('[Dalila] provide() must be called within a scope');
+        throw new Error("[Dalila] provide() must be called within a scope. " +
+            "Use withScope(createScope(), () => provide(...)) or the auto-scope API.");
     }
     const registry = getScopeRegistry(scope);
+    bumpRevision();
     registry.set(token, value);
 }
+/**
+ * Inject a context value from the current scope hierarchy.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Walks up the parent chain until it finds the token.
+ * - If not found and token has a defaultValue, returns that.
+ * - Throws a descriptive error if not found and no default.
+ */
 export function inject(token) {
     const scope = getCurrentScope();
     if (!scope) {
-        throw new Error('[Dalila] inject() must be called within a scope');
+        throw new Error("[Dalila] inject() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    const res = registry.resolve(token);
+    if (res) {
+        maybeWarnDeepHierarchy(res.depth);
+        return res.value;
+    }
+    // Check for default value
+    if (token.defaultValue !== undefined) {
+        return token.defaultValue;
+    }
+    const name = token.name || "unnamed";
+    let message = `[Dalila] Context "${name}" not found in scope hierarchy.`;
+    if (isInDevMode()) {
+        const levels = debugListAvailableContexts(8);
+        if (levels.length > 0) {
+            message += `\n\nAvailable contexts by depth:\n`;
+            for (const level of levels) {
+                const names = level.tokens.map((t) => t.name).join(", ") || "(none)";
+                message += `  depth ${level.depth}: ${names}\n`;
+            }
+        }
+    }
+    throw new Error(message);
+}
+/**
+ * Inject a context value from the current scope hierarchy if present.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Returns { found: true, value } when found.
+ * - Returns { found: false, value: undefined } when not found (or uses defaultValue if available).
+ */
+export function tryInject(token) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] tryInject() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    const res = registry.resolve(token);
+    if (res) {
+        maybeWarnDeepHierarchy(res.depth);
+        return { found: true, value: res.value };
+    }
+    // Check for default value
+    if (token.defaultValue !== undefined) {
+        return { found: true, value: token.defaultValue };
+    }
+    return { found: false, value: undefined };
+}
+/**
+ * Inject a context value and return metadata about where it was resolved.
+ */
+export function injectMeta(token) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] injectMeta() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
     }
-    // The registry.get() method already walks up the parent chain,
-    // so we only need to get the registry for the current scope
     const registry = getScopeRegistry(scope);
-    const value = registry.get(token);
-    if (value !== undefined) {
-        return value;
+    const res = registry.resolve(token);
+    if (!res) {
+        const name = token.name || "unnamed";
+        let message = `[Dalila] Context "${name}" not found in scope hierarchy.`;
+        if (isInDevMode()) {
+            const levels = debugListAvailableContexts(8);
+            if (levels.length > 0) {
+                message += `\n\nAvailable contexts by depth:\n`;
+                for (const level of levels) {
+                    const names = level.tokens.map((t) => t.name).join(", ") || "(none)";
+                    message += `  depth ${level.depth}: ${names}\n`;
+                }
+            }
+        }
+        throw new Error(message);
     }
-    throw new Error(`[Dalila] Context ${token.name || 'unnamed'} not found`);
+    maybeWarnDeepHierarchy(res.depth);
+    return { value: res.value, ownerScope: res.ownerScope, depth: res.depth };
+}
+/**
+ * Debug helper: list available context tokens per depth.
+ */
+export function debugListAvailableContexts(maxPerLevel) {
+    const scope = getCurrentScope();
+    if (!scope)
+        return [];
+    const levels = [];
+    let depth = 0;
+    let current = scope;
+    while (current) {
+        const registry = scopeRegistries.get(current);
+        const tokens = registry
+            ? registry.listTokens(maxPerLevel).map((token) => ({
+                name: token.name || "unnamed",
+                token,
+            }))
+            : [];
+        levels.push({ depth, tokens });
+        current = current.parent;
+        depth++;
+    }
+    return levels;
+}
+/**
+ * Alias for debugListAvailableContexts (public helper name).
+ */
+export function listAvailableContexts(maxPerLevel) {
+    return debugListAvailableContexts(maxPerLevel);
 }

package/dist/context/index.d.ts

@@ -1,3 +1,2 @@
-export { createContext, type ContextToken } from "./context.js";
-export { provide, inject, scope, createProvider, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";
-export { provide as provideGlobalSafe, inject as injectGlobalSafe } from "./auto-scope.js";
+export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, type ContextToken, type TryInjectResult, } from "./context.js";
+export { provide, inject, tryInject, scope, createProvider, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";

package/dist/context/index.js

@@ -1,3 +1,2 @@
-export { createContext } from "./context.js";
-export { provide, inject, scope, createProvider, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";
-export { provide as provideGlobalSafe, inject as injectGlobalSafe } from "./auto-scope.js";
+export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, } from "./context.js";
+export { provide, inject, tryInject, scope, createProvider, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";

package/dist/context/raw.d.ts

@@ -1,2 +1,2 @@
 export { createContext, type ContextToken } from "./context.js";
-export { provide, inject } from "./context.js";
+export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/context/raw.js

@@ -1,2 +1,2 @@
 export { createContext } from "./context.js";
-export { provide, inject } from "./context.js";
+export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/core/index.d.ts

@@ -11,4 +11,4 @@ export * from "./resource.js";
 export * from "./query.js";
 export * from "./mutation.js";
 export * from "./store.js";
-export { batch, measure, mutate } from "./scheduler.js";
+export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";

package/dist/core/index.js

@@ -11,4 +11,4 @@ export * from "./resource.js";
 export * from "./query.js";
 export * from "./mutation.js";
 export * from "./store.js";
-export { batch, measure, mutate } from "./scheduler.js";
+export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";

package/dist/core/match.js

@@ -1,5 +1,5 @@
 import { effect } from "./signal.js";
-import { createScope, getCurrentScope, withScope } from "./scope.js";
+import { createScope, getCurrentScope, isScopeDisposed, withScope } from "./scope.js";
 import { scheduleMicrotask } from "./scheduler.js";
 /**
  * Multi-branch conditional DOM primitive with per-case lifetime.
@@ -35,6 +35,13 @@ export function match(value, cases) {
     /** 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.
@@ -89,7 +96,7 @@ export function match(value, cases) {
      */
     const swap = (key) => {
         clear();
-        const nextScope = createScope();
+        const nextScope = createScope(resolveParentScope());
         try {
             const fn = cases[key];
             if (!fn) {
@@ -158,7 +165,6 @@ export function match(value, cases) {
      * - dispose current case scope,
      * - remove mounted nodes.
      */
-    const parentScope = getCurrentScope();
     if (parentScope) {
         parentScope.onCleanup(() => {
             disposed = true;

package/dist/core/query.js

@@ -1,8 +1,9 @@
 import { computed, effect } from "./signal.js";
-import { getCurrentScope } from "./scope.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).
  *
@@ -25,9 +26,31 @@ import { createMutation } from "./mutation.js";
 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.
          *
@@ -41,8 +64,17 @@ export function createQueryClient() {
         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 && scope) {
+            if (!cleanupRegistered) {
                 cleanupRegistered = true;
                 scope.onCleanup(() => {
                     if (staleTimer != null)
@@ -72,6 +104,7 @@ export function createQueryClient() {
             const k = cfg.key();
             const ck = encodeKey(k);
             let r;
+            const ks = ensureKeyScope(ck);
             const opts = {
                 onError: cfg.onError,
                 onSuccess: (data) => {
@@ -79,11 +112,17 @@ export function createQueryClient() {
                     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).
-            r = createCachedResource(ck, (sig) => cfg.fetch(sig, k), { ...opts, tags: cfg.tags });
+            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. */
@@ -98,17 +137,11 @@ export function createQueryClient() {
         /** Expose the current encoded key as a computed signal. */
         const cacheKeySig = computed(() => encodeKey(cfg.key()));
         /**
-         * Eager kick:
-         * - computed() is lazy
-         * - calling resource() starts the fetch immediately (resource auto-fetches on creation)
+         * 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();
-        /**
-         * Key-change driver:
-         * - computed() only re-evaluates on read
-         * - this effect reads resource() so key changes will recreate the resource
-         *   even if the consumer never reads data() / loading() / error()
-         */
         effect(() => {
             resource();
         });
@@ -125,7 +158,7 @@ export function createQueryClient() {
         return makeQuery(cfg, { persist: false });
     }
     function queryGlobal(cfg) {
-        return makeQuery(cfg, { persist: true });
+        return makeQuery(cfg, { persist: true, warnPersistWithoutTtl: false });
     }
     function mutation(cfg) {
         return createMutation(cfg);

package/dist/core/resource.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from "./signal.js";
+import { type Scope } from "./scope.js";
 /**
  * ResourceOptions:
  * - initialValue: optional initial data (null is allowed by design)
@@ -96,6 +97,40 @@ export type DepSource<D> = (() => D) | ReadonlyArray<Signal<any>> | {
  *   Guard: early-return resolves only if `!loading()`.
  */
 export declare function createDependentResource<T, D>(fetchFn: (signal: AbortSignal, deps: D) => Promise<T>, deps: DepSource<D>, options?: ResourceOptions<T>): ResourceState<T>;
+/**
+ * CacheEntry:
+ * A cached resource plus book-keeping for memory safety and invalidation.
+ *
+ * Fields:
+ * - createdAt/ttlMs: TTL-based expiry.
+ * - tags: tag index for invalidation.
+ * - stale: marker used by invalidation flows.
+ * - refCount: number of active scopes referencing this entry.
+ * - persist: if true, entry may live outside scopes (global cache).
+ * - cacheScope: dedicated scope that owns the underlying resource lifetime.
+ *
+ * Why cacheScope?
+ * - If a cached resource were created in the caller scope, it could be disposed
+ *   prematurely when that scope ends, even though other scopes still reference it.
+ * - We isolate each cache entry in its own scope so the cache controls disposal.
+ */
+type CacheEntry = {
+    resource: ResourceState<any>;
+    createdAt: number;
+    ttlMs?: number;
+    tags: Set<string>;
+    stale: boolean;
+    /** Active scoped users. */
+    refCount: number;
+    /** Explicit "keep global" flag. */
+    persist: boolean;
+    /**
+     * Dedicated scope for this cache entry.
+     * The resource is created inside this scope, isolating it from caller scopes.
+     * When the entry is removed from cache, this scope is disposed.
+     */
+    cacheScope: Scope;
+};
 export interface CachedResourceOptions<T> extends ResourceOptions<T> {
     ttlMs?: number;
     tags?: readonly string[];
@@ -109,6 +144,16 @@ export interface CachedResourceOptions<T> extends ResourceOptions<T> {
      * Leave default as true to teach DX.
      */
     warnIfNoScope?: boolean;
+    /**
+     * Optional dev warning when persist is true without ttlMs.
+     * Leave default as true to teach DX.
+     */
+    warnPersistWithoutTtl?: boolean;
+    /**
+     * Optional scope to run fetchFn inside (for context lookup).
+     * Note: only the sync portion before the first await runs inside this scope.
+     */
+    fetchScope?: Scope | null;
 }
 /**
  * Global cache configuration for memory safety.
@@ -186,4 +231,69 @@ export declare function getResourceCacheKeysByTag(tag: string): string[];
  * - Outside a scope, it warns and returns a normal resource (no interval).
  */
 export declare function createAutoRefreshResource<T>(fetchFn: (signal: AbortSignal) => Promise<T>, refreshInterval: number, options?: ResourceOptions<T>): ResourceState<T>;
+/**
+ * Isolated cache instance for SSR and testing.
+ *
+ * Use this when you need complete cache isolation:
+ * - SSR: each request gets its own cache
+ * - Testing: each test gets fresh state
+ *
+ * Example:
+ * ```ts
+ * const { createCachedResource, clearCache, invalidateKey, getCache } = createIsolatedCache();
+ *
+ * // Use the isolated createCachedResource instead of the global one
+ * const resource = createCachedResource('key', fetchFn);
+ *
+ * // Clean up when done
+ * clearCache();
+ * ```
+ */
+export interface IsolatedCache {
+    /**
+     * Create a cached resource using this isolated cache.
+     */
+    createCachedResource: <T>(key: string, fetchFn: (signal: AbortSignal) => Promise<T>, options?: CachedResourceOptions<T>) => ResourceState<T>;
+    /**
+     * Clear all entries in this isolated cache.
+     */
+    clearCache: (key?: string) => void;
+    /**
+     * Invalidate a specific key in this isolated cache.
+     */
+    invalidateKey: (key: string, opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+    /**
+     * Invalidate all entries with a specific tag.
+     */
+    invalidateTag: (tag: string, opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+    /**
+     * Invalidate all entries with any of the specified tags.
+     */
+    invalidateTags: (tags: readonly string[], opts?: {
+        revalidate?: boolean;
+        force?: boolean;
+    }) => void;
+    /**
+     * Get the underlying cache Map (for debugging/inspection).
+     */
+    getCache: () => Map<string, CacheEntry>;
+    /**
+     * Get cache keys by tag.
+     */
+    getKeysByTag: (tag: string) => string[];
+    /**
+     * Configure cache limits for this instance.
+     */
+    configure: (config: Partial<{
+        maxEntries: number;
+        warnOnEviction: boolean;
+    }>) => void;
+}
+export declare function createIsolatedCache(): IsolatedCache;
 export {};