sandly 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -407,21 +407,21 @@ type Factory<T, TReg extends AnyTag> = (ctx: ResolutionContext<TReg>) => Promise
  *
  * @example Synchronous finalizer
  * ```typescript
- * const finalizer: Finalizer<FileHandle> = (fileHandle) => {
+ * const cleanup: Finalizer<FileHandle> = (fileHandle) => {
  *   fileHandle.close();
  * };
  * ```
  *
  * @example Asynchronous finalizer
  * ```typescript
- * const finalizer: Finalizer<DatabaseConnection> = async (connection) => {
+ * const cleanup: Finalizer<DatabaseConnection> = async (connection) => {
  *   await connection.disconnect();
  * };
  * ```
  *
  * @example Resilient finalizer
  * ```typescript
- * const finalizer: Finalizer<HttpServer> = async (server) => {
+ * const cleanup: Finalizer<HttpServer> = async (server) => {
  *   try {
  *     await server.close();
  *   } catch (error) {
@@ -437,38 +437,97 @@ type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
 /**
  * Type representing a complete dependency lifecycle with both factory and finalizer.
  *
- * This type is used when registering dependencies that need cleanup. Instead of
+ * This interface is used when registering dependencies that need cleanup. Instead of
  * passing separate factory and finalizer parameters, you can pass an object
  * containing both.
  *
- * @template T - The dependency tag type
+ * Since this is an interface, you can also implement it as a class for better
+ * organization and reuse. This is particularly useful when you have complex
+ * 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
  *
- * @example Using DependencyLifecycle for registration
+ * @example Using DependencyLifecycle as an object
  * ```typescript
+ * import { Container, Tag } from 'sandly';
+ *
  * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
  *   async connect() { return; }
  *   async disconnect() { return; }
  * }
  *
- * const lifecycle: DependencyLifecycle<typeof DatabaseConnection, never> = {
- *   factory: async () => {
+ * const lifecycle: DependencyLifecycle<DatabaseConnection, never> = {
+ *   create: async () => {
  *     const conn = new DatabaseConnection();
  *     await conn.connect();
  *     return conn;
  *   },
- *   finalizer: async (conn) => {
+ *   cleanup: async (conn) => {
  *     await conn.disconnect();
  *   }
  * };
  *
  * Container.empty().register(DatabaseConnection, lifecycle);
  * ```
+ *
+ * @example Implementing DependencyLifecycle as a class with dependencies
+ * ```typescript
+ * import { Container, Tag, type ResolutionContext } from 'sandly';
+ *
+ * class Logger extends Tag.Service('Logger') {
+ *   log(message: string) { console.log(message); }
+ * }
+ *
+ * class DatabaseConnection extends Tag.Service('DatabaseConnection') {
+ *   constructor(private logger: Logger, private url: string) { super(); }
+ *   async connect() { this.logger.log('Connected'); }
+ *   async disconnect() { this.logger.log('Disconnected'); }
+ * }
+ *
+ * class DatabaseLifecycle implements DependencyLifecycle<DatabaseConnection, typeof Logger> {
+ *   constructor(private url: string) {}
+ *
+ *   async create(ctx: ResolutionContext<typeof Logger>): Promise<DatabaseConnection> {
+ *     const logger = await ctx.resolve(Logger);
+ *     const conn = new DatabaseConnection(logger, this.url);
+ *     await conn.connect();
+ *     return conn;
+ *   }
+ *
+ *   async cleanup(conn: DatabaseConnection): Promise<void> {
+ *     await conn.disconnect();
+ *   }
+ * }
+ *
+ * const container = Container.empty()
+ *   .register(Logger, () => new Logger())
+ *   .register(DatabaseConnection, new DatabaseLifecycle('postgresql://localhost:5432'));
+ * ```
+ *
+ * @example Class with only factory (no cleanup)
+ * ```typescript
+ * import { Container, Tag } from 'sandly';
+ *
+ * class SimpleService extends Tag.Service('SimpleService') {}
+ *
+ * class SimpleServiceLifecycle implements DependencyLifecycle<SimpleService, never> {
+ *   create(): SimpleService {
+ *     return new SimpleService();
+ *   }
+ *   // cleanup is optional, so it can be omitted
+ * }
+ *
+ * const container = Container.empty().register(
+ *   SimpleService,
+ *   new SimpleServiceLifecycle()
+ * );
+ * ```
  */
-type DependencyLifecycle<T, TReg extends AnyTag> = {
-  factory: Factory<T, TReg>;
-  finalizer: Finalizer<T>;
-};
+interface DependencyLifecycle<T, TReg extends AnyTag> {
+  create: Factory<T, TReg>;
+  cleanup?: Finalizer<T>;
+}
 /**
  * Union type representing all valid dependency registration specifications.
  *
@@ -490,8 +549,8 @@ type DependencyLifecycle<T, TReg extends AnyTag> = {
  * @example Lifecycle registration
  * ```typescript
  * const spec: DependencySpec<typeof DatabaseConnection, never> = {
- *   factory: () => new DatabaseConnection(),
- *   finalizer: (conn) => conn.close()
+ *   create: () => new DatabaseConnection(),
+ *   cleanup: (conn) => conn.close()
  * };
  *
  * Container.empty().register(DatabaseConnection, spec);
@@ -522,7 +581,6 @@ interface IContainer<TReg extends AnyTag = never> {
   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]> }>;
-  merge<TTarget extends AnyTag>(other: IContainer<TTarget>): IContainer<TReg | TTarget>;
   destroy(): Promise<void>;
 }
 /**
@@ -736,8 +794,8 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * and cached for subsequent calls. The method is async-safe and handles concurrent
    * requests for the same dependency correctly.
    *
-   * The method performs circular dependency detection using AsyncLocalStorage to track
-   * the resolution chain across async boundaries.
+   * The method performs circular dependency detection by tracking the resolution chain
+   * through the resolution context.
    *
    * @template T - The dependency tag type (must be registered in this container)
    * @param tag - The dependency tag to retrieve
@@ -780,6 +838,12 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * ```
    */
   resolve<T extends TReg>(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>>;
   /**
    * Resolves multiple dependencies concurrently using Promise.all.
    *
@@ -821,51 +885,16 @@ declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
    * ```
    */
   resolveAll<const T extends readonly TReg[]>(...tags: T): Promise<{ [K in keyof T]: TagType<T[K]> }>;
-  /**
-   * Copies all registrations from this container to a target container.
-   *
-   * @internal
-   * @param target - The container to copy registrations to
-   * @throws {ContainerDestroyedError} If this container has been destroyed
-   */
-  copyTo<TTarget extends AnyTag>(target: Container<TTarget>): void;
-  /**
-   * Creates a new container by merging this container's registrations with another container.
-   *
-   * This method creates a new container that contains all registrations from both containers.
-   * If there are conflicts (same dependency registered in both containers), this
-   * container's registration will take precedence.
-   *
-   * **Important**: Only the registrations are copied, not any cached instances.
-   * The new container starts with an empty instance cache.
-   *
-   * @param other - The container to merge with
-   * @returns A new container with combined registrations
-   * @throws {ContainerDestroyedError} If this container has been destroyed
-   *
-   * @example Merging containers
-   * ```typescript
-   * const container1 = Container.empty()
-   *   .register(DatabaseService, () => new DatabaseService());
-   *
-   * const container2 = Container.empty()
-   *   .register(UserService, () => new UserService());
-   *
-   * const merged = container1.merge(container2);
-   * // merged has both DatabaseService and UserService
-   * ```
-   */
-  merge<TTarget extends AnyTag>(other: Container<TTarget>): Container<TReg | TTarget>;
   /**
    * Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
    *
    * **Important: After calling destroy(), the container becomes permanently unusable.**
-   * Any subsequent calls to register(), get(), or destroy() will throw a ContainerError.
+   * Any subsequent calls to register(), get(), or destroy() will throw a DependencyFinalizationError.
    * This ensures proper cleanup and prevents runtime errors from accessing destroyed resources.
    *
    * All finalizers for instantiated dependencies are called concurrently using Promise.allSettled()
    * for maximum cleanup performance.
-   * If any finalizers fail, all errors are collected and a DependencyContainerFinalizationError
+   * If any finalizers fail, all errors are collected and a DependencyFinalizationError
    * is thrown containing details of all failures.
    *
    * **Finalizer Concurrency:** Finalizers run concurrently, so there are no ordering guarantees.
@@ -946,35 +975,34 @@ type ErrorDump = {
     cause?: unknown;
   };
 };
-declare class BaseError extends Error {
-  detail: Record<string, unknown> | undefined;
-  constructor(message: string, {
-    cause,
-    detail
-  }?: ErrorProps);
-  static ensure(error: unknown): BaseError;
-  dump(): ErrorDump;
-  dumps(): string;
-}
 /**
- * Base error class for all dependency container related errors.
+ * Base error class for all library errors.
  *
- * This extends the framework's BaseError to provide consistent error handling
- * and structured error information across the dependency injection system.
+ * This extends the native Error class to provide consistent error handling
+ * and structured error information across the library.
  *
- * @example Catching DI errors
+ * @example Catching library errors
  * ```typescript
  * try {
  *   await container.resolve(SomeService);
  * } catch (error) {
- *   if (error instanceof ContainerError) {
+ *   if (error instanceof SandlyError) {
  *     console.error('DI Error:', error.message);
  *     console.error('Details:', error.detail);
  *   }
  * }
  * ```
  */
-declare class ContainerError extends BaseError {}
+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;
+}
 /**
  * Error thrown when attempting to register a dependency that has already been instantiated.
  *
@@ -982,7 +1010,7 @@ declare class ContainerError extends BaseError {}
  * Registration must happen before any instantiation occurs, as cached instances would still be used
  * by existing dependencies.
  */
-declare class DependencyAlreadyInstantiatedError extends ContainerError {}
+declare class DependencyAlreadyInstantiatedError extends SandlyError {}
 /**
  * Error thrown when attempting to use a container that has been destroyed.
  *
@@ -990,7 +1018,7 @@ declare class DependencyAlreadyInstantiatedError extends ContainerError {}
  * 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 ContainerError {}
+declare class ContainerDestroyedError extends SandlyError {}
 /**
  * Error thrown when attempting to retrieve a dependency that hasn't been registered.
  *
@@ -1011,7 +1039,7 @@ declare class ContainerDestroyedError extends ContainerError {}
  * }
  * ```
  */
-declare class UnknownDependencyError extends ContainerError {
+declare class UnknownDependencyError extends SandlyError {
   /**
    * @internal
    * Creates an UnknownDependencyError for the given tag.
@@ -1050,7 +1078,7 @@ declare class UnknownDependencyError extends ContainerError {
  * }
  * ```
  */
-declare class CircularDependencyError extends ContainerError {
+declare class CircularDependencyError extends SandlyError {
   /**
    * @internal
    * Creates a CircularDependencyError with the dependency chain information.
@@ -1066,6 +1094,9 @@ declare class CircularDependencyError extends ContainerError {
  * 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') {}
@@ -1083,8 +1114,22 @@ declare class CircularDependencyError extends ContainerError {
  *   }
  * }
  * ```
+ *
+ * @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 ContainerError {
+declare class DependencyCreationError extends SandlyError {
   /**
    * @internal
    * Creates a DependencyCreationError wrapping the original factory error.
@@ -1093,6 +1138,27 @@ declare class DependencyCreationError extends ContainerError {
    * @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.
@@ -1113,7 +1179,8 @@ declare class DependencyCreationError extends ContainerError {
  * }
  * ```
  */
-declare class DependencyFinalizationError extends ContainerError {
+declare class DependencyFinalizationError extends SandlyError {
+  private readonly errors;
   /**
    * @internal
    * Creates a DependencyFinalizationError aggregating multiple finalizer failures.
@@ -1121,6 +1188,13 @@ declare class DependencyFinalizationError extends ContainerError {
    * @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
@@ -1547,6 +1621,11 @@ declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
    * 4. If no parent or parent doesn't have it, throw UnknownDependencyError
    */
   resolve<T extends TReg>(tag: T): Promise<TagType<T>>;
+  /**
+   * 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.
    *
@@ -1559,18 +1638,6 @@ declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
    * before their dependents.
    */
   destroy(): Promise<void>;
-  /**
-   * Creates a new scoped container by merging this container's registrations with another container.
-   *
-   * This method overrides the base Container.merge to return a ScopedContainer instead of a regular Container.
-   * The resulting scoped container contains all registrations from both containers and becomes a root scope
-   * (no parent) with the scope name from this container.
-   *
-   * @param other - The container to merge with
-   * @returns A new ScopedContainer with combined registrations
-   * @throws {ContainerDestroyedError} If this container has been destroyed
-   */
-  merge<TTarget extends AnyTag>(other: Container<TTarget>): ScopedContainer<TReg | TTarget>;
   /**
    * Creates a child scoped container.
    *
@@ -1579,49 +1646,6 @@ declare class ScopedContainer<TReg extends AnyTag> extends Container<TReg> {
    */
   child(scope: Scope): ScopedContainer<TReg>;
 }
-/**
- * Converts a regular container into a scoped container, copying all registrations.
- *
- * This function creates a new ScopedContainer instance and copies all factory functions
- * and finalizers from the source container. The resulting scoped container becomes a root
- * scope (no parent) with all the same dependency registrations.
- *
- * **Important**: Only the registrations are copied, not any cached instances.
- * The new scoped container starts with an empty instance cache.
- *
- * @param container - The container to convert to a scoped container
- * @param scope - A string or symbol identifier for this scope (used for debugging)
- * @returns A new ScopedContainer instance with all registrations copied from the source container
- * @throws {ContainerDestroyedError} If the source container has been destroyed
- *
- * @example Converting a regular container to scoped
- * ```typescript
- * import { container, scoped } from 'sandly';
- *
- * const appContainer = Container.empty()
- *   .register(DatabaseService, () => new DatabaseService())
- *   .register(ConfigService, () => new ConfigService());
- *
- * const scopedAppContainer = scoped(appContainer, 'app');
- *
- * // Create child scopes
- * const requestContainer = scopedAppContainer.child('request');
- * ```
- *
- * @example Copying complex registrations
- * ```typescript
- * const baseContainer = Container.empty()
- *   .register(DatabaseService, () => new DatabaseService())
- *   .register(UserService, {
- *     factory: async (ctx) => new UserService(await ctx.resolve(DatabaseService)),
- *     finalizer: (service) => service.cleanup()
- *   });
- *
- * const scopedContainer = scoped(baseContainer, 'app');
- * // scopedContainer now has all the same registrations with finalizers preserved
- * ```
- */
-declare function scoped<TReg extends AnyTag>(container: Container<TReg>, scope: Scope): ScopedContainer<TReg>;
 //#endregion
 //#region src/service.d.ts
 /**
@@ -1641,7 +1665,7 @@ type ConstructorParams<T extends ServiceTag<TagId, unknown>> = T extends (new (.
  */
 type ExtractConstructorDeps<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
   readonly [ServiceTagIdKey]?: infer Id;
-} ? Id extends TagId ? ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
+} ? Id extends TagId ? T[K] extends (new (...args: unknown[]) => infer Instance) ? ServiceTag<Id, Instance> : ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
 /**
  * Produces an ordered tuple of constructor parameters
  * where dependency parameters are replaced with their tag types,
@@ -1650,7 +1674,7 @@ type ExtractConstructorDeps<T extends readonly unknown[]> = T extends readonly [
  */
 type InferConstructorDepsTuple<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
   readonly [ServiceTagIdKey]?: infer Id;
-} ? Id extends TagId ? ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? T[K] : ExtractInjectTag<T[K]> };
+} ? Id extends TagId ? T[K] extends (new (...args: unknown[]) => infer Instance) ? ServiceTag<Id, Instance> : ServiceTag<Id, T[K]> : never : ExtractInjectTag<T[K]> extends never ? T[K] : ExtractInjectTag<T[K]> };
 /**
  * Union of all dependency tags a ServiceTag constructor requires.
  * Filters out non‑DI parameters.
@@ -1711,7 +1735,7 @@ declare function service<T extends ServiceTag<TagId, unknown>>(tag: T, spec: Dep
  */
 type AutoServiceSpec<T extends ServiceTag<TagId, unknown>> = ServiceDepsTuple<T> | {
   dependencies: ServiceDepsTuple<T>;
-  finalizer?: Finalizer<TagType<T>>;
+  cleanup?: Finalizer<TagType<T>>;
 };
 /**
  * Creates a service layer with automatic dependency injection by inferring constructor parameters.
@@ -1806,7 +1830,7 @@ type AutoServiceSpec<T extends ServiceTag<TagId, unknown>> = ServiceDepsTuple<T>
  *   DatabaseService,
  * 	 {
  * 		dependencies: ['postgresql://localhost:5432/mydb'],
- * 		finalizer: (service) => service.disconnect() // Finalizer for cleanup
+ * 		cleanup: (service) => service.disconnect() // Finalizer for cleanup
  * 	 }
  * );
  * ```
@@ -1834,4 +1858,4 @@ declare function autoService<T extends ServiceTag<TagId, unknown>>(tag: T, spec:
  */
 declare function value<T extends ValueTag<TagId, unknown>>(tag: T, constantValue: TagType<T>): Layer<never, T>;
 //#endregion
-export { type AnyLayer, type AnyTag, CircularDependencyError, Container, ContainerDestroyedError, ContainerError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, type DependencyLifecycle, type DependencySpec, type Factory, type Finalizer, type IContainer, type Inject, InjectSource, Layer, type PromiseOrValue, type ResolutionContext, type Scope, ScopedContainer, type ServiceDependencies, type ServiceDepsTuple, type ServiceTag, Tag, type TagType, UnknownDependencyError, type ValueTag, autoService, layer, scoped, service, value };
+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 };

package/dist/index.js

@@ -1,5 +1,3 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
 //#region src/utils/object.ts
 function hasKey(obj, key) {
 	return obj !== void 0 && obj !== null && (typeof obj === "object" || typeof obj === "function") && key in obj;
@@ -75,7 +73,25 @@ const InjectSource = "sandly/InjectSource";
 
 //#endregion
 //#region src/errors.ts
-var BaseError = class BaseError extends Error {
+/**
+* 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);
+*   }
+* }
+* ```
+*/
+var SandlyError = class SandlyError extends Error {
 	detail;
 	constructor(message, { cause, detail } = {}) {
 		super(message, { cause });
@@ -84,10 +100,10 @@ var BaseError = class BaseError extends Error {
 		if (cause instanceof Error && cause.stack !== void 0) this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
 	}
 	static ensure(error) {
-		return error instanceof BaseError ? error : new BaseError("An unknown error occurred", { cause: error });
+		return error instanceof SandlyError ? error : new SandlyError("An unknown error occurred", { cause: error });
 	}
 	dump() {
-		const cause = this.cause instanceof BaseError ? this.cause.dump().error : this.cause;
+		const cause = this.cause instanceof SandlyError ? this.cause.dump().error : this.cause;
 		const result = {
 			name: this.name,
 			message: this.message,
@@ -106,32 +122,13 @@ var BaseError = class BaseError extends Error {
 	}
 };
 /**
-* Base error class for all dependency container related errors.
-*
-* This extends the framework's BaseError to provide consistent error handling
-* and structured error information across the dependency injection system.
-*
-* @example Catching DI errors
-* ```typescript
-* try {
-*   await container.resolve(SomeService);
-* } catch (error) {
-*   if (error instanceof ContainerError) {
-*     console.error('DI Error:', error.message);
-*     console.error('Details:', error.detail);
-*   }
-* }
-* ```
-*/
-var ContainerError = class extends BaseError {};
-/**
 * 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.
 */
-var DependencyAlreadyInstantiatedError = class extends ContainerError {};
+var DependencyAlreadyInstantiatedError = class extends SandlyError {};
 /**
 * Error thrown when attempting to use a container that has been destroyed.
 *
@@ -139,7 +136,7 @@ var DependencyAlreadyInstantiatedError = class extends ContainerError {};
 * on a container that has already been destroyed. It indicates a programming error where the container
 * is being used after it has been destroyed.
 */
-var ContainerDestroyedError = class extends ContainerError {};
+var ContainerDestroyedError = class extends SandlyError {};
 /**
 * Error thrown when attempting to retrieve a dependency that hasn't been registered.
 *
@@ -160,7 +157,7 @@ var ContainerDestroyedError = class extends ContainerError {};
 * }
 * ```
 */
-var UnknownDependencyError = class extends ContainerError {
+var UnknownDependencyError = class extends SandlyError {
 	/**
 	* @internal
 	* Creates an UnknownDependencyError for the given tag.
@@ -201,7 +198,7 @@ var UnknownDependencyError = class extends ContainerError {
 * }
 * ```
 */
-var CircularDependencyError = class extends ContainerError {
+var CircularDependencyError = class extends SandlyError {
 	/**
 	* @internal
 	* Creates a CircularDependencyError with the dependency chain information.
@@ -223,6 +220,9 @@ var CircularDependencyError = class extends ContainerError {
 * 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') {}
@@ -240,8 +240,22 @@ var CircularDependencyError = class extends ContainerError {
 *   }
 * }
 * ```
+*
+* @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
+*   }
+* }
+* ```
 */
-var DependencyCreationError = class extends ContainerError {
+var DependencyCreationError = class DependencyCreationError extends SandlyError {
 	/**
 	* @internal
 	* Creates a DependencyCreationError wrapping the original factory error.
@@ -255,6 +269,31 @@ var DependencyCreationError = class extends ContainerError {
 			detail: { tag: Tag.id(tag) }
 		});
 	}
+	/**
+	* 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() {
+		let current = this.cause;
+		while (current instanceof DependencyCreationError && current.cause !== void 0) current = current.cause;
+		return current;
+	}
 };
 /**
 * Error thrown when one or more finalizers fail during container destruction.
@@ -275,7 +314,7 @@ var DependencyCreationError = class extends ContainerError {
 * }
 * ```
 */
-var DependencyFinalizationError = class extends ContainerError {
+var DependencyFinalizationError = class extends SandlyError {
 	/**
 	* @internal
 	* Creates a DependencyFinalizationError aggregating multiple finalizer failures.
@@ -283,22 +322,44 @@ var DependencyFinalizationError = class extends ContainerError {
 	* @param errors - Array of errors thrown by individual finalizers
 	*/
 	constructor(errors) {
-		const lambdaErrors = errors.map((error) => BaseError.ensure(error));
+		const lambdaErrors = errors.map((error) => SandlyError.ensure(error));
 		super("Error destroying dependency container", {
 			cause: errors[0],
 			detail: { errors: lambdaErrors.map((error) => error.dump()) }
 		});
+		this.errors = errors;
+	}
+	/**
+	* 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() {
+		return this.errors;
 	}
 };
 
 //#endregion
 //#region src/container.ts
 /**
-* AsyncLocalStorage instance used to track the dependency resolution chain.
-* This enables detection of circular dependencies during async dependency resolution.
+* Internal implementation of ResolutionContext that carries the resolution chain
+* for circular dependency detection.
 * @internal
 */
-const resolutionChain = new AsyncLocalStorage();
+var ResolutionContextImpl = class {
+	constructor(resolveFn) {
+		this.resolveFn = resolveFn;
+	}
+	async resolve(tag) {
+		return this.resolveFn(tag);
+	}
+	async resolveAll(...tags) {
+		const promises = tags.map((tag) => this.resolve(tag));
+		const results = await Promise.all(promises);
+		return results;
+	}
+};
 const ContainerTypeId = Symbol.for("sandly/Container");
 /**
 * A type-safe dependency injection container that manages service instantiation,
@@ -487,8 +548,9 @@ var Container = class Container {
 			this.factories.set(tag, spec);
 			this.finalizers.delete(tag);
 		} else {
-			this.factories.set(tag, spec.factory);
-			this.finalizers.set(tag, spec.finalizer);
+			this.factories.set(tag, spec.create.bind(spec));
+			if (spec.cleanup) this.finalizers.set(tag, spec.cleanup.bind(spec));
+			else this.finalizers.delete(tag);
 		}
 		return this;
 	}
@@ -526,8 +588,8 @@ var Container = class Container {
 	* and cached for subsequent calls. The method is async-safe and handles concurrent
 	* requests for the same dependency correctly.
 	*
-	* The method performs circular dependency detection using AsyncLocalStorage to track
-	* the resolution chain across async boundaries.
+	* The method performs circular dependency detection by tracking the resolution chain
+	* through the resolution context.
 	*
 	* @template T - The dependency tag type (must be registered in this container)
 	* @param tag - The dependency tag to retrieve
@@ -570,21 +632,30 @@ var Container = class Container {
 	* ```
 	*/
 	async resolve(tag) {
+		return this.resolveInternal(tag, []);
+	}
+	/**
+	* 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
+	*/
+	resolveInternal(tag, chain) {
 		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot resolve dependencies from a destroyed container");
 		const cached = this.cache.get(tag);
 		if (cached !== void 0) return cached;
-		const currentChain = resolutionChain.getStore() ?? [];
-		if (currentChain.includes(tag)) throw new CircularDependencyError(tag, currentChain);
+		if (chain.includes(tag)) throw new CircularDependencyError(tag, chain);
 		const factory = this.factories.get(tag);
 		if (factory === void 0) throw new UnknownDependencyError(tag);
-		const instancePromise = resolutionChain.run([...currentChain, tag], async () => {
+		const newChain = [...chain, tag];
+		const context = new ResolutionContextImpl((tag$1) => this.resolveInternal(tag$1, newChain));
+		const instancePromise = (async () => {
 			try {
-				const instance = await factory(this);
+				const instance = await factory(context);
 				return instance;
 			} catch (error) {
 				throw new DependencyCreationError(tag, error);
 			}
-		}).catch((error) => {
+		})().catch((error) => {
 			this.cache.delete(tag);
 			throw error;
 		});
@@ -638,66 +709,15 @@ var Container = class Container {
 		return results;
 	}
 	/**
-	* Copies all registrations from this container to a target container.
-	*
-	* @internal
-	* @param target - The container to copy registrations to
-	* @throws {ContainerDestroyedError} If this container has been destroyed
-	*/
-	copyTo(target) {
-		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot copy registrations from a destroyed container");
-		for (const [tag, factory] of this.factories) {
-			const finalizer = this.finalizers.get(tag);
-			if (finalizer) target.register(tag, {
-				factory,
-				finalizer
-			});
-			else target.register(tag, factory);
-		}
-	}
-	/**
-	* Creates a new container by merging this container's registrations with another container.
-	*
-	* This method creates a new container that contains all registrations from both containers.
-	* If there are conflicts (same dependency registered in both containers), this
-	* container's registration will take precedence.
-	*
-	* **Important**: Only the registrations are copied, not any cached instances.
-	* The new container starts with an empty instance cache.
-	*
-	* @param other - The container to merge with
-	* @returns A new container with combined registrations
-	* @throws {ContainerDestroyedError} If this container has been destroyed
-	*
-	* @example Merging containers
-	* ```typescript
-	* const container1 = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService());
-	*
-	* const container2 = Container.empty()
-	*   .register(UserService, () => new UserService());
-	*
-	* const merged = container1.merge(container2);
-	* // merged has both DatabaseService and UserService
-	* ```
-	*/
-	merge(other) {
-		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot merge from a destroyed container");
-		const merged = new Container();
-		other.copyTo(merged);
-		this.copyTo(merged);
-		return merged;
-	}
-	/**
 	* Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
 	*
 	* **Important: After calling destroy(), the container becomes permanently unusable.**
-	* Any subsequent calls to register(), get(), or destroy() will throw a ContainerError.
+	* Any subsequent calls to register(), get(), or destroy() will throw a DependencyFinalizationError.
 	* This ensures proper cleanup and prevents runtime errors from accessing destroyed resources.
 	*
 	* All finalizers for instantiated dependencies are called concurrently using Promise.allSettled()
 	* for maximum cleanup performance.
-	* If any finalizers fail, all errors are collected and a DependencyContainerFinalizationError
+	* If any finalizers fail, all errors are collected and a DependencyFinalizationError
 	* is thrown containing details of all failures.
 	*
 	* **Finalizer Concurrency:** Finalizers run concurrently, so there are no ordering guarantees.
@@ -960,7 +980,14 @@ var ScopedContainer = class ScopedContainer extends Container {
 	* 4. If no parent or parent doesn't have it, throw UnknownDependencyError
 	*/
 	async resolve(tag) {
-		if (this.factories.has(tag)) return super.resolve(tag);
+		return this.resolveInternal(tag, []);
+	}
+	/**
+	* Internal resolution with delegation logic for scoped containers.
+	* @internal
+	*/
+	resolveInternal(tag, chain) {
+		if (this.factories.has(tag)) return super.resolveInternal(tag, chain);
 		if (this.parent !== null) return this.parent.resolve(tag);
 		throw new UnknownDependencyError(tag);
 	}
@@ -992,24 +1019,6 @@ var ScopedContainer = class ScopedContainer extends Container {
 		if (allFailures.length > 0) throw new DependencyFinalizationError(allFailures);
 	}
 	/**
-	* Creates a new scoped container by merging this container's registrations with another container.
-	*
-	* This method overrides the base Container.merge to return a ScopedContainer instead of a regular Container.
-	* The resulting scoped container contains all registrations from both containers and becomes a root scope
-	* (no parent) with the scope name from this container.
-	*
-	* @param other - The container to merge with
-	* @returns A new ScopedContainer with combined registrations
-	* @throws {ContainerDestroyedError} If this container has been destroyed
-	*/
-	merge(other) {
-		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot merge from a destroyed container");
-		const merged = new ScopedContainer(null, this.scope);
-		other.copyTo(merged);
-		this.copyTo(merged);
-		return merged;
-	}
-	/**
 	* Creates a child scoped container.
 	*
 	* Child containers inherit access to parent dependencies but maintain
@@ -1022,52 +1031,6 @@ var ScopedContainer = class ScopedContainer extends Container {
 		return child;
 	}
 };
-/**
-* Converts a regular container into a scoped container, copying all registrations.
-*
-* This function creates a new ScopedContainer instance and copies all factory functions
-* and finalizers from the source container. The resulting scoped container becomes a root
-* scope (no parent) with all the same dependency registrations.
-*
-* **Important**: Only the registrations are copied, not any cached instances.
-* The new scoped container starts with an empty instance cache.
-*
-* @param container - The container to convert to a scoped container
-* @param scope - A string or symbol identifier for this scope (used for debugging)
-* @returns A new ScopedContainer instance with all registrations copied from the source container
-* @throws {ContainerDestroyedError} If the source container has been destroyed
-*
-* @example Converting a regular container to scoped
-* ```typescript
-* import { container, scoped } from 'sandly';
-*
-* const appContainer = Container.empty()
-*   .register(DatabaseService, () => new DatabaseService())
-*   .register(ConfigService, () => new ConfigService());
-*
-* const scopedAppContainer = scoped(appContainer, 'app');
-*
-* // Create child scopes
-* const requestContainer = scopedAppContainer.child('request');
-* ```
-*
-* @example Copying complex registrations
-* ```typescript
-* const baseContainer = Container.empty()
-*   .register(DatabaseService, () => new DatabaseService())
-*   .register(UserService, {
-*     factory: async (ctx) => new UserService(await ctx.resolve(DatabaseService)),
-*     finalizer: (service) => service.cleanup()
-*   });
-*
-* const scopedContainer = scoped(baseContainer, 'app');
-* // scopedContainer now has all the same registrations with finalizers preserved
-* ```
-*/
-function scoped(container, scope) {
-	const emptyScoped = ScopedContainer.empty(scope);
-	return emptyScoped.merge(container);
-}
 
 //#endregion
 //#region src/service.ts
@@ -1212,14 +1175,14 @@ function service(tag, spec) {
 *   DatabaseService,
 * 	 {
 * 		dependencies: ['postgresql://localhost:5432/mydb'],
-* 		finalizer: (service) => service.disconnect() // Finalizer for cleanup
+* 		cleanup: (service) => service.disconnect() // Finalizer for cleanup
 * 	 }
 * );
 * ```
 */
 function autoService(tag, spec) {
 	if (Array.isArray(spec)) spec = { dependencies: spec };
-	const factory = async (ctx) => {
+	const create = async (ctx) => {
 		const diDeps = [];
 		for (const dep of spec.dependencies) if (Tag.isTag(dep)) diDeps.push(dep);
 		const resolved = await ctx.resolveAll(...diDeps);
@@ -1229,11 +1192,10 @@ function autoService(tag, spec) {
 		else args.push(dep);
 		return new tag(...args);
 	};
-	const finalSpec = spec.finalizer ? {
-		factory,
-		finalizer: spec.finalizer
-	} : factory;
-	return service(tag, finalSpec);
+	return service(tag, {
+		create,
+		cleanup: spec.cleanup
+	});
 }
 
 //#endregion
@@ -1261,4 +1223,4 @@ function value(tag, constantValue) {
 }
 
 //#endregion
-export { CircularDependencyError, Container, ContainerDestroyedError, ContainerError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, InjectSource, Layer, ScopedContainer, Tag, UnknownDependencyError, autoService, layer, scoped, service, value };
+export { CircularDependencyError, Container, ContainerDestroyedError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, InjectSource, Layer, SandlyError, ScopedContainer, Tag, UnknownDependencyError, autoService, layer, service, value };

package/package.json

@@ -1,75 +1,76 @@
 {
-  "name": "sandly",
-  "version": "0.5.0",
-  "keywords": [
-    "typescript",
-    "sandly",
-    "dependency-injection",
-    "dependency-inversion",
-    "injection",
-    "di",
-    "inversion-of-control",
-    "ioc",
-    "container",
-    "layer",
-    "service",
-    "aws",
-    "lambda",
-    "aws-lambda"
-  ],
-  "homepage": "https://github.com/borisrakovan/sandly",
-  "bugs": {
-    "url": "https://github.com/borisrakovan/sandly/issues"
-  },
-  "author": "Boris Rakovan <b.rakovan@gmail.com> (https://github.com/borisrakovan)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/borisrakovan/sandly.git"
-  },
-  "license": "MIT",
-  "files": [
-    "dist"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "@eslint/js": "^9.26.0",
-    "@types/aws-lambda": "^8.10.149",
-    "@types/node": "^22.15.3",
-    "@types/node-fetch": "^2.6.12",
-    "dotenv": "^16.5.0",
-    "esbuild": "^0.25.3",
-    "eslint": "^9.26.0",
-    "node-fetch": "^3.3.2",
-    "prettier": "^3.5.3",
-    "prettier-plugin-organize-imports": "^4.1.0",
-    "ts-node": "^10.9.2",
-    "tsdown": "^0.14.1",
-    "tsx": "^4.19.4",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.38.0",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.1.3",
-    "zod": "^4.0.15"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "clean": "rm -rf dist",
-    "watch": "tsc --watch",
-    "format": "prettier --write \"{src,test}/**/*.ts\"",
-    "format:check": "prettier --check \"{src,test}/**/*.ts\"",
-    "lint": "eslint . --fix",
-    "lint:check": "eslint . --max-warnings=0",
-    "type:check": "tsc --noEmit",
-    "test": "vitest run",
-    "release": "changeset version && changeset publish"
-  }
-}
+	"name": "sandly",
+	"version": "0.5.2",
+	"keywords": [
+		"typescript",
+		"sandly",
+		"dependency-injection",
+		"dependency-inversion",
+		"injection",
+		"di",
+		"inversion-of-control",
+		"ioc",
+		"container",
+		"layer",
+		"service",
+		"aws",
+		"lambda",
+		"aws-lambda"
+	],
+	"homepage": "https://github.com/borisrakovan/sandly",
+	"bugs": {
+		"url": "https://github.com/borisrakovan/sandly/issues"
+	},
+	"author": "Boris Rakovan <b.rakovan@gmail.com> (https://github.com/borisrakovan)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/borisrakovan/sandly.git"
+	},
+	"license": "MIT",
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"clean": "rm -rf dist",
+		"watch": "tsc --watch",
+		"format": "prettier --write \"{src,test}/**/*.ts\"",
+		"format:check": "prettier --check \"{src,test}/**/*.ts\"",
+		"lint": "eslint . --fix",
+		"lint:check": "eslint . --max-warnings=0",
+		"type:check": "tsc --noEmit",
+		"test": "vitest run",
+		"release": "changeset version && changeset publish"
+	},
+	"devDependencies": {
+		"@changesets/cli": "^2.29.5",
+		"@eslint/js": "^9.26.0",
+		"@types/aws-lambda": "^8.10.149",
+		"@types/node": "^22.15.3",
+		"@types/node-fetch": "^2.6.12",
+		"dotenv": "^16.5.0",
+		"esbuild": "^0.25.3",
+		"eslint": "^9.26.0",
+		"node-fetch": "^3.3.2",
+		"prettier": "^3.5.3",
+		"prettier-plugin-organize-imports": "^4.1.0",
+		"ts-node": "^10.9.2",
+		"tsdown": "^0.14.1",
+		"tsx": "^4.19.4",
+		"typescript": "^5.8.3",
+		"typescript-eslint": "^8.38.0",
+		"vite-tsconfig-paths": "^5.1.4",
+		"vitest": "^3.1.3",
+		"zod": "^4.0.15"
+	},
+	"packageManager": "pnpm@9.13.0+sha512.beb9e2a803db336c10c9af682b58ad7181ca0fbd0d4119f2b33d5f2582e96d6c0d93c85b23869295b765170fbdaa92890c0da6ada457415039769edf3c959efe"
+}