sandly 0.4.0 → 0.5.1

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 };