dalila 1.3.1 → 1.3.2

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

@@ -1,72 +1,82 @@
 /**
- * Auto-scoping Context API
+ * Auto-scoping Context API.
  *
- * Simplifica uso de provide/inject removendo necessidade de withScope explícito
- * quando usando patterns comuns.
+ * 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 } from './context.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
- *
- * Se chamado fora de scope, cria um global scope automaticamente
- *
- * @example
- * ```typescript
- * // ✅ ANTES (verboso)
- * const scope = createScope();
- * withScope(scope, () => {
- *   provide(Theme, 'dark');
- * });
+ * Provide with auto-scope.
  *
- * // ✅ DEPOIS (simples)
- * provide(Theme, 'dark'); // 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;
 /**
- * Inject with auto-scope
+ * Provide explicitly in the global root scope.
  *
- * Se chamado fora de scope, tenta buscar no global scope
- * Se não encontrar, lança erro DESCRITIVO
+ * 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;
 /**
- * Shorthand for createScope + withScope
+ * Try to inject a context value with auto-scope.
  *
- * @example
- * ```typescript
- * // ✅ ANTES (verboso)
- * const appScope = createScope();
- * withScope(appScope, () => {
- *   provide(Theme, 'dark');
- *   createApp();
- * });
+ * 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 }`.
  *
- * // ✅ DEPOIS (conciso)
- * scope(() => {
- *   provide(Theme, 'dark');
- *   createApp();
- * });
- * ```
+ * 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;
 };
 /**
- * Create a scoped provider component helper
+ * Provider helper that bundles:
+ * - a dedicated provider scope
+ * - a value created by `setup()`
+ * - registration via `provide()`
  *
- * @example
- * ```typescript
- * const ThemeProvider = createProvider(ThemeContext, () => {
- *   const theme = signal('dark');
- *   return { theme };
- * });
- *
- * const { value, dispose } = ThemeProvider.create();
- * // use value.theme()
- * ```
+ * 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: () => {
@@ -76,11 +86,17 @@ export declare function createProvider<T>(token: ContextToken<T>, setup: () => T
     use: () => T;
 };
 /**
- * Get global scope (for debugging/advanced use)
+ * Returns the global root scope (if it exists).
+ * Intended for debugging/advanced usage only.
  */
 export declare function getGlobalScope(): Scope | null;
 /**
- * Reset global scope (for testing)
+ * 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

@@ -1,23 +1,51 @@
 /**
- * Auto-scoping Context API
+ * Auto-scoping Context API.
  *
- * Simplifica uso de provide/inject removendo necessidade de withScope explícito
- * quando usando patterns comuns.
+ * 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, withScope } from '../core/scope.js';
+import { getCurrentScope, createScope, isScopeDisposed, withScope } from '../core/scope.js';
 import { isInDevMode } from '../core/dev.js';
-import { createContext, provide as rawProvide, inject as rawInject } from './context.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)
- * Usado quando provide/inject são chamados sem scope
+ * Global root scope (lazy initialized).
  *
- * 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.
+ * Used only when `provide()` is called outside a scope.
+ * `inject()` is safe-by-default and never creates this scope.
  */
-let globalRootScope = null;
+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;
@@ -25,7 +53,8 @@ function warnGlobalProvideOnce() {
         return;
     warnedGlobalProvide = true;
     console.warn('[Dalila] provide() called outside a scope. Using a global root scope (auto-scope). ' +
-        'Prefer scope(() => { ... }) for lifecycle-safe cleanup.');
+        'Prefer scope(() => { ... }) or provideGlobal() for explicit globals. ' +
+        'You can also setAutoScopePolicy("throw") to prevent accidental globals.');
 }
 function detachBeforeUnloadListener() {
     if (typeof window === 'undefined')
@@ -37,21 +66,36 @@ function detachBeforeUnloadListener() {
     window.removeEventListener('beforeunload', beforeUnloadHandler);
     beforeUnloadHandler = null;
 }
-// Note: only provide() creates the global scope; inject() never creates it (safe-by-default).
+/**
+ * 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();
+        globalRootScope = createScope(null);
+        setGlobalRootScope(globalRootScope);
         if (typeof window !== 'undefined' && window.addEventListener && !beforeUnloadHandler) {
-            // Cleanup on page unload (browser only)
             beforeUnloadHandler = () => {
                 detachBeforeUnloadListener();
                 try {
-                    globalRootScope?.dispose();
+                    getGlobalRootScope()?.dispose();
                 }
                 catch {
-                    // do not throw during unload
+                    // Do not throw during unload.
                 }
-                globalRootScope = null;
+                setGlobalRootScope(null);
                 warnedGlobalProvide = false;
             };
             window.addEventListener('beforeunload', beforeUnloadHandler);
@@ -60,31 +104,25 @@ function getOrCreateGlobalScope() {
     return globalRootScope;
 }
 /**
- * Provide with auto-scope
- *
- * Se chamado fora de scope, cria um global scope automaticamente
+ * Provide with auto-scope.
  *
- * @example
- * ```typescript
- * // ✅ ANTES (verboso)
- * const scope = createScope();
- * withScope(scope, () => {
- *   provide(Theme, 'dark');
- * });
- *
- * // ✅ DEPOIS (simples)
- * provide(Theme, 'dark'); // 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) {
-        // Inside a scope - use normal provide
         rawProvide(token, value);
     }
     else {
-        // Outside scope - use global scope
-        warnGlobalProvideOnce();
+        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);
@@ -92,55 +130,121 @@ export function provide(token, value) {
     }
 }
 /**
- * Inject with auto-scope
+ * Provide explicitly in the global root scope.
  *
- * Se chamado fora de scope, tenta buscar no global scope
- * Se não encontrar, lança erro DESCRITIVO
+ * 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) {
-    const currentScope = getCurrentScope();
-    if (currentScope) {
-        // Inside a scope - use normal inject
-        try {
-            return rawInject(token);
-        }
-        catch {
-            // Enhanced error message
-            throw new Error(createContextNotFoundError(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;
     }
-    // Outside scope - try global scope
     if (!globalRootScope) {
+        // Check for default value before throwing
+        if (token.defaultValue !== undefined) {
+            return token.defaultValue;
+        }
         throw createInjectOutsideScopeError(token, 'No global scope exists yet.');
     }
-    try {
-        return withScope(globalRootScope, () => rawInject(token));
-    }
-    catch {
+    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));
 }
 /**
- * Shorthand for createScope + withScope
+ * Inject explicitly from the global root scope.
  *
- * @example
- * ```typescript
- * // ✅ ANTES (verboso)
- * const appScope = createScope();
- * withScope(appScope, () => {
- *   provide(Theme, 'dark');
- *   createApp();
- * });
+ * 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 }`.
  *
- * // ✅ DEPOIS (conciso)
- * scope(() => {
- *   provide(Theme, 'dark');
- *   createApp();
- * });
- * ```
+ * Semantics:
+ * - If `fn` throws, the scope is disposed and the error is rethrown.
+ * - Caller owns disposal.
  */
 export function scope(fn) {
-    const newScope = createScope();
+    const parent = getCurrentScope();
+    const newScope = createScope(parent ?? null);
     try {
         const result = withScope(newScope, fn);
         return {
@@ -154,23 +258,18 @@ export function scope(fn) {
     }
 }
 /**
- * Create a scoped provider component helper
- *
- * @example
- * ```typescript
- * const ThemeProvider = createProvider(ThemeContext, () => {
- *   const theme = signal('dark');
- *   return { theme };
- * });
+ * Provider helper that bundles:
+ * - a dedicated provider scope
+ * - a value created by `setup()`
+ * - registration via `provide()`
  *
- * const { value, dispose } = ThemeProvider.create();
- * // use value.theme()
- * ```
+ * Useful for "feature modules" that want to expose a typed dependency with explicit lifetime.
  */
 export function createProvider(token, setup) {
     return {
         create() {
-            const providerScope = createScope();
+            const parent = getCurrentScope();
+            const providerScope = createScope(parent ?? null);
             const value = withScope(providerScope, () => {
                 const result = setup();
                 provide(token, result);
@@ -187,7 +286,7 @@ export function createProvider(token, setup) {
     };
 }
 /**
- * Create enhanced error message for context not found
+ * Builds a descriptive error message for missing contexts inside a scope hierarchy.
  */
 function createContextNotFoundError(token) {
     const contextName = token.name || 'unnamed';
@@ -198,8 +297,19 @@ function createContextNotFoundError(token) {
     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 same hierarchy\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;
 }
@@ -213,21 +323,31 @@ function createInjectOutsideScopeError(token, extra) {
         `Learn more: https://github.com/evertondsvieira/dalila/blob/main/docs/context.md`);
 }
 /**
- * Get global scope (for debugging/advanced use)
+ * Returns the global root scope (if it exists).
+ * Intended for debugging/advanced usage only.
  */
 export function getGlobalScope() {
-    return globalRootScope;
+    return getGlobalRootScope();
 }
 /**
- * Reset global scope (for testing)
+ * 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();
-        globalRootScope = null;
+        setGlobalRootScope(null);
     }
     warnedGlobalProvide = false;
+    autoScopePolicy = "throw";
 }
-// Re-export createContext for convenience
+// 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 {};