sandly 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,197 +1,24 @@
-//#region src/layer.ts
-/**
-* The type ID for the Layer interface.
-*/
-const LayerTypeId = Symbol.for("sandly/Layer");
-/**
-* 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
-*
-* @param register - Function that performs the dependency registrations. Receives a container.
-* @returns The layer instance.
-*
-* @example Simple layer
-* ```typescript
-* import { layer, Tag } from 'sandly';
-*
-* class DatabaseService extends Tag.Service('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;
-* ```
-*
-* @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 (ctx) => new DatabaseService(await ctx.resolve(ConfigTag)))
-*       .register(CacheService, async (ctx) => new CacheService(await ctx.resolve(ConfigTag)))
-* );
-*
-* // Service layer (requires infrastructure)
-* const serviceLayer = layer<typeof DatabaseService | typeof CacheService, typeof UserService>(
-*   (container) =>
-*     container.register(UserService, async (ctx) =>
-*       new UserService(await ctx.resolve(DatabaseService), await ctx.resolve(CacheService))
-*     )
-* );
-*
-* // Compose the complete application
-* const appLayer = serviceLayer.provide(infraLayer).provide(configLayer);
-* ```
-*/
-function layer(register) {
-	const layerImpl = {
-		register: (container) => register(container),
-		provide(dependency$1) {
-			return createProvidedLayer(dependency$1, layerImpl);
-		},
-		provideMerge(dependency$1) {
-			return createComposedLayer(dependency$1, layerImpl);
-		},
-		merge(other) {
-			return createMergedLayer(layerImpl, other);
-		}
-	};
-	return layerImpl;
-}
+//#region src/tag.ts
 /**
-* Internal function to create a provided layer from two layers.
-* This implements the `.provide()` method logic - only exposes target layer's provisions.
-*
+* Symbol used to identify ValueTag objects at runtime.
 * @internal
 */
-function createProvidedLayer(dependency$1, target) {
-	return createComposedLayer(dependency$1, target);
-}
+const ValueTagIdKey = "sandly/ValueTagIdKey";
 /**
-* Internal function to create a composed layer from two layers.
-* This implements the `.provideMerge()` method logic - exposes both layers' provisions.
-*
+* Symbol used to carry the phantom type for ValueTag.
 * @internal
 */
-function createComposedLayer(dependency$1, target) {
-	return layer((container) => {
-		const containerWithDependency = dependency$1.register(
-			container
-			// The type
-			// IContainer<TRequires1 | TProvides1 | Exclude<TRequires2, TProvides1> | TContainer>
-			// can be simplified to
-			// IContainer<TRequires1 | TRequires2 | TProvides1 | TContainer>
-);
-		return target.register(containerWithDependency);
-	});
-}
+const TagTypeKey = "sandly/TagTypeKey";
 /**
-* Internal function to create a merged layer from two layers.
-* This implements the `.merge()` method logic.
-*
+* Helper to get an object property safely.
 * @internal
 */
-function createMergedLayer(layer1, layer2) {
-	return layer((container) => {
-		const container1 = layer1.register(container);
-		const container2 = layer2.register(container1);
-		return container2;
-	});
-}
-/**
-* Utility object containing helper functions for working with layers.
-*/
-const Layer = {
-	empty() {
-		return layer((container) => container);
-	},
-	mergeAll(...layers) {
-		return layers.reduce((acc, layer$1) => acc.merge(layer$1));
-	},
-	merge(layer1, layer2) {
-		return layer1.merge(layer2);
-	}
-};
-
-//#endregion
-//#region src/constant.ts
-/**
-* Creates a layer that provides a constant value for a given tag.
-*
-* @param tag - The value tag to provide
-* @param constantValue - The constant value to provide
-* @returns A layer with no dependencies that provides the constant value
-*
-* @example
-* ```typescript
-* const ApiKey = Tag.of('ApiKey')<string>();
-* const DatabaseUrl = Tag.of('DatabaseUrl')<string>();
-*
-* const apiKey = constant(ApiKey, 'my-secret-key');
-* const dbUrl = constant(DatabaseUrl, 'postgresql://localhost:5432/myapp');
-*
-* const config = Layer.merge(apiKey, dbUrl);
-* ```
-*/
-function constant(tag, constantValue) {
-	return layer((container) => container.register(tag, () => constantValue));
-}
-
-//#endregion
-//#region src/utils/object.ts
-function hasKey(obj, key) {
-	return obj !== void 0 && obj !== null && (typeof obj === "object" || typeof obj === "function") && key in obj;
-}
-function getKey(obj, ...keys) {
-	let current = obj;
-	for (const key of keys) {
-		if (!hasKey(current, key)) return void 0;
-		current = current[key];
-	}
-	return current;
+function getKey(obj, key) {
+	if (obj === null || obj === void 0) return void 0;
+	return obj[key];
 }
-
-//#endregion
-//#region src/tag.ts
-/**
-* 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 service tags.
-*
-* Note: We can't use a symbol here becuase it produced the following TS error:
-*  error TS4020: 'extends' clause of exported class 'NotificationService' has or is using private name 'TagIdKey'.
-*
-* @internal
-*/
-const ValueTagIdKey = "sandly/ValueTagIdKey";
-const ServiceTagIdKey = "sandly/ServiceTagIdKey";
-/**
-* Internal string used to identify the type of a tagged type within the dependency injection system.
-* This string is used as a property key to attach metadata to both value tags and service tags.
-* It is used to carry the type of the tagged type and should not be used directly.
-* @internal
-*/
-const TagTypeKey = "sandly/TagTypeKey";
 /**
-* Utility object containing factory functions for creating dependency tags.
-*
-* The Tag object provides the primary API for creating both value tags and service tags
-* used throughout the dependency injection system. It's the main entry point for
-* defining dependencies in a type-safe way.
+* Utility object for creating and working with tags.
 */
 const Tag = {
 	of: (id) => {
@@ -200,35 +27,35 @@ const Tag = {
 			[TagTypeKey]: void 0
 		});
 	},
-	Service: (id) => {
-		class Tagged {
-			static [ServiceTagIdKey] = id;
-			[ServiceTagIdKey] = id;
+	id: (tag) => {
+		if (typeof tag === "function") {
+			const customTag = getKey(tag, "Tag");
+			if (customTag !== void 0) return customTag;
+			return tag.name || "AnonymousClass";
 		}
-		return Tagged;
+		return String(tag[ValueTagIdKey]);
 	},
-	id: (tag) => {
-		return typeof tag === "function" ? tag[ServiceTagIdKey] : tag[ValueTagIdKey];
+	isServiceTag: (x) => {
+		if (typeof x !== "function") return false;
+		return x.prototype !== void 0;
+	},
+	isValueTag: (x) => {
+		return typeof x === "object" && x !== null && getKey(x, ValueTagIdKey) !== void 0;
 	},
-	isTag: (tag) => {
-		return typeof tag === "function" ? getKey(tag, ServiceTagIdKey) !== void 0 : getKey(tag, ValueTagIdKey) !== void 0;
+	isTag: (x) => {
+		return Tag.isServiceTag(x) || Tag.isValueTag(x);
 	}
 };
-/**
-* String used to store the original ValueTag in Inject<T> types.
-* This prevents property name collisions while allowing type-level extraction.
-*/
-const InjectSource = "sandly/InjectSource";
 
 //#endregion
 //#region src/errors.ts
 /**
-* Base error class for all library errors.
+* Base error class for all Sandly library errors.
 *
-* This extends the native Error class to provide consistent error handling
+* Extends the native Error class to provide consistent error handling
 * and structured error information across the library.
 *
-* @example Catching library errors
+* @example
 * ```typescript
 * try {
 *   await container.resolve(SomeService);
@@ -248,9 +75,15 @@ var SandlyError = class SandlyError extends Error {
 		this.detail = detail;
 		if (cause instanceof Error && cause.stack !== void 0) this.stack = `${this.stack ?? ""}\nCaused by: ${cause.stack}`;
 	}
+	/**
+	* Wraps any error as a SandlyError.
+	*/
 	static ensure(error) {
 		return error instanceof SandlyError ? error : new SandlyError("An unknown error occurred", { cause: error });
 	}
+	/**
+	* Returns a structured representation of the error for logging.
+	*/
 	dump() {
 		return {
 			name: this.name,
@@ -260,12 +93,14 @@ var SandlyError = class SandlyError extends Error {
 			cause: this.dumpCause(this.cause)
 		};
 	}
+	/**
+	* Returns a JSON string representation of the error.
+	*/
 	dumps() {
 		return JSON.stringify(this.dump());
 	}
 	/**
 	* Recursively extract cause chain from any Error.
-	* Handles both AppError (with dump()) and plain Errors (with cause property).
 	*/
 	dumpCause(cause) {
 		if (cause instanceof SandlyError) return cause.dump();
@@ -281,34 +116,18 @@ var SandlyError = class SandlyError extends Error {
 	}
 };
 /**
-* Error thrown when attempting to register a dependency that has already been instantiated.
-*
-* This error occurs when calling `container.register()` for a tag that has already been instantiated.
-* Registration must happen before any instantiation occurs, as cached instances would still be used
-* by existing dependencies.
-*/
-var DependencyAlreadyInstantiatedError = class extends SandlyError {};
-/**
 * Error thrown when attempting to use a container that has been destroyed.
-*
-* This error occurs when calling `container.resolve()`, `container.register()`, or `container.destroy()`
-* on a container that has already been destroyed. It indicates a programming error where the container
-* is being used after it has been destroyed.
 */
 var ContainerDestroyedError = class extends SandlyError {};
 /**
 * Error thrown when attempting to retrieve a dependency that hasn't been registered.
 *
-* This error occurs when calling `container.resolve(Tag)` for a tag that was never
-* registered via `container.register()`. It indicates a programming error where
-* the dependency setup is incomplete.
-*
 * @example
 * ```typescript
-* const container = Container.empty(); // Empty container
+* const container = Container.builder().build(); // Empty container
 *
 * try {
-*   await c.resolve(UnregisteredService); // This will throw
+*   await container.resolve(UnregisteredService);
 * } catch (error) {
 *   if (error instanceof UnknownDependencyError) {
 *     console.error('Missing dependency:', error.message);
@@ -317,113 +136,57 @@ var ContainerDestroyedError = class extends SandlyError {};
 * ```
 */
 var UnknownDependencyError = class extends SandlyError {
-	/**
-	* @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 ${String(Tag.id(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.
+* Error thrown when a circular dependency is detected during resolution.
 *
-* @example Circular dependency scenario
+* @example
 * ```typescript
-* class ServiceA extends Tag.Service('ServiceA') {}
-* class ServiceB extends Tag.Service('ServiceB') {}
-*
-* const container = Container.empty()
-*   .register(ServiceA, async (ctx) =>
-*     new ServiceA(await ctx.resolve(ServiceB)) // Depends on B
-*   )
-*   .register(ServiceB, async (ctx) =>
-*     new ServiceB(await ctx.resolve(ServiceA)) // Depends on A - CIRCULAR!
-*   );
-*
+* // ServiceA depends on ServiceB, ServiceB depends on ServiceA
 * try {
-*   await c.resolve(ServiceA);
+*   await container.resolve(ServiceA);
 * } catch (error) {
 *   if (error instanceof CircularDependencyError) {
 *     console.error('Circular dependency:', error.message);
-*     // Output: "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
+*     // "Circular dependency detected for ServiceA: ServiceA -> ServiceB -> ServiceA"
 *   }
 * }
 * ```
 */
 var CircularDependencyError = class extends SandlyError {
-	/**
-	* @internal
-	* Creates a CircularDependencyError with the dependency chain information.
-	*
-	* @param tag - The tag where the circular dependency was detected
-	* @param dependencyChain - The chain of dependencies that led to the circular reference
-	*/
 	constructor(tag, dependencyChain) {
 		const chain = dependencyChain.map((t) => Tag.id(t)).join(" -> ");
-		super(`Circular dependency detected for ${String(Tag.id(tag))}: ${chain} -> ${String(Tag.id(tag))}`, { detail: {
+		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.
+* Error thrown when a dependency factory throws 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.
+* For nested dependencies (A depends on B depends on C), use `getRootCause()`
+* to unwrap all layers and get the original error.
 *
-* 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
+* @example
 * ```typescript
-* class DatabaseService extends Tag.Service('DatabaseService') {}
-*
-* const container = Container.empty().register(DatabaseService, () => {
-*   throw new Error('Database connection failed');
-* });
-*
 * try {
-*   await c.resolve(DatabaseService);
+*   await container.resolve(UserService);
 * } catch (error) {
 *   if (error instanceof DependencyCreationError) {
 *     console.error('Failed to create:', error.message);
-*     console.error('Original error:', error.cause);
-*   }
-* }
-* ```
-*
-* @example Getting root cause from nested errors
-* ```typescript
-* // ServiceA -> ServiceB -> ServiceC (ServiceC throws)
-* try {
-*   await container.resolve(ServiceA);
-* } catch (error) {
-*   if (error instanceof DependencyCreationError) {
-*     console.error('Top-level error:', error.message); // "Error creating instance of ServiceA"
 *     const rootCause = error.getRootCause();
-*     console.error('Root cause:', rootCause); // Original error from ServiceC
+*     console.error('Root cause:', rootCause);
 *   }
 * }
 * ```
 */
 var DependencyCreationError = class DependencyCreationError extends SandlyError {
-	/**
-	* @internal
-	* Creates a DependencyCreationError wrapping the original factory error.
-	*
-	* @param tag - The tag of the dependency that failed to be created
-	* @param error - The original error thrown by the factory function
-	*/
 	constructor(tag, error) {
-		super(`Error creating instance of ${String(Tag.id(tag))}`, {
+		super(`Error creating instance of "${Tag.id(tag)}"`, {
 			cause: error,
 			detail: { tag: Tag.id(tag) }
 		});
@@ -431,22 +194,8 @@ var DependencyCreationError = class DependencyCreationError extends SandlyError
 	/**
 	* 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);
-	*   }
-	* }
-	* ```
+	* When dependencies are nested, each level wraps the error.
+	* This method unwraps all layers to get the original error.
 	*/
 	getRootCause() {
 		let current = this.cause;
@@ -457,42 +206,31 @@ var DependencyCreationError = class DependencyCreationError extends SandlyError
 /**
 * 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.
+* Even if some finalizers fail, cleanup continues for all others.
+* This error aggregates all failures.
 *
-* @example Handling finalization errors
+* @example
 * ```typescript
 * try {
 *   await container.destroy();
 * } catch (error) {
 *   if (error instanceof DependencyFinalizationError) {
-*     console.error('Some finalizers failed');
-*     console.error('Error details:', error.detail.errors);
+*     console.error('Cleanup failures:', error.getRootCauses());
 *   }
 * }
 * ```
 */
 var DependencyFinalizationError = class extends SandlyError {
-	/**
-	* @internal
-	* Creates a DependencyFinalizationError aggregating multiple finalizer failures.
-	*
-	* @param errors - Array of errors thrown by individual finalizers
-	*/
 	constructor(errors) {
-		const lambdaErrors = errors.map((error) => SandlyError.ensure(error));
-		super("Error destroying dependency container", {
+		const sandlyErrors = errors.map((error) => SandlyError.ensure(error));
+		super("Error destroying container", {
 			cause: errors[0],
-			detail: { errors: lambdaErrors.map((error) => error.dump()) }
+			detail: { errors: sandlyErrors.map((error) => error.dump()) }
 		});
 		this.errors = errors;
 	}
 	/**
-	* Returns the root causes of the errors that occurred during finalization.
-	*
-	* @returns An array of the errors that occurred during finalization.
-	* You can expect at least one error in the array.
+	* Returns all root cause errors from the finalization failures.
 	*/
 	getRootCauses() {
 		return this.errors;
@@ -519,283 +257,199 @@ var ResolutionContextImpl = class {
 		return results;
 	}
 };
+/**
+* Unique symbol for container type branding.
+*/
 const ContainerTypeId = Symbol.for("sandly/Container");
 /**
-* A type-safe dependency injection container that manages service instantiation,
-* caching, and lifecycle management with support for async dependencies and
-* circular dependency detection.
+* Builder for constructing immutable containers.
 *
-* 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.
+* Use `Container.builder()` to create a builder, then chain `.add()` calls
+* to register dependencies, and finally call `.build()` to create the container.
 *
-* @template TTags - Union type of all registered dependency tags in this container
+* @template TTags - Union type of registered dependency tags
 *
-* @example Basic usage with service tags
+* @example
 * ```typescript
-* import { container, Tag } from 'sandly';
-*
-* class DatabaseService extends Tag.Service('DatabaseService') {
-*   query() { return 'data'; }
-* }
-*
-* class UserService extends Tag.Service('UserService') {
-*   constructor(private db: DatabaseService) {}
-*   getUser() { return this.db.query(); }
-* }
-*
-* const container = Container.empty()
-*   .register(DatabaseService, () => new DatabaseService())
-*   .register(UserService, async (ctx) =>
-*     new UserService(await ctx.resolve(DatabaseService))
-*   );
-*
-* const userService = await c.resolve(UserService);
+* const container = Container.builder()
+*   .add(Database, () => new Database())
+*   .add(UserService, async (ctx) =>
+*     new UserService(await ctx.resolve(Database))
+*   )
+*   .build();
 * ```
+*/
+var ContainerBuilder = class {
+	factories = new Map();
+	finalizers = new Map();
+	/**
+	* Registers a dependency with a factory function or lifecycle object.
+	*
+	* @param tag - The dependency tag (class or ValueTag)
+	* @param spec - Factory function or lifecycle object
+	* @returns The builder with updated type information
+	*/
+	add(tag, spec) {
+		if (typeof spec === "function") {
+			this.factories.set(tag, spec);
+			this.finalizers.delete(tag);
+		} else {
+			this.factories.set(tag, spec.create.bind(spec));
+			if (spec.cleanup) this.finalizers.set(tag, spec.cleanup.bind(spec));
+			else this.finalizers.delete(tag);
+		}
+		return this;
+	}
+	/**
+	* Creates an immutable container from the registered dependencies.
+	*/
+	build() {
+		return Container._createFromBuilder(this.factories, this.finalizers);
+	}
+};
+/**
+* Type-safe dependency injection container.
 *
-* @example Usage with value tags
-* ```typescript
-* const ApiKeyTag = Tag.of('apiKey')<string>();
-* const ConfigTag = Tag.of('config')<{ dbUrl: string }>();
-*
-* const container = Container.empty()
-*   .register(ApiKeyTag, () => process.env.API_KEY!)
-*   .register(ConfigTag, () => ({ dbUrl: 'postgresql://localhost:5432' }));
+* Containers are immutable - use `Container.builder()` to create one.
+* Each dependency is created once (singleton) and cached.
 *
-* const apiKey = await c.resolve(ApiKeyTag);
-* const config = await c.resolve(ConfigTag);
-* ```
+* @template TTags - Union type of registered dependency tags
 *
-* @example With finalizers for cleanup
+* @example
 * ```typescript
-* class DatabaseConnection extends Tag.Service('DatabaseConnection') {
-*   async connect() { return; }
-*   async disconnect() { return; }
+* class Database {
+*   query(sql: string) { return []; }
 * }
 *
-* const container = Container.empty().register(
-*   DatabaseConnection,
-*   async () => {
-*     const conn = new DatabaseConnection();
-*     await conn.connect();
-*     return conn;
-*   },
-*   async (conn) => conn.disconnect() // Finalizer for cleanup
-* );
+* class UserService {
+*   constructor(private db: Database) {}
+*   getUsers() { return this.db.query('SELECT * FROM users'); }
+* }
+*
+* const container = Container.builder()
+*   .add(Database, () => new Database())
+*   .add(UserService, async (ctx) =>
+*     new UserService(await ctx.resolve(Database))
+*   )
+*   .build();
 *
-* // Later...
-* await c.destroy(); // Calls all finalizers
+* const userService = await container.resolve(UserService);
 * ```
 */
 var Container = class Container {
 	[ContainerTypeId];
-	constructor() {}
 	/**
-	* Cache of instantiated dependencies as promises.
-	* Ensures singleton behavior and supports concurrent access.
+	* Cache of instantiated dependencies.
 	* @internal
 	*/
 	cache = new Map();
 	/**
-	* Factory functions for creating dependency instances.
+	* Factory functions for creating dependencies.
 	* @internal
 	*/
-	factories = new Map();
+	factories;
 	/**
-	* Finalizer functions for cleaning up dependencies when the container is destroyed.
+	* Cleanup functions for dependencies.
 	* @internal
 	*/
-	finalizers = new Map();
+	finalizers;
 	/**
-	* Flag indicating whether this container has been destroyed.
+	* Whether this container has been destroyed.
 	* @internal
 	*/
 	isDestroyed = false;
 	/**
-	* Creates a new empty container instance.
-	* @returns A new empty Container instance with no registered dependencies.
+	* @internal - Use Container.builder() or Container.empty()
 	*/
-	static empty() {
-		return new Container();
+	constructor(factories, finalizers) {
+		this.factories = factories;
+		this.finalizers = 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 `.resolve()` calls.
-	*
-	* If a dependency is already registered, this method will override it unless the
-	* dependency has already been instantiated, in which case it will throw an error.
-	*
-	* @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 {ContainerDestroyedError} If the container has been destroyed
-	* @throws {Error} If the dependency has already been instantiated
-	*
-	* @example Registering a simple service
-	* ```typescript
-	* class LoggerService extends Tag.Service('LoggerService') {
-	*   log(message: string) { console.log(message); }
-	* }
-	*
-	* const container = Container.empty().register(
-	*   LoggerService,
-	*   () => new LoggerService()
-	* );
-	* ```
-	*
-	* @example Registering with dependencies
-	* ```typescript
-	* class UserService extends Tag.Service('UserService') {
-	*   constructor(private db: DatabaseService, private logger: LoggerService) {}
-	* }
-	*
-	* const container = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService())
-	*   .register(LoggerService, () => new LoggerService())
-	*   .register(UserService, async (ctx) =>
-	*     new UserService(
-	*       await ctx.resolve(DatabaseService),
-	*       await ctx.resolve(LoggerService)
-	*     )
-	*   );
-	* ```
-	*
-	* @example Overriding a dependency
-	* ```typescript
-	* const container = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService())
-	*   .register(DatabaseService, () => new MockDatabaseService()); // Overrides the previous registration
-	* ```
-	*
-	* @example Using value tags
-	* ```typescript
-	* const ConfigTag = Tag.of('config')<{ apiUrl: string }>();
-	*
-	* const container = Container.empty().register(
-	*   ConfigTag,
-	*   () => ({ apiUrl: 'https://api.example.com' })
-	* );
-	* ```
-	*
-	* @example With finalizer for cleanup
-	* ```typescript
-	* class DatabaseConnection extends Tag.Service('DatabaseConnection') {
-	*   async connect() { return; }
-	*   async close() { return; }
-	* }
-	*
-	* const container = Container.empty().register(
-	*   DatabaseConnection,
-	*   async () => {
-	*     const conn = new DatabaseConnection();
-	*     await conn.connect();
-	*     return conn;
-	*   },
-	*   (conn) => conn.close() // Called during container.destroy()
-	* );
-	* ```
+	* @internal - Used by ContainerBuilder
 	*/
-	register(tag, spec) {
-		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot register dependencies on a destroyed container");
-		if (this.has(tag) && this.exists(tag)) throw new DependencyAlreadyInstantiatedError(`Cannot register dependency ${String(Tag.id(tag))} - it has already been instantiated. Registration must happen before any instantiation occurs, as cached instances would still be used by existing dependencies.`);
-		if (typeof spec === "function") {
-			this.factories.set(tag, spec);
-			this.finalizers.delete(tag);
-		} else {
-			this.factories.set(tag, spec.create.bind(spec));
-			if (spec.cleanup) this.finalizers.set(tag, spec.cleanup.bind(spec));
-			else this.finalizers.delete(tag);
-		}
-		return this;
+	static _createFromBuilder(factories, finalizers) {
+		return new Container(factories, finalizers);
 	}
 	/**
-	* Checks if a dependency has been registered in the container.
-	*
-	* This returns `true` if the dependency has been registered via `.register()`,
-	* regardless of whether it has been instantiated yet.
-	*
-	* @param tag - The dependency tag to check
-	* @returns `true` if the dependency has been registered, `false` otherwise
+	* Creates a new container builder.
 	*
 	* @example
 	* ```typescript
-	* const container = Container.empty().register(DatabaseService, () => new DatabaseService());
-	* console.log(c.has(DatabaseService)); // true
+	* const container = Container.builder()
+	*   .add(Database, () => new Database())
+	*   .build();
 	* ```
 	*/
-	has(tag) {
-		return this.factories.has(tag);
+	static builder() {
+		return new ContainerBuilder();
 	}
 	/**
-	* Checks if a dependency has been instantiated (cached) in the container.
+	* Creates an empty container with no dependencies.
 	*
-	* @param tag - The dependency tag to check
-	* @returns true if the dependency has been instantiated, false otherwise
+	* Shorthand for `Container.builder().build()`.
 	*/
-	exists(tag) {
-		return this.cache.has(tag);
+	static empty() {
+		return Container.builder().build();
 	}
 	/**
-	* Retrieves a dependency instance from the container, creating it if necessary.
+	* Creates a scoped container for hierarchical dependency management.
 	*
-	* 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.
+	* Scoped containers support parent/child relationships where children
+	* can access parent dependencies but maintain their own cache.
 	*
-	* The method performs circular dependency detection by tracking the resolution chain
-	* through the resolution context.
+	* @param scope - Identifier for the scope (for debugging)
 	*
-	* @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
+	* @example
 	* ```typescript
-	* const container = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService());
+	* const appContainer = Container.scoped('app');
+	* // ... add app-level dependencies
 	*
-	* const db = await c.resolve(DatabaseService);
-	* db.query('SELECT * FROM users');
+	* const requestContainer = appContainer.child('request');
+	* // ... add request-specific dependencies
 	* ```
+	*/
+	static scoped(scope) {
+		return ScopedContainer.empty(scope);
+	}
+	/**
+	* Creates a container from a layer.
 	*
-	* @example Concurrent access (singleton behavior)
-	* ```typescript
-	* // All three calls will receive the same instance
-	* const [db1, db2, db3] = await Promise.all([
-	*   c.resolve(DatabaseService),
-	*   c.resolve(DatabaseService),
-	*   c.resolve(DatabaseService)
-	* ]);
+	* This is a convenience method equivalent to applying a layer to
+	* `Container.builder()` and building the result.
 	*
-	* console.log(db1 === db2 === db3); // true
-	* ```
+	* @param layer - A layer with no requirements (all dependencies satisfied)
 	*
-	* @example Dependency injection in factories
+	* @example
 	* ```typescript
-	* const container = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService())
-	*   .register(UserService, async (ctx) => {
-	*     const db = await ctx.resolve(DatabaseService);
-	*     return new UserService(db);
-	*   });
+	* const dbLayer = Layer.service(Database, []);
+	* const container = Container.from(dbLayer);
 	*
-	* const userService = await c.resolve(UserService);
+	* const db = await container.resolve(Database);
 	* ```
 	*/
+	static from(layer) {
+		const builder = Container.builder();
+		const resultBuilder = layer.apply(builder);
+		return resultBuilder.build();
+	}
+	/**
+	* Resolves a dependency, creating it if necessary.
+	*
+	* Dependencies are singletons - the same instance is returned on subsequent calls.
+	*
+	* @param tag - The dependency tag to resolve
+	* @returns Promise resolving to the dependency instance
+	* @throws {ContainerDestroyedError} If the container has been destroyed
+	* @throws {UnknownDependencyError} If any dependency is not registered
+	* @throws {CircularDependencyError} If a circular dependency is detected
+	* @throws {DependencyCreationError} If any factory function throws an error
+	*/
 	async resolve(tag) {
 		return this.resolveInternal(tag, []);
 	}
 	/**
-	* Internal resolution method that tracks the dependency chain for circular dependency detection.
-	* Can be overridden by subclasses (e.g., ScopedContainer) to implement custom resolution logic.
+	* Internal resolution with dependency chain tracking.
 	* @internal
 	*/
 	resolveInternal(tag, chain) {
@@ -806,7 +460,7 @@ var Container = class Container {
 		const factory = this.factories.get(tag);
 		if (factory === void 0) throw new UnknownDependencyError(tag);
 		const newChain = [...chain, tag];
-		const context = new ResolutionContextImpl((tag$1) => this.resolveInternal(tag$1, newChain));
+		const context = new ResolutionContextImpl((t) => this.resolveInternal(t, newChain));
 		const instancePromise = (async () => {
 			try {
 				const instance = await factory(context);
@@ -822,44 +476,14 @@ var Container = class Container {
 		return instancePromise;
 	}
 	/**
-	* Resolves multiple dependencies concurrently using Promise.all.
+	* Resolves multiple dependencies concurrently.
 	*
-	* This method takes a variable number of dependency tags and resolves all of them concurrently,
-	* returning a tuple with the resolved instances in the same order as the input tags.
-	* The method maintains all the same guarantees as the individual resolve method:
-	* singleton behavior, circular dependency detection, and proper error handling.
-	*
-	* @template T - The tuple type of dependency tags to resolve
-	* @param tags - Variable number of dependency tags to resolve
-	* @returns Promise resolving to a tuple of service instances in the same order
+	* @param tags - The dependency tags to resolve
+	* @returns Promise resolving to a tuple of instances
 	* @throws {ContainerDestroyedError} If the container has been destroyed
 	* @throws {UnknownDependencyError} If any dependency is not registered
 	* @throws {CircularDependencyError} If a circular dependency is detected
 	* @throws {DependencyCreationError} If any factory function throws an error
-	*
-	* @example Basic usage
-	* ```typescript
-	* const container = Container.empty()
-	*   .register(DatabaseService, () => new DatabaseService())
-	*   .register(LoggerService, () => new LoggerService());
-	*
-	* const [db, logger] = await c.resolveAll(DatabaseService, LoggerService);
-	* ```
-	*
-	* @example Mixed tag types
-	* ```typescript
-	* const ApiKeyTag = Tag.of('apiKey')<string>();
-	* const container = Container.empty()
-	*   .register(ApiKeyTag, () => 'secret-key')
-	*   .register(UserService, () => new UserService());
-	*
-	* const [apiKey, userService] = await c.resolveAll(ApiKeyTag, UserService);
-	* ```
-	*
-	* @example Empty array
-	* ```typescript
-	* const results = await c.resolveAll(); // Returns empty array
-	* ```
 	*/
 	async resolveAll(...tags) {
 		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot resolve dependencies from a destroyed container");
@@ -868,75 +492,45 @@ var Container = class Container {
 		return results;
 	}
 	/**
-	* Destroys all instantiated dependencies by calling their finalizers and makes the container unusable.
+	* Resolves a service, runs the callback with it, then destroys the container.
 	*
-	* **Important: After calling destroy(), the container becomes permanently unusable.**
-	* 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 DependencyFinalizationError
-	* 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.
+	* This is a convenience method for the common "create, use, destroy" pattern.
+	* The container is always destroyed after the callback completes, even if it throws.
 	*
-	* @returns Promise that resolves when all cleanup is complete
-	* @throws {DependencyFinalizationError} If any finalizers fail during cleanup
+	* @param tag - The dependency tag to resolve
+	* @param fn - Callback that receives the resolved service
+	* @returns Promise resolving to the callback's return value
+	* @throws {ContainerDestroyedError} If the container has been destroyed
+	* @throws {UnknownDependencyError} If the dependency is not registered
+	* @throws {CircularDependencyError} If a circular dependency is detected
+	* @throws {DependencyCreationError} If the factory function throws
+	* @throws {DependencyFinalizationError} If the finalizer function throws
 	*
-	* @example Basic cleanup
+	* @example
 	* ```typescript
-	* const container = Container.empty()
-	*   .register(DatabaseConnection,
-	*     async () => {
-	*       const conn = new DatabaseConnection();
-	*       await conn.connect();
-	*       return conn;
-	*     },
-	*     (conn) => conn.disconnect() // Finalizer
-	*   );
-	*
-	* const db = await c.resolve(DatabaseConnection);
-	* await c.destroy(); // Calls conn.disconnect(), container becomes unusable
-	*
-	* // This will throw an error
-	* try {
-	*   await c.resolve(DatabaseConnection);
-	* } catch (error) {
-	*   console.log(error.message); // "Cannot resolve dependencies from a destroyed container"
-	* }
+	* const result = await container.use(UserService, (service) =>
+	*   service.getUsers()
+	* );
+	* // Container is automatically destroyed after callback completes
 	* ```
+	*/
+	async use(tag, fn) {
+		try {
+			const service = await this.resolve(tag);
+			return await fn(service);
+		} finally {
+			await this.destroy();
+		}
+	}
+	/**
+	* Destroys the container, calling all finalizers.
 	*
-	* @example Application shutdown
-	* ```typescript
-	* const appContainer Container.empty
-	*   .register(DatabaseService, () => new DatabaseService())
-	*   .register(HTTPServer, async (ctx) => new HTTPServer(await ctx.resolve(DatabaseService)));
-	*
-	* // During application shutdown
-	* process.on('SIGTERM', async () => {
-	*   try {
-	*     await appContainer.destroy(); // Clean shutdown of all services
-	*   } catch (error) {
-	*     console.error('Error during shutdown:', error);
-	*   }
-	*   process.exit(0);
-	* });
-	* ```
+	* After destruction, the container cannot be used.
+	* 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.
 	*
-	* @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 destroyed regardless of finalizer errors
-	* ```
+	* @throws {DependencyFinalizationError} If any finalizers fail
 	*/
 	async destroy() {
 		if (this.isDestroyed) return;
@@ -946,167 +540,153 @@ var Container = class Container {
 				return finalizer(dep);
 			});
 			const results = await Promise.allSettled(promises);
-			const failures = results.filter((result) => result.status === "rejected");
-			if (failures.length > 0) throw new DependencyFinalizationError(failures.map((result) => result.reason));
+			const failures = results.filter((r) => r.status === "rejected");
+			if (failures.length > 0) throw new DependencyFinalizationError(failures.map((r) => r.reason));
 		} finally {
 			this.isDestroyed = true;
 			this.cache.clear();
 		}
 	}
 };
-
-//#endregion
-//#region src/dependency.ts
 /**
-* Creates a layer that provides a single dependency with inferred requirements.
+* Builder for constructing scoped containers.
 *
-* This is a simplified alternative to `layer()` for the common case of defining
-* a single dependency. Unlike `service()` and `autoService()`, this works with
-* any tag type (ServiceTag or ValueTag) and doesn't require extending `Tag.Service()`.
-*
-* Requirements are passed as an optional array of tags, allowing TypeScript to infer
-* both the tag type and the requirements automatically - no explicit type
-* parameters needed.
-*
-* @param tag - The tag (ServiceTag or ValueTag) that identifies this dependency
-* @param spec - Factory function or lifecycle object for creating the dependency
-* @param requirements - Optional array of dependency tags this dependency requires (defaults to [])
-* @returns A layer that requires the specified dependencies and provides the tag
-*
-* @example Simple dependency without requirements
-* ```typescript
-* const Config = Tag.of('Config')<{ apiUrl: string }>();
-*
-* // No requirements - can omit the array
-* const configDep = dependency(Config, () => ({
-*   apiUrl: process.env.API_URL!
-* }));
-* ```
+* @template TTags - Union type of registered dependency tags
+*/
+var ScopedContainerBuilder = class {
+	factories = new Map();
+	finalizers = new Map();
+	constructor(scope, parent) {
+		this.scope = scope;
+		this.parent = parent;
+	}
+	/**
+	* Registers a dependency with a factory function or lifecycle object.
+	*/
+	add(tag, spec) {
+		if (typeof spec === "function") {
+			this.factories.set(tag, spec);
+			this.finalizers.delete(tag);
+		} else {
+			this.factories.set(tag, spec.create.bind(spec));
+			if (spec.cleanup) this.finalizers.set(tag, spec.cleanup.bind(spec));
+			else this.finalizers.delete(tag);
+		}
+		return this;
+	}
+	/**
+	* Creates an immutable scoped container from the registered dependencies.
+	*/
+	build() {
+		const child = ScopedContainer._createScopedFromBuilder(this.scope, this.parent, this.factories, this.finalizers);
+		if (this.parent instanceof ScopedContainer) this.parent._registerChild(child);
+		return child;
+	}
+};
+/**
+* Scoped container for hierarchical dependency management.
 *
-* @example Dependency with requirements
-* ```typescript
-* const database = dependency(
-*   Database,
-*   async (ctx) => {
-*     const config = await ctx.resolve(Config);
-*     const logger = await ctx.resolve(Logger);
-*     logger.info('Creating database connection');
-*     return createDb(config.DATABASE);
-*   },
-*   [Config, Logger]
-* );
-* ```
+* Supports parent/child relationships where children can access parent
+* dependencies but maintain their own cache. Useful for request-scoped
+* dependencies in web applications.
 *
-* @example Dependency with lifecycle (create + cleanup)
-* ```typescript
-* const database = dependency(
-*   Database,
-*   {
-*     create: async (ctx) => {
-*       const config = await ctx.resolve(Config);
-*       const logger = await ctx.resolve(Logger);
-*       logger.info('Creating database connection');
-*       return await createDb(config.DATABASE);
-*     },
-*     cleanup: async (db) => {
-*       await disconnectDb(db);
-*     },
-*   },
-*   [Config, Logger]
-* );
-* ```
+* @template TTags - Union type of registered dependency tags
 *
-* @example Comparison with layer()
+* @example
 * ```typescript
-* // Using layer() - verbose, requires explicit type parameters
-* const database = layer<typeof Config | typeof Logger, typeof Database>(
-*   (container) =>
-*     container.register(Database, async (ctx) => {
-*       const config = await ctx.resolve(Config);
-*       return createDb(config.DATABASE);
-*     })
-* );
-*
-* // Using dependency() - cleaner, fully inferred types
-* const database = dependency(
-*   Database,
-*   async (ctx) => {
-*     const config = await ctx.resolve(Config);
-*     return createDb(config.DATABASE);
-*   },
-*   [Config, Logger]
-* );
+* // Application-level container
+* const appContainer = ScopedContainer.builder('app')
+*   .add(Database, () => new Database())
+*   .build();
+*
+* // Request-level container (inherits from app)
+* const requestContainer = appContainer.child('request')
+*   .add(RequestContext, () => new RequestContext())
+*   .build();
+*
+* // Can resolve both app and request dependencies
+* const db = await requestContainer.resolve(Database);
+* const ctx = await requestContainer.resolve(RequestContext);
 * ```
 */
-function dependency(tag, spec, requirements) {
-	return layer((container) => {
-		return container.register(tag, spec);
-	});
-}
-
-//#endregion
-//#region src/scoped-container.ts
 var ScopedContainer = class ScopedContainer extends Container {
 	scope;
 	parent;
 	children = [];
-	constructor(parent, scope) {
-		super();
-		this.parent = parent;
+	/**
+	* @internal
+	*/
+	constructor(scope, parent, factories, finalizers) {
+		super(factories, finalizers);
 		this.scope = scope;
+		this.parent = parent;
 	}
 	/**
-	* Creates a new empty scoped container instance.
-	* @param scope - The scope identifier for this container
-	* @returns A new empty ScopedContainer instance with no registered dependencies
+	* @internal - Used by ScopedContainerBuilder
 	*/
-	static empty(scope) {
-		return new ScopedContainer(null, scope);
+	static _createScopedFromBuilder(scope, parent, factories, finalizers) {
+		return new ScopedContainer(scope, parent, factories, finalizers);
 	}
 	/**
-	* Registers a dependency in the scoped container.
+	* Creates a new scoped container builder.
 	*
-	* Overrides the base implementation to return ScopedContainer type
-	* for proper method chaining support.
+	* @param scope - Identifier for the scope (for debugging)
+	*
+	* @example
+	* ```typescript
+	* const container = ScopedContainer.builder('app')
+	*   .add(Database, () => new Database())
+	*   .build();
+	* ```
 	*/
-	register(tag, spec) {
-		super.register(tag, spec);
-		return this;
+	static builder(scope) {
+		return new ScopedContainerBuilder(scope, null);
 	}
 	/**
-	* Checks if a dependency has been registered in this scope or any parent scope.
-	*
-	* This method checks the current scope first, then walks up the parent chain.
-	* Returns true if the dependency has been registered somewhere in the scope hierarchy.
+	* Creates an empty scoped container with no dependencies.
 	*/
-	has(tag) {
-		if (super.has(tag)) return true;
-		return this.parent?.has(tag) ?? false;
+	static empty(scope) {
+		return ScopedContainer.builder(scope).build();
 	}
 	/**
-	* Checks if a dependency has been instantiated in this scope or any parent scope.
+	* Creates a scoped container from a layer.
 	*
-	* This method checks the current scope first, then walks up the parent chain.
-	* Returns true if the dependency has been instantiated somewhere in the scope hierarchy.
+	* This is a convenience method equivalent to applying a layer to
+	* `ScopedContainer.builder()` and building the result.
+	*
+	* @param scope - Identifier for the scope (for debugging)
+	* @param layer - A layer with no requirements (all dependencies satisfied)
+	*
+	* @example
+	* ```typescript
+	* const dbLayer = Layer.service(Database, []);
+	* const container = ScopedContainer.from('app', dbLayer);
+	*
+	* const db = await container.resolve(Database);
+	* ```
 	*/
-	exists(tag) {
-		if (super.exists(tag)) return true;
-		return this.parent?.exists(tag) ?? false;
+	static from(scope, layer) {
+		const builder = ScopedContainer.builder(scope);
+		const resultBuilder = layer.apply(builder);
+		return resultBuilder.build();
 	}
 	/**
-	* Retrieves a dependency instance, resolving from the current scope or parent scopes.
+	* Resolves a dependency from this scope or parent scopes, creating it if necessary.
 	*
-	* 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
+	* Dependencies are singletons - the same instance is returned on subsequent calls.
+	*
+	* @param tag - The dependency tag to resolve
+	* @returns Promise resolving to the dependency instance
+	* @throws {ContainerDestroyedError} If the container has been destroyed
+	* @throws {UnknownDependencyError} If any dependency is not registered
+	* @throws {CircularDependencyError} If a circular dependency is detected
+	* @throws {DependencyCreationError} If any factory function throws an error
 	*/
 	async resolve(tag) {
 		return this.resolveInternal(tag, []);
 	}
 	/**
-	* Internal resolution with delegation logic for scoped containers.
+	* Internal resolution with parent delegation.
 	* @internal
 	*/
 	resolveInternal(tag, chain) {
@@ -1115,22 +695,76 @@ var ScopedContainer = class ScopedContainer extends Container {
 		throw new UnknownDependencyError(tag);
 	}
 	/**
-	* Destroys this scoped container and its children, preserving the container structure for reuse.
+	* @internal - Used by ScopedContainerBuilder to register children
+	*/
+	_registerChild(child) {
+		this.children.push(new WeakRef(child));
+	}
+	/**
+	* Creates a child container builder that inherits from this container.
 	*
-	* 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
+	* Use this to create a child scope and add dependencies to it.
+	* The child can resolve dependencies from this container.
 	*
-	* Child destruction happens first to ensure dependencies don't get cleaned up
-	* before their dependents.
+	* @param scope - Identifier for the child scope
+	* @returns A new ScopedContainerBuilder for the child scope
+	* @throws {ContainerDestroyedError} If the container has been destroyed
+	*
+	* @example
+	* ```typescript
+	* const requestContainer = appContainer.child('request')
+	*   .add(RequestContext, () => new RequestContext())
+	*   .build();
+	*
+	* await requestContainer.resolve(Database); // From parent
+	* await requestContainer.resolve(RequestContext); // From this scope
+	* ```
+	*/
+	child(scope) {
+		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot create child containers from a destroyed container");
+		return new ScopedContainerBuilder(scope, this);
+	}
+	/**
+	* Creates a child container with a layer applied.
+	*
+	* This is a convenience method combining child() + layer.apply() + build().
+	* Use this when you have a layer ready to apply.
+	*
+	* @param scope - Identifier for the child scope
+	* @param layer - Layer to apply to the child (can require parent's tags)
+	*
+	* @example
+	* ```typescript
+	* const requestContainer = appContainer.childFrom('request',
+	*   userService
+	*     .provide(Layer.value(TenantContext, tenantCtx))
+	*     .provide(Layer.value(RequestId, requestId))
+	* );
+	*
+	* const users = await requestContainer.resolve(UserService);
+	* ```
+	*/
+	childFrom(scope, layer) {
+		return layer.apply(this.child(scope)).build();
+	}
+	/**
+	* Destroys this container and all child containers.
+	*
+	* Children are destroyed first to ensure proper cleanup order.
+	*
+	* After destruction, the container cannot be used.
+	* 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.
+	*
+	* @throws {DependencyFinalizationError} If any finalizers fail
 	*/
 	async destroy() {
 		if (this.isDestroyed) return;
 		const allFailures = [];
-		const childDestroyPromises = this.children.map((weakRef) => weakRef.deref()).filter((child) => child !== void 0).map((child) => child.destroy());
+		const childDestroyPromises = this.children.map((ref) => ref.deref()).filter((child) => child !== void 0).map((child) => child.destroy());
 		const childResults = await Promise.allSettled(childDestroyPromises);
-		const childFailures = childResults.filter((result) => result.status === "rejected").map((result) => result.reason);
+		const childFailures = childResults.filter((r) => r.status === "rejected").map((r) => r.reason);
 		allFailures.push(...childFailures);
 		try {
 			await super.destroy();
@@ -1141,185 +775,152 @@ var ScopedContainer = class ScopedContainer extends Container {
 		}
 		if (allFailures.length > 0) throw new DependencyFinalizationError(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) {
-		if (this.isDestroyed) throw new ContainerDestroyedError("Cannot create child containers from a destroyed container");
-		const child = new ScopedContainer(this, scope);
-		this.children.push(new WeakRef(child));
-		return child;
-	}
 };
 
 //#endregion
-//#region src/service.ts
+//#region src/layer.ts
 /**
-* Creates a service layer from any tag type (ServiceTag or ValueTag) with optional parameters.
-*
-* For ServiceTag 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 (ServiceTag or ValueTag)
-* @param tag - The tag (ServiceTag or ValueTag)
-* @param factory - Factory function for service instantiation with container
-* @returns The service layer
-*
-* @example Simple service without dependencies
-* ```typescript
-* class LoggerService extends Tag.Service('LoggerService') {
-*   log(message: string) { console.log(message); }
-* }
-*
-* const loggerService = service(LoggerService, () => new LoggerService());
-* ```
-*
-* @example Service with dependencies
-* ```typescript
-* class DatabaseService extends Tag.Service('DatabaseService') {
-*   query() { return []; }
-* }
-*
-* class UserService extends Tag.Service('UserService') {
-*   constructor(private db: DatabaseService) {
-*     super();
-*   }
-*
-*   getUsers() { return this.db.query(); }
-* }
-*
-* const userService = service(UserService, async (ctx) =>
-*   new UserService(await ctx.resolve(DatabaseService))
-* );
-* ```
+* The type ID for the Layer interface.
+*/
+const LayerTypeId = Symbol.for("sandly/Layer");
+/**
+* Creates a layer from a builder function.
+* @internal
+*/
+function createLayer(applyFn) {
+	const layerImpl = {
+		apply: applyFn,
+		provide(dependency) {
+			return createProvidedLayer(dependency, layerImpl);
+		},
+		provideMerge(dependency) {
+			return createComposedLayer(dependency, layerImpl);
+		},
+		merge(other) {
+			return createMergedLayer(layerImpl, other);
+		}
+	};
+	return layerImpl;
+}
+/**
+* Creates a layer that only exposes the target's provisions.
+* @internal
 */
-function service(tag, spec) {
-	return layer((container) => {
-		return container.register(tag, spec);
-	});
+function createProvidedLayer(dependency, target) {
+	return createComposedLayer(dependency, target);
 }
 /**
-* Creates a service layer with automatic dependency injection by inferring constructor parameters.
-*
-* This is a convenience function that automatically resolves constructor dependencies and passes
-* both DI-managed dependencies and static values to the service constructor in the correct order.
-* It eliminates the need to manually write factory functions for services with constructor dependencies.
-*
-* @template T - The ServiceTag representing the service class
-* @param tag - The service tag (must be a ServiceTag, not a ValueTag)
-* @param deps - Tuple of constructor parameters in order - mix of dependency tags and static values
-* @param finalizer - Optional cleanup function called when the container is destroyed
-* @returns A service layer that automatically handles dependency injection
+* Creates a composed layer that exposes both layers' provisions.
+* @internal
+*/
+function createComposedLayer(dependency, target) {
+	return {
+		apply: (builder) => {
+			const withDep = dependency.apply(builder);
+			return target.apply(withDep);
+		},
+		provide(dep) {
+			return createProvidedLayer(dep, this);
+		},
+		provideMerge(dep) {
+			return createComposedLayer(dep, this);
+		},
+		merge(other) {
+			return createMergedLayer(this, other);
+		}
+	};
+}
+/**
+* Creates a merged layer from two independent layers.
+* @internal
+*/
+function createMergedLayer(layer1, layer2) {
+	return {
+		apply: (builder) => {
+			const with1 = layer1.apply(builder);
+			return layer2.apply(with1);
+		},
+		provide(dep) {
+			return createProvidedLayer(dep, this);
+		},
+		provideMerge(dep) {
+			return createComposedLayer(dep, this);
+		},
+		merge(other) {
+			return createMergedLayer(this, other);
+		}
+	};
+}
+/**
+* Consolidated Layer API for creating and composing dependency layers.
 *
-* @example Simple service with dependencies
+* @example
 * ```typescript
-* class DatabaseService extends Tag.Service('DatabaseService') {
-*   constructor(private url: string) {
-*     super();
-*   }
-*   connect() { return `Connected to ${this.url}`; }
+* // Define services
+* class Database {
+*   query(sql: string) { return []; }
 * }
 *
-* class UserService extends Tag.Service('UserService') {
-*   constructor(private db: DatabaseService, private timeout: number) {
-*     super();
-*   }
+* class UserService {
+*   constructor(private db: Database) {}
 *   getUsers() { return this.db.query('SELECT * FROM users'); }
 * }
 *
-* // Automatically inject DatabaseService and pass static timeout value
-* const userService = autoService(UserService, [DatabaseService, 5000]);
-* ```
+* // Create layers
+* const dbLayer = Layer.service(Database, []);
+* const userLayer = Layer.service(UserService, [Database]);
 *
-* @example Mixed dependencies and static values
-* ```typescript
-* class NotificationService extends Tag.Service('NotificationService') {
-*   constructor(
-*     private logger: LoggerService,
-*     private apiKey: string,
-*     private retries: number,
-*     private cache: CacheService
-*   ) {
-*     super();
-*   }
-* }
+* // Compose and create container
+* const appLayer = userLayer.provide(dbLayer);
+* const container = Container.from(appLayer);
 *
-* // Mix of DI tags and static values in constructor order
-* const notificationService = autoService(NotificationService, [
-*   LoggerService,    // Will be resolved from container
-*   'secret-api-key', // Static string value
-*   3,                // Static number value
-*   CacheService      // Will be resolved from container
-* ]);
-* ```
-*
-* @example Compared to manual service creation
-* ```typescript
-* // Manual approach (more verbose)
-* const userServiceManual = service(UserService, async (ctx) => {
-*   const db = await ctx.resolve(DatabaseService);
-*   return new UserService(db, 5000);
-* });
-*
-* // Auto approach (concise)
-* const userServiceAuto = autoService(UserService, [DatabaseService, 5000]);
-* ```
-*
-* @example With finalizer for cleanup
-* ```typescript
-* class DatabaseService extends Tag.Service('DatabaseService') {
-*   constructor(private connectionString: string) {
-*     super();
-*   }
-*
-*   private connection: Connection | null = null;
-*
-*   async connect() {
-*     this.connection = await createConnection(this.connectionString);
-*   }
-*
-*   async disconnect() {
-*     if (this.connection) {
-*       await this.connection.close();
-*       this.connection = null;
-*     }
-*   }
-* }
-*
-* // Service with automatic cleanup
-* const dbService = autoService(
-*   DatabaseService,
-* 	 {
-* 		dependencies: ['postgresql://localhost:5432/mydb'],
-* 		cleanup: (service) => service.disconnect() // Finalizer for cleanup
-* 	 }
-* );
+* const users = await container.resolve(UserService);
 * ```
 */
-function autoService(tag, spec) {
-	if (Array.isArray(spec)) spec = { dependencies: spec };
-	const create = async (ctx) => {
-		const diDeps = [];
-		for (const dep of spec.dependencies) if (Tag.isTag(dep)) diDeps.push(dep);
-		const resolved = await ctx.resolveAll(...diDeps);
-		const args = [];
-		let resolvedIndex = 0;
-		for (const dep of spec.dependencies) if (Tag.isTag(dep)) args.push(resolved[resolvedIndex++]);
-		else args.push(dep);
-		return new tag(...args);
-	};
-	return service(tag, {
-		create,
-		cleanup: spec.cleanup
-	});
-}
+const Layer = {
+	service(cls, deps, options) {
+		return createLayer((builder) => {
+			return builder.add(cls, {
+				create: async (ctx) => {
+					const args = await Promise.all(deps.map((dep) => Tag.isTag(dep) ? ctx.resolve(dep) : dep));
+					return new cls(...args);
+				},
+				cleanup: options?.cleanup
+			});
+		});
+	},
+	value(tag, value) {
+		return createLayer((builder) => {
+			return builder.add(tag, () => value);
+		});
+	},
+	create(options) {
+		const layer = {
+			apply: (builder) => {
+				return options.apply(builder);
+			},
+			provide(dep) {
+				return createProvidedLayer(dep, layer);
+			},
+			provideMerge(dep) {
+				return createComposedLayer(dep, layer);
+			},
+			merge(other) {
+				return createMergedLayer(layer, other);
+			}
+		};
+		return layer;
+	},
+	empty() {
+		return createLayer((builder) => builder);
+	},
+	mergeAll(...layers) {
+		return layers.reduce((acc, layer) => acc.merge(layer));
+	},
+	merge(layer1, layer2) {
+		return layer1.merge(layer2);
+	}
+};
 
 //#endregion
-export { CircularDependencyError, Container, ContainerDestroyedError, DependencyAlreadyInstantiatedError, DependencyCreationError, DependencyFinalizationError, InjectSource, Layer, SandlyError, ScopedContainer, Tag, UnknownDependencyError, autoService, constant, dependency, layer, service };
+export { CircularDependencyError, Container, ContainerBuilder, ContainerDestroyedError, DependencyCreationError, DependencyFinalizationError, Layer, SandlyError, ScopedContainer, ScopedContainerBuilder, Tag, UnknownDependencyError };