dalila 1.3.0 → 1.3.2

package/dist/context/auto-scope.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Auto-scoping Context API.
+ *
+ * Goal:
+ * - Remove the need for explicit `withScope()` in common app code.
+ *
+ * Auto-scope rules:
+ * - `provide()` outside a scope creates a global root scope (warns once in dev).
+ * - `inject()` outside a scope never creates global state; it only reads an existing global root.
+ *
+ * Rationale:
+ * - Apps often want "global-ish" DI without Provider pyramids.
+ * - Still keep things lifecycle-safe: the global scope can be disposed on page unload.
+ */
+import { type Scope } from '../core/scope.js';
+import { createContext, type ContextToken, type TryInjectResult } from './context.js';
+export type AutoScopePolicy = "warn" | "throw" | "silent";
+export declare function setAutoScopePolicy(policy: AutoScopePolicy): void;
+/**
+ * Provide with auto-scope.
+ *
+ * Semantics:
+ * - Inside a scope: behaves like the raw `provide()`.
+ * - Outside a scope: creates/uses the global root scope (warns once in dev).
+ */
+export declare function provide<T>(token: ContextToken<T>, value: T): void;
+/**
+ * Provide explicitly in the global root scope.
+ *
+ * Semantics:
+ * - Always uses the detached global scope (creates if needed).
+ * - Never warns.
+ */
+export declare function provideGlobal<T>(token: ContextToken<T>, value: T): void;
+/**
+ * Inject with auto-scope.
+ *
+ * Semantics:
+ * - Inside a scope: behaves like raw `inject()`, but throws a more descriptive error.
+ * - Outside a scope:
+ *   - If a global scope exists: reads from it (safe-by-default).
+ *   - If no global scope exists: throws with guidance (does NOT create global state).
+ */
+export declare function inject<T>(token: ContextToken<T>): T;
+/**
+ * Try to inject a context value with auto-scope.
+ *
+ * Semantics:
+ * - Returns { found: true, value } when the token is found.
+ * - Returns { found: false, value: undefined } when not found.
+ * - Works both inside and outside scopes (reads global if exists).
+ */
+export declare function tryInject<T>(token: ContextToken<T>): TryInjectResult<T>;
+/**
+ * Inject explicitly from the global root scope.
+ *
+ * Semantics:
+ * - Reads only the global root scope.
+ * - Throws if no global scope exists yet.
+ */
+export declare function injectGlobal<T>(token: ContextToken<T>): T;
+/**
+ * Convenience helper: create a scope, run `fn` inside it, and return `{ result, dispose }`.
+ *
+ * Semantics:
+ * - If `fn` throws, the scope is disposed and the error is rethrown.
+ * - Caller owns disposal.
+ */
+export declare function scope<T>(fn: () => T): {
+    result: T;
+    dispose: () => void;
+};
+/**
+ * Provider helper that bundles:
+ * - a dedicated provider scope
+ * - a value created by `setup()`
+ * - registration via `provide()`
+ *
+ * Useful for "feature modules" that want to expose a typed dependency with explicit lifetime.
+ */
+export declare function createProvider<T>(token: ContextToken<T>, setup: () => T): {
+    create: () => {
+        value: T;
+        dispose: () => void;
+    };
+    use: () => T;
+};
+/**
+ * Returns the global root scope (if it exists).
+ * Intended for debugging/advanced usage only.
+ */
+export declare function getGlobalScope(): Scope | null;
+/**
+ * Returns true if a global root scope exists.
+ */
+export declare function hasGlobalScope(): boolean;
+/**
+ * Resets the global root scope.
+ * Intended for tests to ensure isolation between runs.
+ */
+export declare function resetGlobalScope(): void;
+export { createContext };

package/dist/context/auto-scope.js

@@ -0,0 +1,353 @@
+/**
+ * Auto-scoping Context API.
+ *
+ * Goal:
+ * - Remove the need for explicit `withScope()` in common app code.
+ *
+ * Auto-scope rules:
+ * - `provide()` outside a scope creates a global root scope (warns once in dev).
+ * - `inject()` outside a scope never creates global state; it only reads an existing global root.
+ *
+ * Rationale:
+ * - Apps often want "global-ish" DI without Provider pyramids.
+ * - Still keep things lifecycle-safe: the global scope can be disposed on page unload.
+ */
+import { getCurrentScope, createScope, isScopeDisposed, withScope } from '../core/scope.js';
+import { isInDevMode } from '../core/dev.js';
+import { createContext, provide as rawProvide, tryInject as rawTryInject, debugListAvailableContexts, } from './context.js';
+/**
+ * Symbol key for storing the global root scope.
+ * Using Symbol.for() allows multiple instances of Dalila to share the same global scope,
+ * preventing conflicts when multiple libs use Dalila in the same app.
+ */
+const DALILA_GLOBAL_SCOPE_KEY = Symbol.for('dalila:global-scope');
+/**
+ * Global storage for the root scope using the symbol key.
+ * This allows sharing across multiple Dalila instances.
+ */
+const globalStorage = globalThis;
+/**
+ * Global root scope (lazy initialized).
+ *
+ * Used only when `provide()` is called outside a scope.
+ * `inject()` is safe-by-default and never creates this scope.
+ */
+function getGlobalRootScope() {
+    return globalStorage[DALILA_GLOBAL_SCOPE_KEY] ?? null;
+}
+function setGlobalRootScope(scope) {
+    globalStorage[DALILA_GLOBAL_SCOPE_KEY] = scope;
+}
+/** Dev warning guard so we only warn once per page lifecycle. */
+let warnedGlobalProvide = false;
+/** Browser-only unload handler for global scope cleanup. */
+let beforeUnloadHandler = null;
+let autoScopePolicy = "throw";
+export function setAutoScopePolicy(policy) {
+    autoScopePolicy = policy;
+}
+function warnGlobalProvideOnce() {
+    if (!isInDevMode())
+        return;
+    if (warnedGlobalProvide)
+        return;
+    warnedGlobalProvide = true;
+    console.warn('[Dalila] provide() called outside a scope. Using a global root scope (auto-scope). ' +
+        'Prefer scope(() => { ... }) or provideGlobal() for explicit globals. ' +
+        'You can also setAutoScopePolicy("throw") to prevent accidental globals.');
+}
+function detachBeforeUnloadListener() {
+    if (typeof window === 'undefined')
+        return;
+    if (!beforeUnloadHandler)
+        return;
+    if (!window.removeEventListener)
+        return;
+    window.removeEventListener('beforeunload', beforeUnloadHandler);
+    beforeUnloadHandler = null;
+}
+/**
+ * Returns the global root scope, creating it if needed.
+ *
+ * Notes:
+ * - Only `provide()` is allowed to create the global scope.
+ * - On browsers, we dispose the global scope on `beforeunload` to release resources.
+ * - We intentionally swallow errors during unload to avoid noisy teardown failures.
+ */
+// Note: provideGlobal() can also create this scope explicitly.
+function getOrCreateGlobalScope() {
+    let globalRootScope = getGlobalRootScope();
+    if (globalRootScope && isScopeDisposed(globalRootScope)) {
+        detachBeforeUnloadListener();
+        setGlobalRootScope(null);
+        warnedGlobalProvide = false;
+        globalRootScope = null;
+    }
+    if (!globalRootScope) {
+        globalRootScope = createScope(null);
+        setGlobalRootScope(globalRootScope);
+        if (typeof window !== 'undefined' && window.addEventListener && !beforeUnloadHandler) {
+            beforeUnloadHandler = () => {
+                detachBeforeUnloadListener();
+                try {
+                    getGlobalRootScope()?.dispose();
+                }
+                catch {
+                    // Do not throw during unload.
+                }
+                setGlobalRootScope(null);
+                warnedGlobalProvide = false;
+            };
+            window.addEventListener('beforeunload', beforeUnloadHandler);
+        }
+    }
+    return globalRootScope;
+}
+/**
+ * Provide with auto-scope.
+ *
+ * Semantics:
+ * - Inside a scope: behaves like the raw `provide()`.
+ * - Outside a scope: creates/uses the global root scope (warns once in dev).
+ */
+export function provide(token, value) {
+    const currentScope = getCurrentScope();
+    if (currentScope) {
+        rawProvide(token, value);
+    }
+    else {
+        if (autoScopePolicy === "throw") {
+            throw new Error("[Dalila] provide() called outside a scope. " +
+                "Use scope(() => provide(...)) or provideGlobal() instead.");
+        }
+        if (autoScopePolicy === "warn") {
+            warnGlobalProvideOnce();
+        }
+        const globalScope = getOrCreateGlobalScope();
+        withScope(globalScope, () => {
+            rawProvide(token, value);
+        });
+    }
+}
+/**
+ * Provide explicitly in the global root scope.
+ *
+ * Semantics:
+ * - Always uses the detached global scope (creates if needed).
+ * - Never warns.
+ */
+export function provideGlobal(token, value) {
+    const globalScope = getOrCreateGlobalScope();
+    withScope(globalScope, () => {
+        rawProvide(token, value);
+    });
+}
+/**
+ * Inject with auto-scope.
+ *
+ * Semantics:
+ * - Inside a scope: behaves like raw `inject()`, but throws a more descriptive error.
+ * - Outside a scope:
+ *   - If a global scope exists: reads from it (safe-by-default).
+ *   - If no global scope exists: throws with guidance (does NOT create global state).
+ */
+export function inject(token) {
+    if (getCurrentScope()) {
+        const result = rawTryInject(token);
+        if (result.found)
+            return result.value;
+        throw new Error(createContextNotFoundError(token));
+    }
+    let globalRootScope = getGlobalRootScope();
+    if (globalRootScope && isScopeDisposed(globalRootScope)) {
+        setGlobalRootScope(null);
+        warnedGlobalProvide = false;
+        globalRootScope = null;
+    }
+    if (!globalRootScope) {
+        // Check for default value before throwing
+        if (token.defaultValue !== undefined) {
+            return token.defaultValue;
+        }
+        throw createInjectOutsideScopeError(token, 'No global scope exists yet.');
+    }
+    return withScope(globalRootScope, () => {
+        const result = rawTryInject(token);
+        if (result.found)
+            return result.value;
+        throw createInjectOutsideScopeError(token);
+    });
+}
+/**
+ * Try to inject a context value with auto-scope.
+ *
+ * Semantics:
+ * - Returns { found: true, value } when the token is found.
+ * - Returns { found: false, value: undefined } when not found.
+ * - Works both inside and outside scopes (reads global if exists).
+ */
+export function tryInject(token) {
+    if (getCurrentScope()) {
+        return rawTryInject(token);
+    }
+    let globalRootScope = getGlobalRootScope();
+    if (globalRootScope && isScopeDisposed(globalRootScope)) {
+        setGlobalRootScope(null);
+        warnedGlobalProvide = false;
+        globalRootScope = null;
+    }
+    if (!globalRootScope) {
+        // Check for default value
+        if (token.defaultValue !== undefined) {
+            return { found: true, value: token.defaultValue };
+        }
+        return { found: false, value: undefined };
+    }
+    return withScope(globalRootScope, () => rawTryInject(token));
+}
+/**
+ * Inject explicitly from the global root scope.
+ *
+ * Semantics:
+ * - Reads only the global root scope.
+ * - Throws if no global scope exists yet.
+ */
+export function injectGlobal(token) {
+    let globalRootScope = getGlobalRootScope();
+    if (globalRootScope && isScopeDisposed(globalRootScope)) {
+        setGlobalRootScope(null);
+        warnedGlobalProvide = false;
+        globalRootScope = null;
+    }
+    if (!globalRootScope) {
+        // Check for default value before throwing
+        if (token.defaultValue !== undefined) {
+            return token.defaultValue;
+        }
+        throw new Error("[Dalila] injectGlobal() called but no global scope exists yet. " +
+            "Use provideGlobal() first.");
+    }
+    return withScope(globalRootScope, () => {
+        const result = rawTryInject(token);
+        if (result.found)
+            return result.value;
+        throw new Error("[Dalila] injectGlobal() token not found in global scope. " +
+            "Provide it via provideGlobal() or call inject() inside the correct scope.");
+    });
+}
+/**
+ * Convenience helper: create a scope, run `fn` inside it, and return `{ result, dispose }`.
+ *
+ * Semantics:
+ * - If `fn` throws, the scope is disposed and the error is rethrown.
+ * - Caller owns disposal.
+ */
+export function scope(fn) {
+    const parent = getCurrentScope();
+    const newScope = createScope(parent ?? null);
+    try {
+        const result = withScope(newScope, fn);
+        return {
+            result,
+            dispose: () => newScope.dispose(),
+        };
+    }
+    catch (err) {
+        newScope.dispose();
+        throw err;
+    }
+}
+/**
+ * Provider helper that bundles:
+ * - a dedicated provider scope
+ * - a value created by `setup()`
+ * - registration via `provide()`
+ *
+ * Useful for "feature modules" that want to expose a typed dependency with explicit lifetime.
+ */
+export function createProvider(token, setup) {
+    return {
+        create() {
+            const parent = getCurrentScope();
+            const providerScope = createScope(parent ?? null);
+            const value = withScope(providerScope, () => {
+                const result = setup();
+                provide(token, result);
+                return result;
+            });
+            return {
+                value,
+                dispose: () => providerScope.dispose(),
+            };
+        },
+        use() {
+            return inject(token);
+        },
+    };
+}
+/**
+ * Builds a descriptive error message for missing contexts inside a scope hierarchy.
+ */
+function createContextNotFoundError(token) {
+    const contextName = token.name || 'unnamed';
+    let message = `[Dalila] Context '${contextName}' not found in scope hierarchy.\n\n`;
+    message += `Possible causes:\n`;
+    message += `  1. You forgot to call provide(token, value) in an ancestor scope\n`;
+    message += `  2. You're calling inject() in a child scope, but provide() was in a sibling scope\n`;
+    message += `  3. The scope where provide() was called has already been disposed\n\n`;
+    message += `How to fix:\n`;
+    message += `  • Make sure provide() is called in a parent scope\n`;
+    message += `  • Use scope(() => { provide(...); inject(...); }) to ensure the same hierarchy\n`;
+    message += `  • Check that the scope hasn't been disposed\n\n`;
+    if (isInDevMode()) {
+        const levels = debugListAvailableContexts(8);
+        if (levels.length > 0) {
+            message += `Available 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`;
+            }
+            message += `\n`;
+        }
+    }
+    message += `Learn more: https://github.com/evertondsvieira/dalila/blob/main/docs/context.md`;
+    return message;
+}
+function createInjectOutsideScopeError(token, extra) {
+    const name = token.name || 'unnamed';
+    return new Error(`[Dalila] Context '${name}' not found.\n\n` +
+        (extra ? `${extra}\n` : '') +
+        `You called inject() outside a scope. Either:\n` +
+        `  1. Call provide(token, value) first, or\n` +
+        `  2. Wrap your code in scope(() => { ... })\n\n` +
+        `Learn more: https://github.com/evertondsvieira/dalila/blob/main/docs/context.md`);
+}
+/**
+ * Returns the global root scope (if it exists).
+ * Intended for debugging/advanced usage only.
+ */
+export function getGlobalScope() {
+    return getGlobalRootScope();
+}
+/**
+ * Returns true if a global root scope exists.
+ */
+export function hasGlobalScope() {
+    return getGlobalRootScope() != null;
+}
+/**
+ * Resets the global root scope.
+ * Intended for tests to ensure isolation between runs.
+ */
+export function resetGlobalScope() {
+    detachBeforeUnloadListener();
+    const globalRootScope = getGlobalRootScope();
+    if (globalRootScope) {
+        globalRootScope.dispose();
+        setGlobalRootScope(null);
+    }
+    warnedGlobalProvide = false;
+    autoScopePolicy = "throw";
+}
+// Re-export createContext for convenience.
+export { createContext };

package/dist/context/context.d.ts

@@ -1,7 +1,111 @@
+import { type Scope } from "../core/scope.js";
+/**
+ * Context (Dependency Injection) — scope-based and hierarchical.
+ *
+ * Mental model:
+ * - A context value lives in the current Scope.
+ * - Child scopes can read values provided by ancestors (via Scope.parent chain).
+ * - Values are cleaned up automatically when the owning scope is disposed.
+ *
+ * Constraints (raw API):
+ * - `provide()` MUST be called inside a scope.
+ * - `inject()` MUST be called inside a scope.
+ *
+ * (Auto-scope behavior belongs in `dalila/context` wrapper — not here.)
+ */
+/**
+ * Branded type marker for compile-time type safety.
+ * Using a unique symbol ensures tokens are not interchangeable even if they have the same T.
+ */
+declare const ContextBrand: unique symbol;
+/**
+ * ContextToken:
+ * - `name` is optional (used for debugging/errors)
+ * - `defaultValue` is optional (returned when no provider is found)
+ * - Branded with a unique symbol for type safety
+ */
 export interface ContextToken<T> {
     readonly name?: string;
-    readonly _brand: T;
+    readonly defaultValue?: T;
+    readonly [ContextBrand]: T;
 }
-export declare function createContext<T>(name?: string): ContextToken<T>;
+/**
+ * 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 declare function createContext<T>(name?: string, defaultValue?: T): ContextToken<T>;
+/**
+ * Configure the depth at which context lookup warns about deep hierarchies.
+ * Set to Infinity to disable the warning.
+ */
+export declare function setDeepHierarchyWarnDepth(depth: number): void;
+/**
+ * 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 declare function provide<T>(token: ContextToken<T>, value: T): void;
+/**
+ * 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 declare function inject<T>(token: ContextToken<T>): T;
+/**
+ * Result of tryInject - distinguishes between "not found" and "found with undefined value".
+ */
+export type TryInjectResult<T> = {
+    found: true;
+    value: T;
+} | {
+    found: false;
+    value: undefined;
+};
+/**
+ * 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 declare function tryInject<T>(token: ContextToken<T>): TryInjectResult<T>;
+/**
+ * Inject a context value and return metadata about where it was resolved.
+ */
+export declare function injectMeta<T>(token: ContextToken<T>): {
+    value: T;
+    ownerScope: Scope;
+    depth: number;
+};
+/**
+ * Debug helper: list available context tokens per depth.
+ */
+export declare function debugListAvailableContexts(maxPerLevel?: number): Array<{
+    depth: number;
+    tokens: {
+        name: string;
+        token: ContextToken<any>;
+    }[];
+}>;
+/**
+ * Alias for debugListAvailableContexts (public helper name).
+ */
+export declare function listAvailableContexts(maxPerLevel?: number): Array<{
+    depth: number;
+    tokens: {
+        name: string;
+        token: ContextToken<any>;
+    }[];
+}>;
+export {};