sandly 0.4.0 → 0.5.1

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandly",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "keywords": [
     "typescript",
     "sandly",