sandly 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,1255 @@
+//#region src/tag.d.ts
+/**
+ * Internal symbol used to identify tagged types within the dependency injection system.
+ * This symbol is used as a property key to attach metadata to both value tags and class tags.
+ * @internal
+ */
+declare const TagId: "__tag_id__";
+/**
+ * Type representing a value-based dependency tag.
+ *
+ * Value tags are used to represent non-class dependencies like configuration objects,
+ * strings, numbers, or any other values. They use phantom types to maintain type safety
+ * while being distinguishable at runtime through their unique identifiers.
+ *
+ * @template T - The type of the value this tag represents
+ * @template Id - The unique identifier for this tag (string or symbol)
+ *
+ * @example
+ * ```typescript
+ * // Creates a value tag for string configuration
+ * const ApiKeyTag: ValueTag<string, 'apiKey'> = Tag.of('apiKey')<string>();
+ *
+ * // Register in container
+ * container.register(ApiKeyTag, () => 'my-secret-key');
+ * ```
+ */
+type ValueTag<T, Id extends string | symbol> = Readonly<{
+  readonly [TagId]: Id;
+  /** @internal Phantom type to carry T */
+  readonly __type: T;
+}>;
+/**
+ * Type representing a class-based dependency tag.
+ *
+ * Tagged classes are created by Tag.Class() and serve as both the dependency identifier
+ * and the constructor for the service. They extend regular classes with tag metadata
+ * that the DI system uses for identification and type safety.
+ *
+ * @template T - The type of instances created by this tagged class
+ * @template Id - The unique identifier for this tag (string or symbol)
+ *
+ * @example
+ * ```typescript
+ * // Creates a tagged class
+ * class UserService extends Tag.Class('UserService') {
+ *   getUsers() { return []; }
+ * }
+ *
+ * // Register in container
+ * container.register(UserService, () => new UserService());
+ * ```
+ *
+ * @internal - Users should use Tag.Class() instead of working with this type directly
+ */
+type TaggedClass<T, Id extends string | symbol> = {
+  new (...args: any[]): T & {
+    readonly [TagId]: Id;
+  };
+  readonly [TagId]: Id;
+};
+/**
+ * Type representing a class-based dependency tag.
+ *
+ * This type is a shortcut for TaggedClass<T, string | symbol>.
+ *
+ * @template T - The type of instances created by this tagged class
+ * @returns A tagged class with a string or symbol identifier
+ *
+ * @internal - Users should use Tag.Class() instead of working with this type directly
+ */
+type ClassTag<T> = TaggedClass<T, string | symbol>;
+/**
+ * Union type representing any valid dependency tag in the system.
+ *
+ * A tag can be either a value tag (for non-class dependencies) or a tagged class
+ * (for service classes). This type is used throughout the DI system to constrain
+ * what can be used as a dependency identifier.
+ *
+ * @example Value tag
+ * ```typescript
+ * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
+ * // ConfigTag satisfies AnyTag
+ * ```
+ *
+ * @example Class tag
+ * ```typescript
+ * class DatabaseService extends Tag.Class('DatabaseService') {}
+ * // DatabaseService satisfies AnyTag
+ * ```
+ */
+type AnyTag = ValueTag<any, string | symbol> | TaggedClass<any, string | symbol>;
+/**
+ * Utility object containing factory functions for creating dependency tags.
+ *
+ * The Tag object provides the primary API for creating both value tags and class tags
+ * used throughout the dependency injection system. It's the main entry point for
+ * defining dependencies in a type-safe way.
+ */
+declare const Tag: {
+  /**
+   * Creates a value tag factory for dependencies that are not classes.
+   *
+   * This method returns a factory function that, when called with a type parameter,
+   * creates a value tag for that type. The tag has a string or symbol-based identifier
+   * that must be unique within your application.
+   *
+   * @template Id - The string or symbol identifier for this tag (must be unique)
+   * @param id - The unique string or symbol identifier for this tag
+   * @returns A factory function that creates value tags for the specified type
+   *
+   * @example Basic usage with strings
+   * ```typescript
+   * const ApiKeyTag = Tag.of('apiKey')<string>();
+   * const ConfigTag = Tag.of('config')<{ dbUrl: string; port: number }>();
+   *
+   * container
+   *   .register(ApiKeyTag, () => process.env.API_KEY!)
+   *   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost', port: 5432 }));
+   * ```
+   *
+   * @example Usage with symbols
+   * ```typescript
+   * const DB_CONFIG_SYM = Symbol('database-config');
+   * const ConfigTag = Tag.of(DB_CONFIG_SYM)<DatabaseConfig>();
+   *
+   * container.register(ConfigTag, () => ({ host: 'localhost', port: 5432 }));
+   * ```
+   *
+   * @example Primitive values
+   * ```typescript
+   * const PortTag = Tag.of('port')<number>();
+   * const EnabledTag = Tag.of('enabled')<boolean>();
+   *
+   * container
+   *   .register(PortTag, () => 3000)
+   *   .register(EnabledTag, () => true);
+   * ```
+   *
+   * @example Complex objects
+   * ```typescript
+   * interface DatabaseConfig {
+   *   host: string;
+   *   port: number;
+   *   database: string;
+   * }
+   *
+   * const DbConfigTag = Tag.of('database-config')<DatabaseConfig>();
+   * container.register(DbConfigTag, () => ({
+   *   host: 'localhost',
+   *   port: 5432,
+   *   database: 'myapp'
+   * }));
+   * ```
+   */
+  of: <Id extends string | symbol>(id: Id) => <T>() => ValueTag<T, Id>;
+  /**
+   * 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<T, symbol>;
+  /**
+   * Creates a base class that can be extended to create service classes with dependency tags.
+   *
+   * This is the primary way to define service classes in the dependency injection system.
+   * Classes that extend the returned base class become both the dependency identifier
+   * and the implementation, providing type safety and clear semantics.
+   *
+   * @template Id - The unique identifier for this service class
+   * @param id - The unique identifier (string or symbol) for this service
+   * @returns A base class that can be extended to create tagged service classes
+   *
+   * @example Basic service class
+   * ```typescript
+   * class UserService extends Tag.Class('UserService') {
+   *   getUsers() {
+   *     return ['alice', 'bob'];
+   *   }
+   * }
+   *
+   * container.register(UserService, () => new UserService());
+   * ```
+   *
+   * @example Service with dependencies
+   * ```typescript
+   * class DatabaseService extends Tag.Class('DatabaseService') {
+   *   query(sql: string) { return []; }
+   * }
+   *
+   * class UserRepository extends Tag.Class('UserRepository') {
+   *   constructor(private db: DatabaseService) {
+   *     super();
+   *   }
+   *
+   *   findUser(id: string) {
+   *     return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
+   *   }
+   * }
+   *
+   * container
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(UserRepository, async (c) =>
+   *     new UserRepository(await c.get(DatabaseService))
+   *   );
+   * ```
+   *
+   * @example With symbol identifiers
+   * ```typescript
+   * const SERVICE_ID = Symbol('InternalService');
+   *
+   * class InternalService extends Tag.Class(SERVICE_ID) {
+   *   doInternalWork() { return 'work'; }
+   * }
+   * ```
+   */
+  Class: <Id extends string | symbol>(id: Id) => TaggedClass<{
+    /** @internal */
+    readonly __type: unknown;
+    readonly __tag_id__: Id;
+  }, Id>;
+  /**
+   * Extracts the string representation of a tag's identifier.
+   *
+   * This utility function returns a human-readable string for any tag's identifier,
+   * whether it's a string-based or symbol-based tag. Primarily used internally
+   * for error messages and debugging.
+   *
+   * @param tag - Any valid dependency tag (value tag or class tag)
+   * @returns String representation of the tag's identifier
+   *
+   * @example
+   * ```typescript
+   * const StringTag = Tag.of('myString')<string>();
+   * const SymbolTag = Tag.for<number>();
+   * class ServiceClass extends Tag.Class('MyService') {}
+   *
+   * console.log(Tag.id(StringTag)); // "myString"
+   * console.log(Tag.id(SymbolTag)); // "Symbol()"
+   * console.log(Tag.id(ServiceClass)); // "MyService"
+   * ```
+   *
+   * @internal - Primarily for internal use in error messages and debugging
+   */
+  id: (tag: AnyTag) => string;
+};
+/**
+ * Utility type that extracts the service type from any dependency tag.
+ *
+ * This type is essential for type inference throughout the DI system, allowing
+ * the container and layers to automatically determine what type of service
+ * a given tag represents without manual type annotations.
+ *
+ * @template T - Any dependency tag (ValueTag or TaggedClass)
+ * @returns The service type that the tag represents
+ *
+ * @example With value tags
+ * ```typescript
+ * const StringTag = Tag.of('myString')<string>();
+ * const ConfigTag = Tag.of('config')<{ apiKey: string }>();
+ *
+ * type StringService = ServiceOf<typeof StringTag>; // string
+ * type ConfigService = ServiceOf<typeof ConfigTag>; // { apiKey: string }
+ * ```
+ *
+ * @example With class tags
+ * ```typescript
+ * class UserService extends Tag.Class('UserService') {
+ *   getUsers() { return []; }
+ * }
+ *
+ * type UserServiceType = ServiceOf<typeof UserService>; // UserService
+ * ```
+ *
+ * @example Used in container methods
+ * ```typescript
+ * // The container uses ServiceOf internally for type inference
+ * container.register(StringTag, () => 'hello'); // Factory must return string
+ * container.register(UserService, () => new UserService()); // Factory must return UserService
+ *
+ * const str: string = await container.get(StringTag); // Automatically typed as string
+ * const user: UserService = await container.get(UserService); // Automatically typed as UserService
+ * ```
+ */
+type ServiceOf<T> = T extends ValueTag<infer S, string | symbol> ? S : T extends ClassTag<infer S> ? S : never;
+//#endregion
+//#region src/types.d.ts
+type PromiseOrValue<T> = T | Promise<T>;
+/**
+ * Unique symbol used to store the original ValueTag in Inject<T> types.
+ * This prevents property name collisions while allowing type-level extraction.
+ */
+declare const InjectSource: unique symbol;
+/**
+ * Generic interface representing a class constructor.
+ *
+ * This is primarily used internally for type constraints and validations.
+ * Most users should use Tag.Class() instead of working with raw constructors.
+ *
+ * @template T - The type that the constructor creates
+ * @internal
+ */
+
+/**
+ * Type representing a factory function used to create dependency instances.
+ *
+ * Factory functions are the core mechanism for dependency creation in the DI system.
+ * They receive a dependency container and can use it to resolve other dependencies
+ * that the service being created needs.
+ *
+ * The factory can be either synchronous (returning T directly) or asynchronous
+ * (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
+ *
+ * @example Synchronous factory
+ * ```typescript
+ * const factory: Factory<DatabaseService, never> = (container) => {
+ *   return new DatabaseService('sqlite://memory');
+ * };
+ * ```
+ *
+ * @example Asynchronous factory with dependencies
+ * ```typescript
+ * const factory: Factory<UserService, typeof ConfigTag | typeof DatabaseService> = async (container) => {
+ *   const [config, db] = await Promise.all([
+ *     container.get(ConfigTag),
+ *     container.get(DatabaseService)
+ *   ]);
+ *   return new UserService(config, db);
+ * };
+ * ```
+ */
+type Factory<T, TReg extends AnyTag, TScope extends Scope> = (container: IContainer<TReg, TScope>) => PromiseOrValue<T>;
+/**
+ * Helper type for injecting ValueTag dependencies in constructor parameters.
+ * This allows clean specification of ValueTag dependencies while preserving
+ * the original tag information for dependency inference.
+ *
+ * The phantom property is optional to allow normal runtime values to be assignable.
+ *
+ * @template T - A ValueTag type
+ * @returns The value type with optional phantom tag metadata for dependency inference
+ *
+ * @example
+ * ```typescript
+ * const ApiKeyTag = Tag.of('apiKey')<string>();
+ *
+ * class UserService extends Tag.Class('UserService') {
+ *   constructor(
+ *     private db: DatabaseService,        // ClassTag - works automatically
+ *     private apiKey: Inject<typeof ApiKeyTag>  // ValueTag - type is string, tag preserved
+ *   ) {
+ *     super();
+ *   }
+ * }
+ * ```
+ */
+type Inject<T extends ValueTag<unknown, string | symbol>> = T extends ValueTag<infer V, string | symbol> ? V & {
+  readonly [InjectSource]?: T;
+} : never;
+/**
+ * Helper type to extract the original ValueTag from an Inject<T> type.
+ * Since InjectSource is optional, we need to check for both presence and absence.
+ * @internal
+ */
+type ExtractInjectTag<T> = T extends {
+  readonly [InjectSource]?: infer U;
+} ? U : never;
+/**
+ * Type representing a finalizer function used to clean up dependency instances.
+ *
+ * Finalizers are optional cleanup functions that are called when the container
+ * is destroyed via `container.destroy()`. They receive the created instance
+ * and should perform any necessary cleanup (closing connections, releasing resources, etc.).
+ *
+ * Like factories, finalizers can be either synchronous or asynchronous.
+ * All finalizers are called concurrently during container destruction.
+ *
+ * @template T - The type of the service instance being finalized
+ *
+ * @example Synchronous finalizer
+ * ```typescript
+ * const finalizer: Finalizer<FileHandle> = (fileHandle) => {
+ *   fileHandle.close();
+ * };
+ * ```
+ *
+ * @example Asynchronous finalizer
+ * ```typescript
+ * const finalizer: Finalizer<DatabaseConnection> = async (connection) => {
+ *   await connection.disconnect();
+ * };
+ * ```
+ *
+ * @example Resilient finalizer
+ * ```typescript
+ * const finalizer: Finalizer<HttpServer> = async (server) => {
+ *   try {
+ *     await server.close();
+ *   } catch (error) {
+ *     if (!error.message.includes('already closed')) {
+ *       throw error; // Re-throw unexpected errors
+ *     }
+ *     // Ignore "already closed" errors
+ *   }
+ * };
+ * ```
+ */
+type Finalizer<T> = (instance: T) => PromiseOrValue<void>;
+type Scope = string | symbol;
+declare const DefaultScope: unique symbol;
+type DefaultScope = typeof DefaultScope;
+//#endregion
+//#region src/container.d.ts
+type DependencyLifecycle<T extends AnyTag, TReg extends AnyTag, TScope extends Scope> = {
+  factory: Factory<ServiceOf<T>, TReg, TScope>;
+  finalizer: Finalizer<ServiceOf<T>>;
+};
+interface IContainer<TReg extends AnyTag, TScope extends Scope = DefaultScope> {
+  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, TScope> | DependencyLifecycle<T, TReg, TScope>, scope?: TScope): IContainer<TReg | T, TScope>;
+  has(tag: AnyTag): boolean;
+  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  destroy(): Promise<void>;
+}
+/**
+ * A type-safe dependency injection container that manages service instantiation,
+ * caching, and lifecycle management with support for async dependencies and
+ * circular dependency detection.
+ *
+ * The container maintains complete type safety by tracking registered dependencies
+ * 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
+ *
+ * @example Basic usage with class tags
+ * ```typescript
+ * import { container, Tag } from 'sandl';
+ *
+ * class DatabaseService extends Tag.Class('DatabaseService') {
+ *   query() { return 'data'; }
+ * }
+ *
+ * class UserService extends Tag.Class('UserService') {
+ *   constructor(private db: DatabaseService) {}
+ *   getUser() { return this.db.query(); }
+ * }
+ *
+ * const c = container()
+ *   .register(DatabaseService, () => new DatabaseService())
+ *   .register(UserService, async (container) =>
+ *     new UserService(await container.get(DatabaseService))
+ *   );
+ *
+ * const userService = await c.get(UserService);
+ * ```
+ *
+ * @example Usage with value tags
+ * ```typescript
+ * const ApiKeyTag = Tag.of('apiKey')<string>();
+ * const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
+ *
+ * const c = container()
+ *   .register(ApiKeyTag, () => process.env.API_KEY!)
+ *   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost:5432' }));
+ *
+ * const apiKey = await c.get(ApiKeyTag);
+ * const config = await c.get(ConfigTag);
+ * ```
+ *
+ * @example With finalizers for cleanup
+ * ```typescript
+ * class DatabaseConnection extends Tag.Class('DatabaseConnection') {
+ *   async connect() { return; }
+ *   async disconnect() { return; }
+ * }
+ *
+ * const c = container().register(
+ *   DatabaseConnection,
+ *   async () => {
+ *     const conn = new DatabaseConnection();
+ *     await conn.connect();
+ *     return conn;
+ *   },
+ *   async (conn) => conn.disconnect() // Finalizer for cleanup
+ * );
+ *
+ * // Later...
+ * await c.destroy(); // Calls all finalizers
+ * ```
+ */
+declare class Container<TReg extends AnyTag> implements IContainer<TReg> {
+  /**
+   * Cache of instantiated dependencies as promises.
+   * Ensures singleton behavior and supports concurrent access.
+   * @internal
+   */
+  private readonly cache;
+  /**
+   * Factory functions for creating dependency instances.
+   * @internal
+   */
+  private readonly factories;
+  /**
+   * Finalizer functions for cleaning up dependencies when the container is destroyed.
+   * @internal
+   */
+  private readonly finalizers;
+  /**
+   * Registers a dependency in the container with a factory function and optional finalizer.
+   *
+   * The factory function receives the current container instance and must return the
+   * service instance (or a Promise of it). The container tracks the registration at
+   * the type level, ensuring type safety for subsequent `.get()` calls.
+   *
+   * @template T - The dependency tag being registered
+   * @param tag - The dependency tag (class or value tag)
+   * @param factory - Function that creates the service instance, receives container for dependency injection
+   * @param finalizer - Optional cleanup function called when container is destroyed
+   * @returns A new container instance with the dependency registered
+   * @throws {DependencyContainerError} If the dependency is already registered
+   *
+   * @example Registering a simple service
+   * ```typescript
+   * class LoggerService extends Tag.Class('LoggerService') {
+   *   log(message: string) { console.log(message); }
+   * }
+   *
+   * const c = container().register(
+   *   LoggerService,
+   *   () => new LoggerService()
+   * );
+   * ```
+   *
+   * @example Registering with dependencies
+   * ```typescript
+   * class UserService extends Tag.Class('UserService') {
+   *   constructor(private db: DatabaseService, private logger: LoggerService) {}
+   * }
+   *
+   * const c = container()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(LoggerService, () => new LoggerService())
+   *   .register(UserService, async (container) =>
+   *     new UserService(
+   *       await container.get(DatabaseService),
+   *       await container.get(LoggerService)
+   *     )
+   *   );
+   * ```
+   *
+   * @example Using value tags
+   * ```typescript
+   * const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
+   *
+   * const c = container().register(
+   *   ConfigTag,
+   *   () => ({ apiUrl: 'https://api.example.com' })
+   * );
+   * ```
+   *
+   * @example With finalizer for cleanup
+   * ```typescript
+   * class DatabaseConnection extends Tag.Class('DatabaseConnection') {
+   *   async connect() { return; }
+   *   async close() { return; }
+   * }
+   *
+   * const c = container().register(
+   *   DatabaseConnection,
+   *   async () => {
+   *     const conn = new DatabaseConnection();
+   *     await conn.connect();
+   *     return conn;
+   *   },
+   *   (conn) => conn.close() // Called during container.destroy()
+   * );
+   * ```
+   */
+  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, DefaultScope> | DependencyLifecycle<T, TReg, DefaultScope>): IContainer<TReg | T>;
+  /**
+   * Checks if a dependency has been instantiated (cached) in the container.
+   *
+   * Note: This returns `true` only after the dependency has been created via `.get()`.
+   * A registered but not-yet-instantiated dependency will return `false`.
+   *
+   * @param tag - The dependency tag to check
+   * @returns `true` if the dependency has been instantiated and cached, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * const c = container().register(DatabaseService, () => new DatabaseService());
+   *
+   * console.log(c.has(DatabaseService)); // false - not instantiated yet
+   *
+   * await c.get(DatabaseService);
+   * console.log(c.has(DatabaseService)); // true - now instantiated and cached
+   * ```
+   */
+  has(tag: AnyTag): boolean;
+  /**
+   * Retrieves a dependency instance from the container, creating it if necessary.
+   *
+   * This method ensures singleton behavior - each dependency is created only once
+   * 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.
+   *
+   * @template T - The dependency tag type (must be registered in this container)
+   * @param tag - The dependency tag to retrieve
+   * @returns Promise resolving to the service instance
+   * @throws {UnknownDependencyError} If the dependency is not registered
+   * @throws {CircularDependencyError} If a circular dependency is detected
+   * @throws {DependencyCreationError} If the factory function throws an error
+   *
+   * @example Basic usage
+   * ```typescript
+   * const c = container()
+   *   .register(DatabaseService, () => new DatabaseService());
+   *
+   * const db = await c.get(DatabaseService);
+   * db.query('SELECT * FROM users');
+   * ```
+   *
+   * @example Concurrent access (singleton behavior)
+   * ```typescript
+   * // All three calls will receive the same instance
+   * const [db1, db2, db3] = await Promise.all([
+   *   c.get(DatabaseService),
+   *   c.get(DatabaseService),
+   *   c.get(DatabaseService)
+   * ]);
+   *
+   * console.log(db1 === db2 === db3); // true
+   * ```
+   *
+   * @example Dependency injection in factories
+   * ```typescript
+   * const c = container()
+   *   .register(DatabaseService, () => new DatabaseService())
+   *   .register(UserService, async (container) => {
+   *     const db = await container.get(DatabaseService);
+   *     return new UserService(db);
+   *   });
+   *
+   * const userService = await c.get(UserService);
+   * ```
+   */
+  get<T extends TReg>(tag: T): Promise<ServiceOf<T>>;
+  /**
+   * Destroys all instantiated dependencies by calling their finalizers, then clears the instance cache.
+   *
+   * **Important: This method preserves the container structure (factories and finalizers) for reuse.**
+   * The container can be used again after destruction to create fresh instances following the same
+   * dependency patterns.
+   *
+   * 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
+   * is thrown containing details of all failures.
+   *
+   * **Finalizer Concurrency:** Finalizers run concurrently, so there are no ordering guarantees.
+   * Services should be designed to handle cleanup gracefully regardless of the order in which their
+   * dependencies are cleaned up.
+   *
+   * @returns Promise that resolves when all cleanup is complete
+   * @throws {DependencyContainerFinalizationError} If any finalizers fail during cleanup
+   *
+   * @example Basic cleanup and reuse
+   * ```typescript
+   * const c = container()
+   *   .register(DatabaseConnection,
+   *     async () => {
+   *       const conn = new DatabaseConnection();
+   *       await conn.connect();
+   *       return conn;
+   *     },
+   *     (conn) => conn.disconnect() // Finalizer
+   *   );
+   *
+   * // First use cycle
+   * const db1 = await c.get(DatabaseConnection);
+   * await c.destroy(); // Calls conn.disconnect(), clears cache
+   *
+   * // Container can be reused - creates fresh instances
+   * const db2 = await c.get(DatabaseConnection); // New connection
+   * expect(db2).not.toBe(db1); // Different instances
+   * ```
+   *
+   * @example Multiple destroy/reuse cycles
+   * ```typescript
+   * const c = container().register(UserService, () => new UserService());
+   *
+   * for (let i = 0; i < 5; i++) {
+   *   const user = await c.get(UserService);
+   *   // ... use service ...
+   *   await c.destroy(); // Clean up, ready for next cycle
+   * }
+   * ```
+   *
+   * @example Handling cleanup errors
+   * ```typescript
+   * try {
+   *   await container.destroy();
+   * } catch (error) {
+   *   if (error instanceof DependencyContainerFinalizationError) {
+   *     console.error('Some dependencies failed to clean up:', error.detail.errors);
+   *   }
+   * }
+   * // Container is still reusable even after finalizer errors
+   * ```
+   */
+  destroy(): Promise<void>;
+}
+declare class ScopedContainer<TReg extends AnyTag, TScope extends Scope> implements IContainer<TReg, TScope> {
+  private readonly scope;
+  private readonly parent;
+  private readonly children;
+  /**
+   * Cache of instantiated dependencies as promises for this scope.
+   * @internal
+   */
+  private readonly cache;
+  /**
+   * Factory functions for creating dependency instances in this scope.
+   * @internal
+   */
+  private readonly factories;
+  /**
+   * Finalizer functions for cleaning up dependencies when this scope is destroyed.
+   * @internal
+   */
+  private readonly finalizers;
+  constructor(parent: IContainer<any, any> | null, scope: TScope);
+  /**
+   * Registers a dependency in the specified scope within this container's scope chain.
+   *
+   * If no scope is specified, registers in the current (leaf) scope. If a scope is specified,
+   * delegates to the parent container if the target scope doesn't match the current scope.
+   *
+   * This allows registering dependencies at different scope levels from any container
+   * in the scope chain, providing flexibility for dependency organization.
+   *
+   * @param tag - The dependency tag to register
+   * @param factory - Factory function to create the dependency
+   * @param finalizer - Optional cleanup function
+   * @param scope - Target scope for registration (defaults to current scope)
+   * @returns This container with updated type information
+   *
+   * @example Registering in different scopes
+   * ```typescript
+   * const runtime = scopedContainer('runtime');
+   * const request = runtime.child('request');
+   *
+   * // Register in current (request) scope
+   * request.register(RequestService, () => new RequestService());
+   *
+   * // Register in runtime scope from request container - delegates to parent
+   * request.register(DatabaseService, () => new DatabaseService(), undefined, 'runtime');
+   * ```
+   */
+  register<T extends AnyTag>(tag: T, factoryOrLifecycle: Factory<ServiceOf<T>, TReg, TScope> | DependencyLifecycle<T, TReg, TScope>, scope?: TScope): ScopedContainer<TReg | T, TScope>;
+  /**
+   * 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 only if the dependency has been created and cached somewhere in the scope hierarchy.
+   */
+  has(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
+   */
+  get<T extends TReg>(tag: T): Promise<ServiceOf<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<TChildScope extends Scope>(scope: TChildScope): ScopedContainer<TReg, TScope | TChildScope>;
+}
+/**
+ * Creates a new empty dependency injection container.
+ *
+ * This is a convenience factory function that creates a new DependencyContainer instance.
+ * The returned container starts with no registered dependencies and the type parameter
+ * defaults to `never`, indicating no dependencies are available for retrieval yet.
+ *
+ * @returns A new empty DependencyContainer instance
+ *
+ * @example
+ * ```typescript
+ * import { container, Tag } from 'sandl';
+ *
+ * class DatabaseService extends Tag.Class('DatabaseService') {}
+ * class UserService extends Tag.Class('UserService') {}
+ *
+ * const c = container()
+ *   .register(DatabaseService, () => new DatabaseService())
+ *   .register(UserService, async (container) =>
+ *     new UserService(await container.get(DatabaseService))
+ *   );
+ *
+ * const userService = await c.get(UserService);
+ * ```
+ */
+declare function container(): Container<never>;
+declare function scopedContainer<TScope extends Scope>(scope: TScope): ScopedContainer<never, TScope>;
+//#endregion
+//#region src/layer.d.ts
+/**
+ * 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.
+ *
+ * @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 'sandl';
+ *
+ * class DatabaseService extends Tag.Class('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 c = container();
+ * const finalContainer = databaseLayer().register(c);
+ *
+ * const db = await finalContainer.get(DatabaseService);
+ * ```
+ *
+ * @example Layer composition
+ * ```typescript
+ * // Layer that requires DatabaseService and provides UserService
+ * const userLayer = layer<typeof DatabaseService, typeof UserService>((container) =>
+ *   container.register(UserService, async (c) =>
+ *     new UserService(await c.get(DatabaseService))
+ *   )
+ * );
+ *
+ * // Compose layers: database layer provides what user layer needs
+ * const appLayer = databaseLayer().to(userLayer());
+ * ```
+ */
+interface Layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never> {
+  /**
+   * Applies this layer's registrations to the given container.
+   *
+   * @param container - The container to register dependencies into
+   * @returns A new container with this layer's dependencies registered
+   *
+   * @example
+   * ```typescript
+   * const container = container();
+   * const updatedContainer = myLayer.register(container);
+   * ```
+   */
+  register: <TScope extends Scope>(container: IContainer<TRequires, TScope>) => IContainer<TRequires | TProvides, TScope>;
+  /**
+   * Composes this layer with a target layer, creating a pipeline where this layer's
+   * provisions satisfy the target layer's requirements. This creates a dependency
+   * flow from source → target.
+   *
+   * Type-safe: The target layer's requirements must be satisfiable by this layer's
+   * provisions and any remaining external requirements.
+   *
+   * @template TTargetRequires - What the target layer requires
+   * @template TTargetProvides - What the target layer provides
+   * @param target - The layer to compose with
+   * @returns A new composed layer
+   *
+   * @example Simple composition
+   * ```typescript
+   * const configLayer = layer<never, typeof ConfigTag>(...);
+   * const dbLayer = layer<typeof ConfigTag, typeof DatabaseService>(...);
+   *
+   * // Config provides what database needs
+   * const infraLayer = configLayer().to(dbLayer());
+   * ```
+   *
+   * @example Multi-level composition
+   * ```typescript
+   * const appLayer = configLayer()
+   *   .to(databaseLayer())
+   *   .to(serviceLayer())
+   *   .to(apiLayer());
+   * ```
+   */
+  to: <TTargetRequires extends AnyTag, TTargetProvides extends AnyTag>(target: Layer<TTargetRequires, TTargetProvides>) => Layer<TRequires | Exclude<TTargetRequires, TProvides>, TProvides | TTargetProvides>;
+  /**
+   * Merges this layer with another layer, combining their requirements and provisions.
+   * This is useful for combining independent layers that don't have a dependency
+   * relationship.
+   *
+   * @template TOtherRequires - What the other layer requires
+   * @template TOtherProvides - What the other layer provides
+   * @param other - The layer to merge with
+   * @returns A new merged layer requiring both layers' requirements and providing both layers' provisions
+   *
+   * @example Merging independent layers
+   * ```typescript
+   * const persistenceLayer = layer<never, typeof DatabaseService | typeof CacheService>(...);
+   * const loggingLayer = layer<never, typeof LoggerService>(...);
+   *
+   * // Combine infrastructure layers
+   * const infraLayer = persistenceLayer().and(loggingLayer());
+   * ```
+   *
+   * @example Building complex layer combinations
+   * ```typescript
+   * const appInfraLayer = persistenceLayer()
+   *   .and(messagingLayer())
+   *   .and(observabilityLayer());
+   * ```
+   */
+  and: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
+}
+/**
+ * A factory function for creating layers.
+ *
+ * @template TRequires - The union of tags this layer requires
+ * @template TProvides - The union of tags this layer provides
+ * @template TParams - Optional parameters that can be passed to configure the layer
+ */
+type LayerFactory<TRequires extends AnyTag, TProvides extends AnyTag, TParams = undefined> = TParams extends undefined ? () => Layer<TRequires, TProvides> : (params: TParams) => Layer<TRequires, TProvides>;
+/**
+ * Creates a new dependency layer that encapsulates a set of dependency registrations.
+ * Layers are the primary building blocks for organizing and composing dependency injection setups.
+ *
+ * @template TRequires - The union of dependency tags this layer requires from other layers or external setup
+ * @template TProvides - The union of dependency tags this layer registers/provides
+ * @template TParams - Optional parameters that can be passed to configure the layer
+ *
+ * @param register - Function that performs the dependency registrations. Receives a container and optional params.
+ * @returns A layer factory function. If TParams is undefined, returns a parameterless function. Otherwise returns a function that takes TParams.
+ *
+ * @example Simple layer without parameters
+ * ```typescript
+ * import { layer, Tag } from '@/di/layer.js';
+ *
+ * class DatabaseService extends Tag.Class('DatabaseService') {
+ *   constructor(private url: string = 'sqlite://memory') {}
+ *   query() { return 'data'; }
+ * }
+ *
+ * // Layer that provides DatabaseService, requires nothing
+ * const databaseLayer = layer<never, typeof DatabaseService>((container) =>
+ *   container.register(DatabaseService, () => new DatabaseService())
+ * );
+ *
+ * // Usage
+ * const dbLayerInstance = databaseLayer(); // No parameters needed
+ * ```
+ *
+ * @example Layer with dependencies
+ * ```typescript
+ * const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
+ *
+ * // Layer that requires ConfigTag and provides DatabaseService
+ * const databaseLayer = layer<typeof ConfigTag, typeof DatabaseService>((container) =>
+ *   container.register(DatabaseService, async (c) => {
+ *     const config = await c.get(ConfigTag);
+ *     return new DatabaseService(config.dbUrl);
+ *   })
+ * );
+ * ```
+ *
+ * @example Parameterized layer
+ * ```typescript
+ * interface DatabaseConfig {
+ *   host: string;
+ *   port: number;
+ * }
+ *
+ * // Layer that takes configuration parameters
+ * const databaseLayer = layer<never, typeof DatabaseService, DatabaseConfig>(
+ *   (container, config) =>
+ *     container.register(DatabaseService, () => new DatabaseService(config))
+ * );
+ *
+ * // Usage with parameters
+ * const dbLayerInstance = databaseLayer({ host: 'localhost', port: 5432 });
+ * ```
+ *
+ * @example Complex application layer structure
+ * ```typescript
+ * // Configuration layer
+ * const configLayer = layer<never, typeof ConfigTag>((container) =>
+ *   container.register(ConfigTag, () => loadConfig())
+ * );
+ *
+ * // Infrastructure layer (requires config)
+ * const infraLayer = layer<typeof ConfigTag, typeof DatabaseService | typeof CacheService>(
+ *   (container) =>
+ *     container
+ *       .register(DatabaseService, async (c) => new DatabaseService(await c.get(ConfigTag)))
+ *       .register(CacheService, async (c) => new CacheService(await c.get(ConfigTag)))
+ * );
+ *
+ * // Service layer (requires infrastructure)
+ * const serviceLayer = layer<typeof DatabaseService | typeof CacheService, typeof UserService>(
+ *   (container) =>
+ *     container.register(UserService, async (c) =>
+ *       new UserService(await c.get(DatabaseService), await c.get(CacheService))
+ *     )
+ * );
+ *
+ * // Compose the complete application
+ * const appLayer = configLayer().to(infraLayer()).to(serviceLayer());
+ * ```
+ */
+declare function layer<TRequires extends AnyTag = never, TProvides extends AnyTag = never, TParams = undefined>(register: <TScope extends Scope>(container: IContainer<TRequires, TScope>, params: TParams) => IContainer<TRequires | TProvides, TScope>): LayerFactory<TRequires, TProvides, TParams>;
+/**
+ * Helper type that extracts the union of all requirements from an array of layers.
+ * Used by Layer.merge() to compute the correct requirement type for the merged layer.
+ *
+ * @internal
+ */
+type UnionOfRequires<T extends readonly Layer<AnyTag, AnyTag>[]> = { [K in keyof T]: T[K] extends Layer<infer R, AnyTag> ? R : never }[number];
+/**
+ * Helper type that extracts the union of all provisions from an array of layers.
+ * Used by Layer.merge() to compute the correct provision type for the merged layer.
+ *
+ * @internal
+ */
+type UnionOfProvides<T extends readonly Layer<AnyTag, AnyTag>[]> = { [K in keyof T]: T[K] extends Layer<AnyTag, infer P> ? P : never }[number];
+/**
+ * Utility object containing helper functions for working with layers.
+ */
+declare const Layer: {
+  /**
+   * Creates an empty layer that provides no dependencies and requires no dependencies.
+   * This is useful as a base layer or for testing.
+   *
+   * @returns An empty layer that can be used as a starting point for layer composition
+   *
+   * @example
+   * ```typescript
+   * import { Layer } from 'sandl';
+   *
+   * const baseLayer = Layer.empty();
+   * const appLayer = baseLayer
+   *   .and(configLayer())
+   *   .and(serviceLayer());
+   * ```
+   */
+  empty(): Layer;
+  /**
+   * Merges multiple layers at once in a type-safe way.
+   * This is equivalent to chaining `.and()` calls but more convenient for multiple layers.
+   *
+   * All layers are merged in order, combining their requirements and provisions.
+   * The resulting layer requires the union of all input layer requirements and
+   * provides the union of all input layer provisions.
+   *
+   * @template T - The tuple type of layers to merge
+   * @param layers - At least 2 layers to merge together
+   * @returns A new layer that combines all input layers
+   *
+   * @example Basic usage
+   * ```typescript
+   * import { Layer } from 'sandl';
+   *
+   * const infraLayer = Layer.merge(
+   *   databaseLayer(),
+   *   cacheLayer(),
+   *   loggingLayer()
+   * );
+   * ```
+   *
+   * @example Equivalent to chaining .and()
+   * ```typescript
+   * // These are equivalent:
+   * const layer1 = Layer.merge(layerA(), layerB(), layerC());
+   * const layer2 = layerA().and(layerB()).and(layerC());
+   * ```
+   *
+   * @example Building infrastructure layers
+   * ```typescript
+   * const persistenceLayer = layer<never, typeof DatabaseService | typeof CacheService>(...);
+   * const messagingLayer = layer<never, typeof MessageQueue>(...);
+   * const observabilityLayer = layer<never, typeof Logger | typeof Metrics>(...);
+   *
+   * // Merge all infrastructure concerns into one layer
+   * const infraLayer = Layer.merge(
+   *   persistenceLayer(),
+   *   messagingLayer(),
+   *   observabilityLayer()
+   * );
+   *
+   * // Now infraLayer provides: DatabaseService | CacheService | MessageQueue | Logger | Metrics
+   * ```
+   */
+  merge<T extends readonly [Layer<AnyTag, AnyTag>, Layer<AnyTag, AnyTag>, ...Layer<AnyTag, AnyTag>[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+};
+//#endregion
+//#region src/service.d.ts
+/**
+ * Extracts constructor parameter types from a TaggedClass.
+ * Only parameters that extend AnyTag are considered as dependencies.
+ */
+type ConstructorParams<T extends ClassTag<unknown>> = T extends (new (...args: infer A) => unknown) ? A : never;
+/**
+ * Helper to convert a tagged instance type back to its constructor type.
+ * This uses the fact that tagged classes have a specific structure with TagId property.
+ */
+type InstanceToConstructorType<T> = T extends {
+  readonly [TagId]: infer Id;
+} ? Id extends string | symbol ? TaggedClass<T, Id> : never : never;
+/**
+ * Extracts constructor-typed dependencies from constructor parameters.
+ * Converts instance types to their corresponding constructor types.
+ * Handles both ClassTag dependencies (automatic) and ValueTag dependencies (via Inject helper).
+ */
+type FilterTags<T extends readonly unknown[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends {
+  readonly [TagId]: string | symbol;
+} ? InstanceToConstructorType<T[K]> : ExtractInjectTag<T[K]> extends never ? never : ExtractInjectTag<T[K]> }[number];
+/**
+ * Extracts the instance type that a TaggedClass constructor creates.
+ */
+
+/**
+ * Extracts only the dependency tags from a constructor's parameters for ClassTag services,
+ * or returns never for ValueTag services (which have no constructor dependencies).
+ * This is used to determine what dependencies a service requires.
+ */
+type ServiceDependencies<T extends AnyTag> = T extends ClassTag<unknown> ? FilterTags<ConstructorParams<T>> extends AnyTag ? FilterTags<ConstructorParams<T>> : never : never;
+/**
+ * Represents a service layer that can be created from any tag type.
+ * For ClassTag services, dependencies are automatically inferred from constructor parameters.
+ * For ValueTag services, there are no dependencies since they don't have constructors.
+ */
+interface Service<T extends AnyTag> extends Layer<ServiceDependencies<T>, T> {
+  /**
+   * The tag that this service represents (ClassTag or ValueTag)
+   */
+  readonly serviceClass: T;
+}
+/**
+ * Creates a service layer from any tag type (ClassTag or ValueTag) with optional parameters.
+ *
+ * For ClassTag services:
+ * - Dependencies are automatically inferred from constructor parameters
+ * - The factory function must handle dependency injection by resolving dependencies from the container
+ *
+ * For ValueTag services:
+ * - No constructor dependencies are needed since they don't have constructors
+ *
+ * @template T - The tag representing the service (ClassTag or ValueTag)
+ * @template TParams - Optional parameters for service configuration
+ * @param serviceClass - The tag (ClassTag or ValueTag)
+ * @param factory - Factory function for service instantiation with container and optional params
+ * @returns A factory function that creates a service layer
+ *
+ * @example Simple service without dependencies
+ * ```typescript
+ * class LoggerService extends Tag.Class('LoggerService') {
+ *   log(message: string) { console.log(message); }
+ * }
+ *
+ * const loggerService = service(LoggerService, () => new LoggerService());
+ * ```
+ *
+ * @example Service with dependencies
+ * ```typescript
+ * class DatabaseService extends Tag.Class('DatabaseService') {
+ *   query() { return []; }
+ * }
+ *
+ * class UserService extends Tag.Class('UserService') {
+ *   constructor(private db: DatabaseService) {
+ *     super();
+ *   }
+ *
+ *   getUsers() { return this.db.query(); }
+ * }
+ *
+ * const userService = service(UserService, async (container) =>
+ *   new UserService(await container.get(DatabaseService))
+ * );
+ * ```
+ *
+ * @example Service with configuration parameters
+ * ```typescript
+ * class DatabaseService extends Tag.Class('DatabaseService') {
+ *   constructor(private config: { dbUrl: string }) {
+ *     super();
+ *   }
+ * }
+ *
+ * const dbService = service(
+ *   DatabaseService,
+ *   (container, params: { dbUrl: string }) => new DatabaseService(params)
+ * );
+ * ```
+ */
+declare function service<T extends AnyTag, TParams = undefined>(serviceClass: T, factory: (container: IContainer<ServiceDependencies<T>>, params: TParams) => PromiseOrValue<ServiceOf<T>>): TParams extends undefined ? () => Service<T> : (params: TParams) => Service<T>;
+//#endregion
+export { type Inject, Layer, type Scope, type Service, type ServiceOf, Tag, type TaggedClass, type ValueTag, container, layer, scopedContainer, service };