sandly 0.5.2 → 1.0.0

package/dist/index.d.ts

@@ -197,40 +197,6 @@ declare const Tag: {
    * ```
    */
   of: <Id extends TagId>(id: Id) => <T>() => ValueTag<Id, T>;
-  /**
-   * Creates an anonymous value tag with a unique symbol identifier.
-   *
-   * This is useful when you want a tag that's guaranteed to be unique but don't
-   * need a human-readable identifier. Each call creates a new unique symbol,
-   * making it impossible to accidentally create duplicate tags.
-   *
-   * @template T - The type that this tag represents
-   * @returns A value tag with a unique symbol identifier
-   *
-   * @example
-   * ```typescript
-   * interface InternalConfig {
-   *   secretKey: string;
-   * }
-   *
-   * const InternalConfigTag = Tag.for<InternalConfig>();
-   *
-   * // This tag is guaranteed to be unique - no chance of conflicts
-   * container.register(InternalConfigTag, () => ({
-   *   secretKey: generateSecret()
-   * }));
-   * ```
-   *
-   * @example Multiple anonymous tags
-   * ```typescript
-   * const ConfigA = Tag.for<string>();
-   * const ConfigB = Tag.for<string>();
-   *
-   * // These are different tags even though they have the same type
-   * console.log(ConfigA === ConfigB); // false
-   * ```
-   */
-  for: <T>() => ValueTag<symbol, T>;
   /**
    * Creates a base class that can be extended to create service classes with dependency tags.
    *
@@ -301,11 +267,9 @@ declare const Tag: {
    * @example
    * ```typescript
    * const StringTag = Tag.of('myString')<string>();
-   * const SymbolTag = Tag.for<number>();
    * class ServiceClass extends Tag.Service('MyService') {}
    *
    * console.log(Tag.id(StringTag)); // "myString"
-   * console.log(Tag.id(SymbolTag)); // "Symbol()"
    * console.log(Tag.id(ServiceClass)); // "MyService"
    * ```
    *
@@ -353,12 +317,12 @@ type Inject<T extends ValueTag<TagId, unknown>> = T extends ValueTag<any, infer
  */
 type ExtractInjectTag<T> = T extends {
   readonly [InjectSource]?: infer U;
-} ? U : never;
-//#endregion
+} ? U : never; //#endregion
 //#region src/types.d.ts
 type PromiseOrValue<T> = T | Promise<T>;
 type Contravariant<A> = (_: A) => void;
 type Covariant<A> = (_: never) => A;
+
 //#endregion
 //#region src/container.d.ts
 /**
@@ -372,7 +336,7 @@ type Covariant<A> = (_: never) => A;
  * (returning Promise<T>). The container handles both cases transparently.
  *
  * @template T - The type of the service instance being created
- * @template TReg - Union type of all dependencies available in the container
+ * @template TRequires - Union type of all required dependencies
  *
  * @example Synchronous factory
  * ```typescript
@@ -392,7 +356,7 @@ type Covariant<A> = (_: never) => A;
  * };
  * ```
  */
-type Factory<T, TReg extends AnyTag> = (ctx: ResolutionContext<TReg>) => PromiseOrValue<T>;
+type Factory<T, TRequires extends AnyTag> = (ctx: ResolutionContext<TRequires>) => PromiseOrValue<T>;
 /**
  * Type representing a finalizer function used to clean up dependency instances.
  *
@@ -446,7 +410,7 @@ type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
  * lifecycle logic or want to share lifecycle definitions across multiple services.
  *
  * @template T - The instance type
- * @template TReg - Union type of all dependencies available in the container
+ * @template TRequires - Union type of all required dependencies
  *
  * @example Using DependencyLifecycle as an object
  * ```typescript
@@ -524,8 +488,8 @@ type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
  * );
  * ```
  */
-interface DependencyLifecycle<T, TReg extends AnyTag> {
-  create: Factory<T, TReg>;
+interface DependencyLifecycle<T, TRequires extends AnyTag> {
+  create: Factory<T, TRequires>;
   cleanup?: Finalizer<T>;
 }
 /**
@@ -536,7 +500,7 @@ interface DependencyLifecycle<T, TReg extends AnyTag> {
  * - A complete lifecycle object with both factory and finalizer
  *
  * @template T - The dependency tag type
- * @template TReg - Union type of all dependencies available in the container
+ * @template TRequires - Union type of all required dependencies
  *
  * @example Simple factory registration
  * ```typescript
@@ -556,33 +520,37 @@ interface DependencyLifecycle<T, TReg extends AnyTag> {
  * Container.empty().register(DatabaseConnection, spec);
  * ```
  */
-type DependencySpec<T extends AnyTag, TReg extends AnyTag> = Factory<TagType<T>, TReg> | DependencyLifecycle<TagType<T>, TReg>;
+type DependencySpec<T extends AnyTag, TRequires extends AnyTag> = Factory<TagType<T>, TRequires> | DependencyLifecycle<TagType<T>, TRequires>;
 /**
  * Type representing the context available to factory functions during dependency resolution.
  *
  * This type contains only the `resolve` and `resolveAll` methods from the container, which are used to retrieve
  * other dependencies during the creation of a service.
  *
- * @template TReg - Union type of all dependencies available in the container
+ * @template TTags - Union type of all dependencies available in the container
  */
-type ResolutionContext<TReg extends AnyTag> = Pick<IContainer<TReg>, 'resolve' | 'resolveAll'>;
+type ResolutionContext<TTags extends AnyTag> = Pick<IContainer<TTags>, 'resolve' | 'resolveAll'>;
 declare const ContainerTypeId: unique symbol;
 /**
  * Interface representing a container that can register and retrieve dependencies.
  *
- * @template TReg - Union type of all dependencies available in the container
+ * @template TTags - Union type of all dependencies available in the container
  */
-interface IContainer<TReg extends AnyTag = never> {
+interface IContainer<TTags extends AnyTag = never> {
   readonly [ContainerTypeId]: {
-    readonly _TReg: Contravariant<TReg>;
+    readonly _TTags: Contravariant<TTags>;
   };
-  register: <T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>) => IContainer<TReg | T>;
+  register: <T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>) => IContainer<TTags | T>;
   has(tag: AnyTag): boolean;
   exists(tag: AnyTag): boolean;
-  resolve: <T extends TReg>(tag: T) => Promise<TagType<T>>;
-  resolveAll: <const T extends readonly TReg[]>(...tags: T) => Promise<{ [K in keyof T]: TagType<T[K]> }>;
+  resolve: <T extends TTags>(tag: T) => Promise<TagType<T>>;
+  resolveAll: <const T extends readonly TTags[]>(...tags: T) => Promise<{ [K in keyof T]: TagType<T[K]> }>;
   destroy(): Promise<void>;
 }
+/**
+ * Extracts the registered tags (TTags) from a container type.
+ */
+type ContainerTags<C> = C extends IContainer<infer TTags> ? TTags : never;
 /**
  * A type-safe dependency injection container that manages service instantiation,
  * caching, and lifecycle management with support for async dependencies and
@@ -592,7 +560,7 @@ interface IContainer<TReg extends AnyTag = never> {
  * at the type level, ensuring that only registered dependencies can be retrieved
  * and preventing runtime errors.
  *
- * @template TReg - Union type of all registered dependency tags in this container
+ * @template TTags - Union type of all registered dependency tags in this container
  *
  * @example Basic usage with service tags
  * ```typescript
@@ -650,9 +618,9 @@ interface IContainer<TReg extends AnyTag = never> {
  * await c.destroy(); // Calls all finalizers
  * ```
  */
-declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
+declare class Container<TTags extends AnyTag> implements IContainer<TTags> {
   readonly [ContainerTypeId]: {
-    readonly _TReg: Contravariant<TReg>;
+    readonly _TTags: Contravariant<TTags>;
   };
   protected constructor();
   /**
@@ -665,7 +633,7 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * Factory functions for creating dependency instances.
    * @internal
    */
-  protected readonly factories: Map<AnyTag, Factory<unknown, TReg>>;
+  protected readonly factories: Map<AnyTag, Factory<unknown, TTags>>;
   /**
    * Finalizer functions for cleaning up dependencies when the container is destroyed.
    * @internal
@@ -763,7 +731,7 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * );
    * ```
    */
-  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>): Container<TReg | T>;
+  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): Container<TTags | T>;
   /**
    * Checks if a dependency has been registered in the container.
    *
@@ -837,13 +805,13 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * const userService = await c.resolve(UserService);
    * ```
    */
-  resolve<T extends TReg>(tag: T): Promise<TagType<T>>;
+  resolve<T extends TTags>(tag: T): Promise<TagType<T>>;
   /**
    * Internal resolution method that tracks the dependency chain for circular dependency detection.
    * Can be overridden by subclasses (e.g., ScopedContainer) to implement custom resolution logic.
    * @internal
    */
-  protected resolveInternal<T extends TReg>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
+  protected resolveInternal<T extends TTags>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
   /**
    * Resolves multiple dependencies concurrently using Promise.all.
    *
@@ -884,7 +852,7 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * const results = await c.resolveAll(); // Returns empty array
    * ```
    */
-  resolveAll<const T extends readonly TReg[]>(...tags: T): Promise<{ [K in keyof T]: TagType<T[K]> }>;
+  resolveAll<const T extends readonly TTags[]>(...tags: T): Promise<{ [K in keyof T]: TagType<T[K]> }>;
   /**
    * Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
    *
@@ -958,297 +926,142 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    */
   destroy(): Promise<void>;
 }
+
 //#endregion
-//#region src/errors.d.ts
-type ErrorProps = {
-  cause?: unknown;
-  detail?: Record<string, unknown>;
-};
-type ErrorDump = {
-  name: string;
-  message: string;
-  stack?: string;
-  error: {
-    name: string;
-    message: string;
-    detail: Record<string, unknown>;
-    cause?: unknown;
-  };
-};
+//#region src/scoped-container.d.ts
+type Scope = string | symbol;
+declare class ScopedContainer<TTags extends AnyTag> extends Container<TTags> {
+  readonly scope: Scope;
+  private parent;
+  private readonly children;
+  protected constructor(parent: IContainer<TTags> | null, scope: Scope);
+  /**
+   * Creates a new empty scoped container instance.
+   * @param scope - The scope identifier for this container
+   * @returns A new empty ScopedContainer instance with no registered dependencies
+   */
+  static empty(scope: Scope): ScopedContainer<never>;
+  /**
+   * Registers a dependency in the scoped container.
+   *
+   * Overrides the base implementation to return ScopedContainer type
+   * for proper method chaining support.
+   */
+  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TTags>): ScopedContainer<TTags | T>;
+  /**
+   * Checks if a dependency has been registered in this scope or any parent scope.
+   *
+   * This method checks the current scope first, then walks up the parent chain.
+   * Returns true if the dependency has been registered somewhere in the scope hierarchy.
+   */
+  has(tag: AnyTag): boolean;
+  /**
+   * Checks if a dependency has been instantiated in this scope or any parent scope.
+   *
+   * This method checks the current scope first, then walks up the parent chain.
+   * Returns true if the dependency has been instantiated somewhere in the scope hierarchy.
+   */
+  exists(tag: AnyTag): boolean;
+  /**
+   * Retrieves a dependency instance, resolving from the current scope or parent scopes.
+   *
+   * Resolution strategy:
+   * 1. Check cache in current scope
+   * 2. Check if factory exists in current scope - if so, create instance here
+   * 3. Otherwise, delegate to parent scope
+   * 4. If no parent or parent doesn't have it, throw UnknownDependencyError
+   */
+  resolve<T extends TTags>(tag: T): Promise<TagType<T>>;
+  /**
+   * Internal resolution with delegation logic for scoped containers.
+   * @internal
+   */
+  protected resolveInternal<T extends TTags>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
+  /**
+   * Destroys this scoped container and its children, preserving the container structure for reuse.
+   *
+   * This method ensures proper cleanup order while maintaining reusability:
+   * 1. Destroys all child scopes first (they may depend on parent scope dependencies)
+   * 2. Then calls finalizers for dependencies created in this scope
+   * 3. Clears only instance caches - preserves factories, finalizers, and child structure
+   *
+   * Child destruction happens first to ensure dependencies don't get cleaned up
+   * before their dependents.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Creates a child scoped container.
+   *
+   * Child containers inherit access to parent dependencies but maintain
+   * their own scope for new registrations and instance caching.
+   */
+  child(scope: Scope): ScopedContainer<TTags>;
+}
+
+//#endregion
+//#region src/layer.d.ts
 /**
- * Base error class for all library errors.
- *
- * This extends the native Error class to provide consistent error handling
- * and structured error information across the library.
+ * Replaces the TTags type parameter in a container type with a new type.
+ * Preserves the concrete container type (Container, ScopedContainer, or IContainer).
  *
- * @example Catching library errors
- * ```typescript
- * try {
- *   await container.resolve(SomeService);
- * } catch (error) {
- *   if (error instanceof SandlyError) {
- *     console.error('DI Error:', error.message);
- *     console.error('Details:', error.detail);
- *   }
- * }
- * ```
+ * Uses contravariance to detect container types:
+ * - Any ScopedContainer<X> extends ScopedContainer<never>
+ * - Any Container<X> extends Container<never> (but not ScopedContainer<never>)
+ * - Falls back to IContainer for anything else
+ * @internal
  */
-declare class SandlyError extends Error {
-  detail: Record<string, unknown> | undefined;
-  constructor(message: string, {
-    cause,
-    detail
-  }?: ErrorProps);
-  static ensure(error: unknown): SandlyError;
-  dump(): ErrorDump;
-  dumps(): string;
-}
+type WithContainerTags<TContainer, TNewTags extends AnyTag> = TContainer extends ScopedContainer<never> ? ScopedContainer<TNewTags> : TContainer extends Container<never> ? Container<TNewTags> : IContainer<TNewTags>;
 /**
- * Error thrown when attempting to register a dependency that has already been instantiated.
- *
- * This error occurs when calling `container.register()` for a tag that has already been instantiated.
- * Registration must happen before any instantiation occurs, as cached instances would still be used
- * by existing dependencies.
+ * The most generic layer type that accepts any concrete layer.
  */
-declare class DependencyAlreadyInstantiatedError extends SandlyError {}
+type AnyLayer = Layer<any, any>;
 /**
- * Error thrown when attempting to use a container that has been destroyed.
- *
- * This error occurs when calling `container.resolve()`, `container.register()`, or `container.destroy()`
- * on a container that has already been destroyed. It indicates a programming error where the container
- * is being used after it has been destroyed.
+ * The type ID for the Layer interface.
  */
-declare class ContainerDestroyedError extends SandlyError {}
+declare const LayerTypeId: unique symbol;
 /**
- * Error thrown when attempting to retrieve a dependency that hasn't been registered.
+ * A dependency layer represents a reusable, composable unit of dependency registrations.
+ * Layers allow you to organize your dependency injection setup into logical groups
+ * that can be combined and reused across different contexts.
  *
- * This error occurs when calling `container.resolve(Tag)` for a tag that was never
- * registered via `container.register()`. It indicates a programming error where
- * the dependency setup is incomplete.
+ * ## Type Variance
  *
- * @example
- * ```typescript
- * const container = Container.empty(); // Empty container
+ * The Layer interface uses TypeScript's variance annotations to enable safe substitutability:
  *
- * try {
- *   await c.resolve(UnregisteredService); // This will throw
- * } catch (error) {
- *   if (error instanceof UnknownDependencyError) {
- *     console.error('Missing dependency:', error.message);
- *   }
- * }
- * ```
- */
-declare class UnknownDependencyError extends SandlyError {
-  /**
-   * @internal
-   * Creates an UnknownDependencyError for the given tag.
-   *
-   * @param tag - The dependency tag that wasn't found
-   */
-  constructor(tag: AnyTag);
-}
-/**
- * Error thrown when a circular dependency is detected during dependency resolution.
+ * ### TRequires (covariant)
+ * A layer requiring fewer dependencies can substitute one requiring more:
+ * - `Layer<never, X>` can be used where `Layer<A | B, X>` is expected
+ * - Intuition: A service that needs nothing is more flexible than one that needs specific deps
  *
- * This occurs when service A depends on service B, which depends on service A (directly
- * or through a chain of dependencies). The error includes the full dependency chain
- * to help identify the circular reference.
+ * ### TProvides (contravariant)
+ * A layer providing more services can substitute one providing fewer:
+ * - `Layer<X, A | B>` can be used where `Layer<X, A>` is expected
+ * - Intuition: A service that gives you extra things is compatible with expecting fewer things
  *
- * @example Circular dependency scenario
- * ```typescript
- * class ServiceA extends Tag.Service('ServiceA') {}
- * class ServiceB extends Tag.Service('ServiceB') {}
+ * @template TRequires - The union of tags this layer requires to be satisfied by other layers
+ * @template TProvides - The union of tags this layer provides/registers
  *
- * const container = Container.empty()
- *   .register(ServiceA, async (ctx) =>
- *     new ServiceA(await ctx.resolve(ServiceB)) // Depends on B
- *   )
- *   .register(ServiceB, async (ctx) =>
- *     new ServiceB(await ctx.resolve(ServiceA)) // Depends on A - CIRCULAR!
- *   );
+ * @example Basic layer usage
+ * ```typescript
+ * import { layer, Tag, container } from 'sandly';
  *
- * try {
- *   await c.resolve(ServiceA);
- * } catch (error) {
- *   if (error instanceof CircularDependencyError) {
- *     console.error('Circular dependency:', error.message);
- *     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
- *   }
+ * class DatabaseService extends Tag.Service('DatabaseService') {
+ *   query() { return 'data'; }
  * }
- * ```
- */
-declare class CircularDependencyError extends SandlyError {
-  /**
-   * @internal
-   * Creates a CircularDependencyError with the dependency chain information.
-   *
-   * @param tag - The tag where the circular dependency was detected
-   * @param dependencyChain - The chain of dependencies that led to the circular reference
-   */
-  constructor(tag: AnyTag, dependencyChain: AnyTag[]);
-}
-/**
- * Error thrown when a dependency factory function throws an error during instantiation.
- *
- * This wraps the original error with additional context about which dependency
- * failed to be created. The original error is preserved as the `cause` property.
  *
- * When dependencies are nested (A depends on B depends on C), and C's factory throws,
- * you get nested DependencyCreationErrors. Use `getRootCause()` to get the original error.
- *
- * @example Factory throwing error
- * ```typescript
- * class DatabaseService extends Tag.Service('DatabaseService') {}
+ * // Create a layer that provides DatabaseService
+ * const databaseLayer = layer<never, typeof DatabaseService>((container) =>
+ *   container.register(DatabaseService, () => new DatabaseService())
+ * );
  *
- * const container = Container.empty().register(DatabaseService, () => {
- *   throw new Error('Database connection failed');
- * });
+ * // Apply the layer to a container
+ * const container = Container.empty();
+ * const finalContainer = databaseLayer.register(c);
  *
- * try {
- *   await c.resolve(DatabaseService);
- * } catch (error) {
- *   if (error instanceof DependencyCreationError) {
- *     console.error('Failed to create:', error.message);
- *     console.error('Original error:', error.cause);
- *   }
- * }
+ * const db = await finalContainer.resolve(DatabaseService);
  * ```
  *
- * @example Getting root cause from nested errors
- * ```typescript
- * // ServiceA -> ServiceB -> ServiceC (ServiceC throws)
- * try {
- *   await container.resolve(ServiceA);
- * } catch (error) {
- *   if (error instanceof DependencyCreationError) {
- *     console.error('Top-level error:', error.message); // "Error creating instance of ServiceA"
- *     const rootCause = error.getRootCause();
- *     console.error('Root cause:', rootCause); // Original error from ServiceC
- *   }
- * }
- * ```
- */
-declare class DependencyCreationError extends SandlyError {
-  /**
-   * @internal
-   * Creates a DependencyCreationError wrapping the original factory error.
-   *
-   * @param tag - The tag of the dependency that failed to be created
-   * @param error - The original error thrown by the factory function
-   */
-  constructor(tag: AnyTag, error: unknown);
-  /**
-   * Traverses the error chain to find the root cause error.
-   *
-   * When dependencies are nested, each level wraps the error in a DependencyCreationError.
-   * This method unwraps all the layers to get to the original error that started the failure.
-   *
-   * @returns The root cause error (not a DependencyCreationError unless that's the only error)
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   await container.resolve(UserService);
-   * } catch (error) {
-   *   if (error instanceof DependencyCreationError) {
-   *     const rootCause = error.getRootCause();
-   *     console.error('Root cause:', rootCause);
-   *   }
-   * }
-   * ```
-   */
-  getRootCause(): unknown;
-}
-/**
- * Error thrown when one or more finalizers fail during container destruction.
- *
- * This error aggregates multiple finalizer failures that occurred during
- * `container.destroy()`. Even if some finalizers fail, the container cleanup
- * process continues and this error contains details of all failures.
- *
- * @example Handling finalization errors
- * ```typescript
- * try {
- *   await container.destroy();
- * } catch (error) {
- *   if (error instanceof DependencyFinalizationError) {
- *     console.error('Some finalizers failed');
- *     console.error('Error details:', error.detail.errors);
- *   }
- * }
- * ```
- */
-declare class DependencyFinalizationError extends SandlyError {
-  private readonly errors;
-  /**
-   * @internal
-   * Creates a DependencyFinalizationError aggregating multiple finalizer failures.
-   *
-   * @param errors - Array of errors thrown by individual finalizers
-   */
-  constructor(errors: unknown[]);
-  /**
-   * Returns the root causes of the errors that occurred during finalization.
-   *
-   * @returns An array of the errors that occurred during finalization.
-   * You can expect at least one error in the array.
-   */
-  getRootCauses(): unknown[];
-}
-//#endregion
-//#region src/layer.d.ts
-/**
- * The most generic layer type that accepts any concrete layer.
- */
-type AnyLayer = Layer<any, any>;
-/**
- * The type ID for the Layer interface.
- */
-declare const LayerTypeId: unique symbol;
-/**
- * A dependency layer represents a reusable, composable unit of dependency registrations.
- * Layers allow you to organize your dependency injection setup into logical groups
- * that can be combined and reused across different contexts.
- *
- * ## Type Variance
- *
- * The Layer interface uses TypeScript's variance annotations to enable safe substitutability:
- *
- * ### TRequires (covariant)
- * A layer requiring fewer dependencies can substitute one requiring more:
- * - `Layer<never, X>` can be used where `Layer<A | B, X>` is expected
- * - Intuition: A service that needs nothing is more flexible than one that needs specific deps
- *
- * ### TProvides (contravariant)
- * A layer providing more services can substitute one providing fewer:
- * - `Layer<X, A | B>` can be used where `Layer<X, A>` is expected
- * - Intuition: A service that gives you extra things is compatible with expecting fewer things
- *
- * @template TRequires - The union of tags this layer requires to be satisfied by other layers
- * @template TProvides - The union of tags this layer provides/registers
- *
- * @example Basic layer usage
- * ```typescript
- * import { layer, Tag, container } from 'sandly';
- *
- * class DatabaseService extends Tag.Service('DatabaseService') {
- *   query() { return 'data'; }
- * }
- *
- * // Create a layer that provides DatabaseService
- * const databaseLayer = layer<never, typeof DatabaseService>((container) =>
- *   container.register(DatabaseService, () => new DatabaseService())
- * );
- *
- * // Apply the layer to a container
- * const container = Container.empty();
- * const finalContainer = databaseLayer.register(c);
- *
- * const db = await finalContainer.resolve(DatabaseService);
- * ```
- *
- * @example Layer composition with variance
+ * @example Layer composition with variance
  * ```typescript
  * // Layer that requires DatabaseService and provides UserService
  * const userLayer = layer<typeof DatabaseService, typeof UserService>((container) =>
@@ -1296,7 +1109,7 @@ interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
    * // Enhanced container has both ExistingService and myLayer's provisions
    * ```
    */
-  register: <TContainer extends AnyTag>(container: IContainer<TRequires | TContainer>) => IContainer<TRequires | TContainer | TProvides>;
+  register: <TContainer extends IContainer<TRequires>>(container: TContainer) => WithContainerTags<TContainer, ContainerTags<TContainer> | TProvides>;
   /**
    * Provides a dependency layer to this layer, creating a pipeline where the dependency layer's
    * provisions satisfy this layer's requirements. This creates a dependency flow from dependency → this.
@@ -1576,76 +1389,360 @@ declare const Layer: {
    */
   merge<TRequires1 extends AnyTag, TProvides1 extends AnyTag, TRequires2 extends AnyTag, TProvides2 extends AnyTag>(layer1: Layer<TRequires1, TProvides1>, layer2: Layer<TRequires2, TProvides2>): Layer<TRequires1 | TRequires2, TProvides1 | TProvides2>;
 };
+
 //#endregion
-//#region src/scoped-container.d.ts
-type Scope = string | symbol;
-declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
-  readonly scope: Scope;
-  private parent;
-  private readonly children;
-  protected constructor(parent: IContainer<TReg> | null, scope: Scope);
+//#region src/constant.d.ts
+/**
+ * Creates a layer that provides a constant value for a given tag.
+ *
+ * @param tag - The value tag to provide
+ * @param constantValue - The constant value to provide
+ * @returns A layer with no dependencies that provides the constant value
+ *
+ * @example
+ * ```typescript
+ * const ApiKey = Tag.of('ApiKey')<string>();
+ * const DatabaseUrl = Tag.of('DatabaseUrl')<string>();
+ *
+ * const apiKey = constant(ApiKey, 'my-secret-key');
+ * const dbUrl = constant(DatabaseUrl, 'postgresql://localhost:5432/myapp');
+ *
+ * const config = Layer.merge(apiKey, dbUrl);
+ * ```
+ */
+declare function constant<T extends ValueTag<TagId, unknown>>(tag: T, constantValue: TagType<T>): Layer<never, T>;
+
+//#endregion
+//#region src/dependency.d.ts
+/**
+ * Extracts a union type from a tuple of tags.
+ * Returns `never` for empty arrays.
+ * @internal
+ */
+type TagsToUnion<T extends readonly AnyTag[]> = T[number];
+/**
+ * Creates a layer that provides a single dependency with inferred requirements.
+ *
+ * This is a simplified alternative to `layer()` for the common case of defining
+ * a single dependency. Unlike `service()` and `autoService()`, this works with
+ * any tag type (ServiceTag or ValueTag) and doesn't require extending `Tag.Service()`.
+ *
+ * Requirements are passed as an optional array of tags, allowing TypeScript to infer
+ * both the tag type and the requirements automatically - no explicit type
+ * parameters needed.
+ *
+ * @param tag - The tag (ServiceTag or ValueTag) that identifies this dependency
+ * @param spec - Factory function or lifecycle object for creating the dependency
+ * @param requirements - Optional array of dependency tags this dependency requires (defaults to [])
+ * @returns A layer that requires the specified dependencies and provides the tag
+ *
+ * @example Simple dependency without requirements
+ * ```typescript
+ * const Config = Tag.of('Config')<{ apiUrl: string }>();
+ *
+ * // No requirements - can omit the array
+ * const configDep = dependency(Config, () => ({
+ *   apiUrl: process.env.API_URL!
+ * }));
+ * ```
+ *
+ * @example Dependency with requirements
+ * ```typescript
+ * const database = dependency(
+ *   Database,
+ *   async (ctx) => {
+ *     const config = await ctx.resolve(Config);
+ *     const logger = await ctx.resolve(Logger);
+ *     logger.info('Creating database connection');
+ *     return createDb(config.DATABASE);
+ *   },
+ *   [Config, Logger]
+ * );
+ * ```
+ *
+ * @example Dependency with lifecycle (create + cleanup)
+ * ```typescript
+ * const database = dependency(
+ *   Database,
+ *   {
+ *     create: async (ctx) => {
+ *       const config = await ctx.resolve(Config);
+ *       const logger = await ctx.resolve(Logger);
+ *       logger.info('Creating database connection');
+ *       return await createDb(config.DATABASE);
+ *     },
+ *     cleanup: async (db) => {
+ *       await disconnectDb(db);
+ *     },
+ *   },
+ *   [Config, Logger]
+ * );
+ * ```
+ *
+ * @example Comparison with layer()
+ * ```typescript
+ * // Using layer() - verbose, requires explicit type parameters
+ * const database = layer<typeof Config | typeof Logger, typeof Database>(
+ *   (container) =>
+ *     container.register(Database, async (ctx) => {
+ *       const config = await ctx.resolve(Config);
+ *       return createDb(config.DATABASE);
+ *     })
+ * );
+ *
+ * // Using dependency() - cleaner, fully inferred types
+ * const database = dependency(
+ *   Database,
+ *   async (ctx) => {
+ *     const config = await ctx.resolve(Config);
+ *     return createDb(config.DATABASE);
+ *   },
+ *   [Config, Logger]
+ * );
+ * ```
+ */
+declare function dependency<TTag extends AnyTag, TRequirements extends readonly AnyTag[] = []>(tag: TTag, spec: DependencySpec<TTag, TagsToUnion<TRequirements>>, requirements?: TRequirements): Layer<TagsToUnion<TRequirements>, TTag>;
+
+//#endregion
+//#region src/errors.d.ts
+type ErrorDump = {
+  name: string;
+  message: string;
+  stack?: string;
+  detail: Record<string, unknown>;
+  cause?: unknown;
+};
+type SandlyErrorOptions = {
+  cause?: unknown;
+  detail?: Record<string, unknown>;
+};
+/**
+ * Base error class for all library errors.
+ *
+ * This extends the native Error class to provide consistent error handling
+ * and structured error information across the library.
+ *
+ * @example Catching library errors
+ * ```typescript
+ * try {
+ *   await container.resolve(SomeService);
+ * } catch (error) {
+ *   if (error instanceof SandlyError) {
+ *     console.error('DI Error:', error.message);
+ *     console.error('Details:', error.detail);
+ *   }
+ * }
+ * ```
+ */
+declare class SandlyError extends Error {
+  detail: Record<string, unknown> | undefined;
+  constructor(message: string, {
+    cause,
+    detail
+  }?: SandlyErrorOptions);
+  static ensure(error: unknown): SandlyError;
+  dump(): ErrorDump;
+  dumps(): string;
   /**
-   * Creates a new empty scoped container instance.
-   * @param scope - The scope identifier for this container
-   * @returns A new empty ScopedContainer instance with no registered dependencies
+   * Recursively extract cause chain from any Error.
+   * Handles both AppError (with dump()) and plain Errors (with cause property).
    */
-  static empty(scope: Scope): ScopedContainer<never>;
+  private dumpCause;
+}
+/**
+ * Error thrown when attempting to register a dependency that has already been instantiated.
+ *
+ * This error occurs when calling `container.register()` for a tag that has already been instantiated.
+ * Registration must happen before any instantiation occurs, as cached instances would still be used
+ * by existing dependencies.
+ */
+declare class DependencyAlreadyInstantiatedError extends SandlyError {}
+/**
+ * Error thrown when attempting to use a container that has been destroyed.
+ *
+ * This error occurs when calling `container.resolve()`, `container.register()`, or `container.destroy()`
+ * on a container that has already been destroyed. It indicates a programming error where the container
+ * is being used after it has been destroyed.
+ */
+declare class ContainerDestroyedError extends SandlyError {}
+/**
+ * Error thrown when attempting to retrieve a dependency that hasn't been registered.
+ *
+ * This error occurs when calling `container.resolve(Tag)` for a tag that was never
+ * registered via `container.register()`. It indicates a programming error where
+ * the dependency setup is incomplete.
+ *
+ * @example
+ * ```typescript
+ * const container = Container.empty(); // Empty container
+ *
+ * try {
+ *   await c.resolve(UnregisteredService); // This will throw
+ * } catch (error) {
+ *   if (error instanceof UnknownDependencyError) {
+ *     console.error('Missing dependency:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class UnknownDependencyError extends SandlyError {
   /**
-   * Registers a dependency in the scoped container.
+   * @internal
+   * Creates an UnknownDependencyError for the given tag.
    *
-   * Overrides the base implementation to return ScopedContainer type
-   * for proper method chaining support.
+   * @param tag - The dependency tag that wasn't found
    */
-  register<T extends AnyTag>(tag: T, spec: DependencySpec<T, TReg>): ScopedContainer<TReg | T>;
+  constructor(tag: AnyTag);
+}
+/**
+ * Error thrown when a circular dependency is detected during dependency resolution.
+ *
+ * This occurs when service A depends on service B, which depends on service A (directly
+ * or through a chain of dependencies). The error includes the full dependency chain
+ * to help identify the circular reference.
+ *
+ * @example Circular dependency scenario
+ * ```typescript
+ * class ServiceA extends Tag.Service('ServiceA') {}
+ * class ServiceB extends Tag.Service('ServiceB') {}
+ *
+ * const container = Container.empty()
+ *   .register(ServiceA, async (ctx) =>
+ *     new ServiceA(await ctx.resolve(ServiceB)) // Depends on B
+ *   )
+ *   .register(ServiceB, async (ctx) =>
+ *     new ServiceB(await ctx.resolve(ServiceA)) // Depends on A - CIRCULAR!
+ *   );
+ *
+ * try {
+ *   await c.resolve(ServiceA);
+ * } catch (error) {
+ *   if (error instanceof CircularDependencyError) {
+ *     console.error('Circular dependency:', error.message);
+ *     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
+ *   }
+ * }
+ * ```
+ */
+declare class CircularDependencyError extends SandlyError {
   /**
-   * Checks if a dependency has been registered in this scope or any parent scope.
+   * @internal
+   * Creates a CircularDependencyError with the dependency chain information.
    *
-   * This method checks the current scope first, then walks up the parent chain.
-   * Returns true if the dependency has been registered somewhere in the scope hierarchy.
+   * @param tag - The tag where the circular dependency was detected
+   * @param dependencyChain - The chain of dependencies that led to the circular reference
    */
-  has(tag: AnyTag): boolean;
+  constructor(tag: AnyTag, dependencyChain: AnyTag[]);
+}
+/**
+ * Error thrown when a dependency factory function throws an error during instantiation.
+ *
+ * This wraps the original error with additional context about which dependency
+ * failed to be created. The original error is preserved as the `cause` property.
+ *
+ * When dependencies are nested (A depends on B depends on C), and C's factory throws,
+ * you get nested DependencyCreationErrors. Use `getRootCause()` to get the original error.
+ *
+ * @example Factory throwing error
+ * ```typescript
+ * class DatabaseService extends Tag.Service('DatabaseService') {}
+ *
+ * const container = Container.empty().register(DatabaseService, () => {
+ *   throw new Error('Database connection failed');
+ * });
+ *
+ * try {
+ *   await c.resolve(DatabaseService);
+ * } catch (error) {
+ *   if (error instanceof DependencyCreationError) {
+ *     console.error('Failed to create:', error.message);
+ *     console.error('Original error:', error.cause);
+ *   }
+ * }
+ * ```
+ *
+ * @example Getting root cause from nested errors
+ * ```typescript
+ * // ServiceA -> ServiceB -> ServiceC (ServiceC throws)
+ * try {
+ *   await container.resolve(ServiceA);
+ * } catch (error) {
+ *   if (error instanceof DependencyCreationError) {
+ *     console.error('Top-level error:', error.message); // "Error creating instance of ServiceA"
+ *     const rootCause = error.getRootCause();
+ *     console.error('Root cause:', rootCause); // Original error from ServiceC
+ *   }
+ * }
+ * ```
+ */
+declare class DependencyCreationError extends SandlyError {
   /**
-   * Checks if a dependency has been instantiated in this scope or any parent scope.
+   * @internal
+   * Creates a DependencyCreationError wrapping the original factory error.
    *
-   * This method checks the current scope first, then walks up the parent chain.
-   * Returns true if the dependency has been instantiated somewhere in the scope hierarchy.
+   * @param tag - The tag of the dependency that failed to be created
+   * @param error - The original error thrown by the factory function
    */
-  exists(tag: AnyTag): boolean;
+  constructor(tag: AnyTag, error: unknown);
   /**
-   * Retrieves a dependency instance, resolving from the current scope or parent scopes.
+   * Traverses the error chain to find the root cause error.
    *
-   * Resolution strategy:
-   * 1. Check cache in current scope
-   * 2. Check if factory exists in current scope - if so, create instance here
-   * 3. Otherwise, delegate to parent scope
-   * 4. If no parent or parent doesn't have it, throw UnknownDependencyError
+   * When dependencies are nested, each level wraps the error in a DependencyCreationError.
+   * This method unwraps all the layers to get to the original error that started the failure.
+   *
+   * @returns The root cause error (not a DependencyCreationError unless that's the only error)
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await container.resolve(UserService);
+   * } catch (error) {
+   *   if (error instanceof DependencyCreationError) {
+   *     const rootCause = error.getRootCause();
+   *     console.error('Root cause:', rootCause);
+   *   }
+   * }
+   * ```
    */
-  resolve<T extends TReg>(tag: T): Promise<TagType<T>>;
+  getRootCause(): unknown;
+}
+/**
+ * Error thrown when one or more finalizers fail during container destruction.
+ *
+ * This error aggregates multiple finalizer failures that occurred during
+ * `container.destroy()`. Even if some finalizers fail, the container cleanup
+ * process continues and this error contains details of all failures.
+ *
+ * @example Handling finalization errors
+ * ```typescript
+ * try {
+ *   await container.destroy();
+ * } catch (error) {
+ *   if (error instanceof DependencyFinalizationError) {
+ *     console.error('Some finalizers failed');
+ *     console.error('Error details:', error.detail.errors);
+ *   }
+ * }
+ * ```
+ */
+declare class DependencyFinalizationError extends SandlyError {
+  private readonly errors;
   /**
-   * Internal resolution with delegation logic for scoped containers.
    * @internal
-   */
-  protected resolveInternal<T extends TReg>(tag: T, chain: AnyTag[]): Promise<TagType<T>>;
-  /**
-   * Destroys this scoped container and its children, preserving the container structure for reuse.
-   *
-   * This method ensures proper cleanup order while maintaining reusability:
-   * 1. Destroys all child scopes first (they may depend on parent scope dependencies)
-   * 2. Then calls finalizers for dependencies created in this scope
-   * 3. Clears only instance caches - preserves factories, finalizers, and child structure
+   * Creates a DependencyFinalizationError aggregating multiple finalizer failures.
    *
-   * Child destruction happens first to ensure dependencies don't get cleaned up
-   * before their dependents.
+   * @param errors - Array of errors thrown by individual finalizers
    */
-  destroy(): Promise<void>;
+  constructor(errors: unknown[]);
   /**
-   * Creates a child scoped container.
+   * Returns the root causes of the errors that occurred during finalization.
    *
-   * Child containers inherit access to parent dependencies but maintain
-   * their own scope for new registrations and instance caching.
+   * @returns An array of the errors that occurred during finalization.
+   * You can expect at least one error in the array.
    */
-  child(scope: Scope): ScopedContainer<TReg>;
+  getRootCauses(): unknown[];
 }
+
 //#endregion
 //#region src/service.d.ts
 /**
@@ -1654,6 +1751,13 @@ declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
  * @internal
  */
 type ConstructorParams<T extends ServiceTag<TagId, unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
+/**
+ * Helper to normalize a tag type.
+ * For ServiceTags, this strips away extra static properties of the class constructor,
+ * reducing it to the canonical ServiceTag<Id, Instance> form.
+ * @internal
+ */
+type CanonicalTag<T extends AnyTag> = T extends ServiceTag<infer Id, infer Instance> ? ServiceTag<Id, Instance> : T;
 /**
  * Extracts only dependency tags from a constructor parameter list.
  * Filters out non‑DI parameters.
@@ -1728,7 +1832,7 @@ type ServiceDepsTuple<T extends ServiceTag<TagId, unknown>> = InferConstructorDe
  * );
  * ```
  */
-declare function service<T extends ServiceTag<TagId, unknown>>(tag: T, spec: DependencySpec<T, ServiceDependencies<T>>): Layer<ServiceDependencies<T>, T>;
+declare function service<T extends ServiceTag<TagId, unknown>>(tag: T, spec: DependencySpec<T, ServiceDependencies<T>>): Layer<ServiceDependencies<T>, CanonicalTag<T>>;
 /**
  * Specification for autoService.
  * Can be either a tuple of constructor parameters or an object with dependencies and finalizer.
@@ -1835,27 +1939,7 @@ type AutoServiceSpec<T extends ServiceTag<TagId, unknown>> = ServiceDepsTuple<T>
  * );
  * ```
  */
-declare function autoService<T extends ServiceTag<TagId, unknown>>(tag: T, spec: AutoServiceSpec<T>): Layer<ServiceDependencies<T>, T>;
-//#endregion
-//#region src/value.d.ts
-/**
- * Creates a layer that provides a constant value for a given tag.
- *
- * @param tag - The value tag to provide
- * @param constantValue - The constant value to provide
- * @returns A layer with no dependencies that provides the constant value
- *
- * @example
- * ```typescript
- * const ApiKey = Tag.of('ApiKey')<string>();
- * const DatabaseUrl = Tag.of('DatabaseUrl')<string>();
- *
- * const apiKey = value(ApiKey, 'my-secret-key');
- * const dbUrl = value(DatabaseUrl, 'postgresql://localhost:5432/myapp');
- *
- * const config = Layer.merge(apiKey, dbUrl);
- * ```
- */
-declare function value<T extends ValueTag<TagId, unknown>>(tag: T, constantValue: TagType<T>): Layer<never, T>;
+declare function autoService<T extends ServiceTag<TagId, unknown>>(tag: T, spec: AutoServiceSpec<T>): Layer<ServiceDependencies<T>, CanonicalTag<T>>;
+
 //#endregion
-export { type AnyLayer, type AnyTag, CircularDependencyError, Container, ContainerDestroyedError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, type DependencyLifecycle, type DependencySpec, type Factory, type Finalizer, type IContainer, type Inject, InjectSource, Layer, type PromiseOrValue, type ResolutionContext, SandlyError, type Scope, ScopedContainer, type ServiceDependencies, type ServiceDepsTuple, type ServiceTag, Tag, type TagType, UnknownDependencyError, type ValueTag, autoService, layer, service, value };
+export { AnyLayer, AnyTag, CircularDependencyError, Container, ContainerDestroyedError, ContainerTags, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, DependencyLifecycle, DependencySpec, Factory, Finalizer, IContainer, Inject, InjectSource, Layer, PromiseOrValue, ResolutionContext, SandlyError, Scope, ScopedContainer, ServiceDependencies, ServiceDepsTuple, ServiceTag, Tag, TagType, UnknownDependencyError, ValueTag, autoService, constant, dependency, layer, service };