sandly 0.0.2

package/dist/index.js

@@ -0,0 +1,983 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/tag.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
+*/
+const TagId = "__tag_id__";
+/**
+* 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.
+*/
+const Tag = {
+	of: (id) => {
+		return () => ({
+			[TagId]: id,
+			__type: void 0
+		});
+	},
+	for: () => {
+		return {
+			[TagId]: Symbol(),
+			__type: void 0
+		};
+	},
+	Class: (id) => {
+		class Tagged {
+			static [TagId] = id;
+			[TagId] = id;
+			/** @internal */
+			__type;
+		}
+		return Tagged;
+	},
+	id: (tag) => {
+		if (typeof tag === "function") {
+			const id$1 = tag[TagId];
+			return typeof id$1 === "symbol" ? id$1.toString() : String(id$1);
+		}
+		const id = tag[TagId];
+		return typeof id === "symbol" ? id.toString() : String(id);
+	}
+};
+
+//#endregion
+//#region src/errors.ts
+var BaseError = class BaseError extends Error {
+	detail;
+	constructor(message, { cause, detail } = {}) {
+		super(message, { cause });
+		this.name = this.constructor.name;
+		this.detail = detail;
+		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 });
+	}
+	dump() {
+		const cause = this.cause instanceof BaseError ? this.cause.dump().error : this.cause;
+		const result = {
+			name: this.name,
+			message: this.message,
+			cause,
+			detail: this.detail ?? {}
+		};
+		return {
+			name: this.name,
+			message: result.message,
+			stack: this.stack,
+			error: result
+		};
+	}
+	dumps() {
+		return JSON.stringify(this.dump());
+	}
+};
+/**
+* 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.get(SomeService);
+* } catch (error) {
+*   if (error instanceof DependencyContainerError) {
+*     console.error('DI Error:', error.message);
+*     console.error('Details:', error.detail);
+*   }
+* }
+* ```
+*/
+var DependencyContainerError = class extends BaseError {};
+/**
+* Error thrown when attempting to retrieve a dependency that hasn't been registered.
+*
+* This error occurs when calling `container.get(Tag)` for a tag that was never
+* registered via `container.register()`. It indicates a programming error where
+* the dependency setup is incomplete.
+*
+* @example
+* ```typescript
+* const c = container(); // Empty container
+*
+* try {
+*   await c.get(UnregisteredService); // This will throw
+* } catch (error) {
+*   if (error instanceof UnknownDependencyError) {
+*     console.error('Missing dependency:', error.message);
+*   }
+* }
+* ```
+*/
+var UnknownDependencyError = class extends DependencyContainerError {
+	/**
+	* @internal
+	* Creates an UnknownDependencyError for the given tag.
+	*
+	* @param tag - The dependency tag that wasn't found
+	*/
+	constructor(tag) {
+		super(`No factory registered for dependency ${Tag.id(tag)}`);
+	}
+};
+/**
+* Error thrown when a circular dependency is detected during dependency resolution.
+*
+* This occurs when service A depends on service B, which depends on service A (directly
+* or through a chain of dependencies). The error includes the full dependency chain
+* to help identify the circular reference.
+*
+* @example Circular dependency scenario
+* ```typescript
+* class ServiceA extends Tag.Class('ServiceA') {}
+* class ServiceB extends Tag.Class('ServiceB') {}
+*
+* const c = container()
+*   .register(ServiceA, async (container) =>
+*     new ServiceA(await container.get(ServiceB)) // Depends on B
+*   )
+*   .register(ServiceB, async (container) =>
+*     new ServiceB(await container.get(ServiceA)) // Depends on A - CIRCULAR!
+*   );
+*
+* try {
+*   await c.get(ServiceA);
+* } catch (error) {
+*   if (error instanceof CircularDependencyError) {
+*     console.error('Circular dependency:', error.message);
+*     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
+*   }
+* }
+* ```
+*/
+var CircularDependencyError = class extends DependencyContainerError {
+	/**
+	* @internal
+	* Creates a CircularDependencyError with the dependency chain information.
+	*
+	* @param tag - The tag where the circular dependency was detected
+	* @param dependencyChain - The chain of dependencies that led to the circular reference
+	*/
+	constructor(tag, dependencyChain) {
+		const chain = dependencyChain.map((t) => Tag.id(t)).join(" -> ");
+		super(`Circular dependency detected for ${Tag.id(tag)}: ${chain} -> ${Tag.id(tag)}`, { detail: {
+			tag: Tag.id(tag),
+			dependencyChain: dependencyChain.map((t) => Tag.id(t))
+		} });
+	}
+};
+/**
+* Error thrown when a dependency factory function throws an error during instantiation.
+*
+* This wraps the original error with additional context about which dependency
+* failed to be created. The original error is preserved as the `cause` property.
+*
+* @example Factory throwing error
+* ```typescript
+* class DatabaseService extends Tag.Class('DatabaseService') {}
+*
+* const c = container().register(DatabaseService, () => {
+*   throw new Error('Database connection failed');
+* });
+*
+* try {
+*   await c.get(DatabaseService);
+* } catch (error) {
+*   if (error instanceof DependencyCreationError) {
+*     console.error('Failed to create:', error.message);
+*     console.error('Original error:', error.cause);
+*   }
+* }
+* ```
+*/
+var DependencyCreationError = class extends DependencyContainerError {
+	/**
+	* @internal
+	* Creates a DependencyCreationError wrapping the original factory error.
+	*
+	* @param tag - The tag of the dependency that failed to be created
+	* @param error - The original error thrown by the factory function
+	*/
+	constructor(tag, error) {
+		super(`Error creating instance of ${Tag.id(tag)}: ${error}`, {
+			cause: error,
+			detail: { tag: Tag.id(tag) }
+		});
+	}
+};
+/**
+* Error thrown when one or more finalizers fail during container destruction.
+*
+* This error aggregates multiple finalizer failures that occurred during
+* `container.destroy()`. Even if some finalizers fail, the container cleanup
+* process continues and this error contains details of all failures.
+*
+* @example Handling finalization errors
+* ```typescript
+* try {
+*   await container.destroy();
+* } catch (error) {
+*   if (error instanceof DependencyContainerFinalizationError) {
+*     console.error('Some finalizers failed');
+*     console.error('Error details:', error.detail.errors);
+*   }
+* }
+* ```
+*/
+var DependencyContainerFinalizationError = class extends DependencyContainerError {
+	/**
+	* @internal
+	* Creates a DependencyContainerFinalizationError aggregating multiple finalizer failures.
+	*
+	* @param errors - Array of errors thrown by individual finalizers
+	*/
+	constructor(errors) {
+		const lambdaErrors = errors.map((error) => BaseError.ensure(error));
+		super("Error destroying dependency container", {
+			cause: errors[0],
+			detail: { errors: lambdaErrors.map((error) => error.dump()) }
+		});
+	}
+};
+
+//#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
+*/
+const resolutionChain = new AsyncLocalStorage();
+/**
+* Shared logic for dependency resolution that handles caching, circular dependency detection,
+* and error handling. Used by both BasicDependencyContainer and ScopedDependencyContainer.
+* @internal
+*/
+async function resolveDependency(tag, cache, factories, container$1) {
+	const cached = cache.get(tag);
+	if (cached !== void 0) return cached;
+	const currentChain = resolutionChain.getStore() ?? [];
+	if (currentChain.includes(tag)) throw new CircularDependencyError(tag, currentChain);
+	const factory = factories.get(tag);
+	if (factory === void 0) return Promise.reject(new UnknownDependencyError(tag));
+	const instancePromise = resolutionChain.run([...currentChain, tag], async () => {
+		try {
+			const instance = await factory(container$1);
+			return instance;
+		} catch (error) {
+			if (error instanceof CircularDependencyError) throw error;
+			throw new DependencyCreationError(tag, error);
+		}
+	}).catch((error) => {
+		cache.delete(tag);
+		throw error;
+	});
+	cache.set(tag, instancePromise);
+	return instancePromise;
+}
+/**
+* Shared logic for running finalizers and handling cleanup errors.
+* @internal
+*/
+async function runFinalizers(finalizers, cache) {
+	const promises = Array.from(finalizers.entries()).filter(([tag]) => cache.has(tag)).map(async ([tag, finalizer]) => {
+		const dep = await cache.get(tag);
+		return finalizer(dep);
+	});
+	const results = await Promise.allSettled(promises);
+	const failures = results.filter((result) => result.status === "rejected");
+	if (failures.length > 0) throw new DependencyContainerFinalizationError(failures.map((result) => result.reason));
+}
+/**
+* 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
+* ```
+*/
+var Container = class {
+	/**
+	* Cache of instantiated dependencies as promises.
+	* Ensures singleton behavior and supports concurrent access.
+	* @internal
+	*/
+	cache = /* @__PURE__ */ new Map();
+	/**
+	* Factory functions for creating dependency instances.
+	* @internal
+	*/
+	factories = /* @__PURE__ */ new Map();
+	/**
+	* Finalizer functions for cleaning up dependencies when the container is destroyed.
+	* @internal
+	*/
+	finalizers = /* @__PURE__ */ new Map();
+	/**
+	* 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(tag, factoryOrLifecycle) {
+		if (this.factories.has(tag)) throw new DependencyContainerError(`Dependency ${Tag.id(tag)} already registered`);
+		if (typeof factoryOrLifecycle === "function") this.factories.set(tag, factoryOrLifecycle);
+		else {
+			this.factories.set(tag, factoryOrLifecycle.factory);
+			this.finalizers.set(tag, factoryOrLifecycle.finalizer);
+		}
+		return this;
+	}
+	/**
+	* 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) {
+		return this.cache.has(tag);
+	}
+	/**
+	* 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);
+	* ```
+	*/
+	async get(tag) {
+		return resolveDependency(tag, this.cache, this.factories, this);
+	}
+	/**
+	* 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
+	* ```
+	*/
+	async destroy() {
+		try {
+			await runFinalizers(this.finalizers, this.cache);
+		} finally {
+			this.cache.clear();
+		}
+	}
+};
+var ScopedContainer = class ScopedContainer {
+	scope;
+	parent;
+	children = [];
+	/**
+	* Cache of instantiated dependencies as promises for this scope.
+	* @internal
+	*/
+	cache = /* @__PURE__ */ new Map();
+	/**
+	* Factory functions for creating dependency instances in this scope.
+	* @internal
+	*/
+	factories = /* @__PURE__ */ new Map();
+	/**
+	* Finalizer functions for cleaning up dependencies when this scope is destroyed.
+	* @internal
+	*/
+	finalizers = /* @__PURE__ */ new Map();
+	constructor(parent, scope) {
+		this.parent = parent;
+		this.scope = scope;
+	}
+	/**
+	* 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(tag, factoryOrLifecycle, scope) {
+		if (scope === void 0 || scope === this.scope) {
+			if (this.factories.has(tag)) throw new DependencyContainerError(`Dependency ${Tag.id(tag)} already registered in scope '${String(this.scope)}'`);
+			if (typeof factoryOrLifecycle === "function") this.factories.set(tag, factoryOrLifecycle);
+			else {
+				this.factories.set(tag, factoryOrLifecycle.factory);
+				this.finalizers.set(tag, factoryOrLifecycle.finalizer);
+			}
+			return this;
+		}
+		if (this.parent === null) throw new DependencyContainerError(`Scope '${String(scope)}' not found in container chain`);
+		this.parent.register(tag, factoryOrLifecycle, scope);
+		return this;
+	}
+	/**
+	* 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) {
+		if (this.cache.has(tag)) return true;
+		return this.parent?.has(tag) ?? false;
+	}
+	/**
+	* 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
+	*/
+	async get(tag) {
+		if (this.factories.has(tag)) return resolveDependency(tag, this.cache, this.factories, this);
+		if (this.parent !== null) return this.parent.get(tag);
+		throw new UnknownDependencyError(tag);
+	}
+	/**
+	* 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.
+	*/
+	async destroy() {
+		const allFailures = [];
+		try {
+			const childDestroyPromises = this.children.map((child) => child.destroy());
+			const childResults = await Promise.allSettled(childDestroyPromises);
+			const childFailures = childResults.filter((result) => result.status === "rejected").map((result) => result.reason);
+			allFailures.push(...childFailures);
+			await runFinalizers(this.finalizers, this.cache);
+		} catch (error) {
+			allFailures.push(error);
+		} finally {
+			this.cache.clear();
+		}
+		if (allFailures.length > 0) throw new DependencyContainerFinalizationError(allFailures);
+	}
+	/**
+	* Creates a child scoped container.
+	*
+	* Child containers inherit access to parent dependencies but maintain
+	* their own scope for new registrations and instance caching.
+	*/
+	child(scope) {
+		const child = new ScopedContainer(this, scope);
+		this.children.push(child);
+		return child;
+	}
+};
+/**
+* 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);
+* ```
+*/
+function container() {
+	return new Container();
+}
+function scopedContainer(scope) {
+	return new ScopedContainer(null, scope);
+}
+
+//#endregion
+//#region src/layer.ts
+/**
+* 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());
+* ```
+*/
+function layer(register) {
+	const factory = (params) => {
+		const layerImpl = {
+			register: (container$1) => register(container$1, params),
+			to(target) {
+				return createComposedLayer(layerImpl, target);
+			},
+			and(other) {
+				return createMergedLayer(layerImpl, other);
+			}
+		};
+		return layerImpl;
+	};
+	return factory;
+}
+/**
+* Internal function to create a composed layer from two layers.
+* This implements the `.to()` method logic.
+*
+* @internal
+*/
+function createComposedLayer(source, target) {
+	return layer((container$1) => {
+		const containerWithSource = source.register(container$1);
+		return target.register(containerWithSource);
+	})();
+}
+/**
+* Internal function to create a merged layer from two layers.
+* This implements the `.and()` method logic.
+*
+* @internal
+*/
+function createMergedLayer(layer1, layer2) {
+	return layer((container$1) => {
+		const container1 = layer1.register(container$1);
+		return layer2.register(container1);
+	})();
+}
+/**
+* Utility object containing helper functions for working with layers.
+*/
+const Layer = {
+	empty() {
+		return layer((container$1) => container$1)();
+	},
+	merge(...layers) {
+		return layers.reduce((acc, layer$1) => acc.and(layer$1));
+	}
+};
+
+//#endregion
+//#region src/service.ts
+/**
+* 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)
+* );
+* ```
+*/
+function service(serviceClass, factory) {
+	const serviceFactory = (params) => {
+		const serviceLayer = layer((container$1) => {
+			return container$1.register(serviceClass, (c) => factory(c, params));
+		})();
+		const serviceImpl = {
+			serviceClass,
+			register: serviceLayer.register,
+			to: serviceLayer.to,
+			and: serviceLayer.and
+		};
+		return serviceImpl;
+	};
+	return serviceFactory;
+}
+
+//#endregion
+export { Layer, Tag, container, layer, scopedContainer, service };