sandly 0.4.0 → 0.5.1

package/README.md

@@ -74,8 +74,8 @@ class UserRepository extends Tag.Service('UserRepository') {
 // Register services with their factories
 const container = Container.empty()
 	.register(Database, {
-		factory: () => new Database(),
-		finalizer: (db) => db.close(), // Cleanup when container is destroyed
+		create: () => new Database(),
+		cleanup: (db) => db.close(), // Cleanup when container is destroyed
 	})
 	.register(
 		UserRepository,
@@ -106,8 +106,8 @@ import { layer, autoService, Container } from 'sandly';
 // Layer that provides Database
 const databaseLayer = layer<never, typeof Database>((container) =>
 	container.register(Database, {
-		factory: () => new Database(),
-		finalizer: (db) => db.close(),
+		create: () => new Database(),
+		cleanup: (db) => db.close(),
 	})
 );
 
@@ -330,12 +330,12 @@ class DatabaseConnection extends Tag.Service('DatabaseConnection') {
 }
 
 const container = Container.empty().register(DatabaseConnection, {
-	factory: async () => {
+	create: async () => {
 		const db = new DatabaseConnection();
 		await db.connect(); // Async initialization
 		return db;
 	},
-	finalizer: async (db) => {
+	cleanup: async (db) => {
 		await db.disconnect(); // Async cleanup
 	},
 });
@@ -485,7 +485,7 @@ Before diving into detailed usage, let's understand the four main building block
 
 ### Tags
 
-Tags are unique identifiers for dependencies. They come in two flavors:
+Tags are unique tokens that represent dependencies and serve as a way to reference them in the container. They come in two flavors:
 
 **ServiceTag** - For class-based dependencies. Created by extending `Tag.Service()`:
 
@@ -507,7 +507,7 @@ const ApiKeyTag = Tag.of('ApiKey')<string>();
 const ConfigTag = Tag.of('Config')<{ port: number }>();
 ```
 
-ValueTags separate the identifier from the value type. The string identifier must be unique, which is why configuration values are the main use case (be careful with generic names like `'port'` or `'config'` - prefer namespaced identifiers like `'app.port'`).
+ValueTags separate the identifier from the value type. The string identifier should be unique in order to avoid collisions in TypeScript type error reporting. The main use-case for ValueTags is for injecting configuration values. Be careful with generic names like `'ApiKey'` or `'Config'` - prefer specific identifiers like `'ThirdPartyApiKey'` or `'HttpClientConfig'`.
 
 ### Container
 
@@ -712,7 +712,7 @@ console.log(logger1 === logger2); // true
 
 #### Finalizers for Cleanup
 
-Register finalizers to clean up resources when the container is destroyed:
+Register finalizers to clean up resources when the container is destroyed. They receive the created instance and should perform any necessary cleanup (closing connections, releasing resources, etc.):
 
 ```typescript
 class DatabaseConnection extends Tag.Service('DatabaseConnection') {
@@ -735,12 +735,14 @@ class DatabaseConnection extends Tag.Service('DatabaseConnection') {
 }
 
 const container = Container.empty().register(DatabaseConnection, {
-	factory: async () => {
+	// Factory
+	create: async () => {
 		const db = new DatabaseConnection();
 		await db.connect();
 		return db;
 	},
-	finalizer: async (db) => {
+	// Finalizer
+	cleanup: async (db) => {
 		await db.disconnect();
 	},
 });
@@ -754,25 +756,103 @@ await container.destroy();
 // Output: "Disconnected"
 ```
 
+You can also implement `DependencyLifecycle` as a class for better organization and reuse:
+
+```typescript
+import {
+	Container,
+	Tag,
+	type DependencyLifecycle,
+	type ResolutionContext,
+} from 'sandly';
+
+class Logger extends Tag.Service('Logger') {
+	log(message: string) {
+		console.log(message);
+	}
+}
+
+class DatabaseConnection extends Tag.Service('DatabaseConnection') {
+	constructor(
+		private logger: Logger,
+		private url: string
+	) {
+		super();
+	}
+	async connect() {
+		this.logger.log('Connected');
+	}
+	async disconnect() {
+		this.logger.log('Disconnected');
+	}
+}
+
+class DatabaseLifecycle
+	implements DependencyLifecycle<DatabaseConnection, typeof Logger>
+{
+	constructor(private url: string) {}
+
+	async create(
+		ctx: ResolutionContext<typeof Logger>
+	): Promise<DatabaseConnection> {
+		const logger = await ctx.resolve(Logger);
+		const db = new DatabaseConnection(logger, this.url);
+		await db.connect();
+		return db;
+	}
+
+	async cleanup(db: DatabaseConnection): Promise<void> {
+		await db.disconnect();
+	}
+}
+
+const container = Container.empty()
+	.register(Logger, () => new Logger())
+	.register(
+		DatabaseConnection,
+		new DatabaseLifecycle('postgresql://localhost:5432')
+	);
+```
+
+The `cleanup` method is optional, so you can implement classes with only a `create` method:
+
+```typescript
+import { Container, Tag, type DependencyLifecycle } from 'sandly';
+
+class SimpleService extends Tag.Service('SimpleService') {}
+
+class SimpleServiceFactory
+	implements DependencyLifecycle<SimpleService, never>
+{
+	create(): SimpleService {
+		return new SimpleService();
+	}
+	// cleanup is optional
+}
+
+const container = Container.empty().register(
+	SimpleService,
+	new SimpleServiceFactory()
+);
+```
+
 All finalizers run concurrently when you call `destroy()`:
 
 ```typescript
 const container = Container.empty()
 	.register(Database, {
-		factory: () => new Database(),
-		finalizer: (db) => db.close(),
+		create: () => new Database(),
+		cleanup: (db) => db.close(),
 	})
 	.register(Cache, {
-		factory: () => new Cache(),
-		finalizer: (cache) => cache.clear(),
+		create: () => new Cache(),
+		cleanup: (cache) => cache.clear(),
 	});
 
 // Both finalizers run in parallel
 await container.destroy();
 ```
 
-If any finalizer fails, cleanup continues for others and a `DependencyFinalizationError` is thrown with details of all failures.
-
 #### Overriding Registrations
 
 You can override a registration before it's instantiated:
@@ -934,6 +1014,51 @@ try {
 }
 ```
 
+#### Finalization Errors
+
+If any finalizer fails, cleanup continues for others and a `DependencyFinalizationError` is thrown with details of all failures:
+
+```typescript
+class Database extends Tag.Service('Database') {
+	async close() {
+		throw new Error('Database close failed');
+	}
+}
+
+class Cache extends Tag.Service('Cache') {
+	async clear() {
+		throw new Error('Cache clear failed');
+	}
+}
+
+const container = Container.empty()
+	.register(Database, {
+		create: () => new Database(),
+		cleanup: async (db) => db.close(),
+	})
+	.register(Cache, {
+		create: () => new Cache(),
+		cleanup: async (cache) => cache.clear(),
+	});
+
+await container.resolve(Database);
+await container.resolve(Cache);
+
+try {
+	await container.destroy();
+} catch (error) {
+	if (error instanceof DependencyFinalizationError) {
+		// Get all original errors that caused the finalization failure
+		const rootCauses = error.getRootCauses();
+		console.error('Finalization failures:', rootCauses);
+		// [
+		//   Error: Database close failed,
+		//   Error: Cache clear failed
+		// ]
+	}
+}
+```
+
 ### Type Safety in Action
 
 The container's type parameter tracks all registered dependencies:
@@ -995,18 +1120,6 @@ container.register(Logger, () => new Logger());
 // TypeScript doesn't track these registrations
 ```
 
-**Use namespaced identifiers for ValueTags** - Prevents collisions:
-
-```typescript
-// ❌ Generic names can collide
-const Port = Tag.of('port')<number>();
-const Timeout = Tag.of('timeout')<number>();
-
-// ✅ Namespaced identifiers
-const ServerPort = Tag.of('server.port')<number>();
-const HttpTimeout = Tag.of('http.timeout')<number>();
-```
-
 **Prefer layers for multiple dependencies** - Once you have larger numbers of services and more complex dependency graphs, layers become cleaner. See the next section for more details.
 
 **Handle cleanup errors** - Finalizers can fail:
@@ -1022,6 +1135,39 @@ try {
 }
 ```
 
+**Avoid resolving during registration if possible** - Once you resolve a dependency, the container will cache it and you won't be able to override the registration. This might become problematic in case you're composing layers and multiple layers reference the same layer in their provisions (see more on layers below). It's better to keep registration and resolution separate:
+
+```typescript
+// ❌ Bad - resolving during setup creates timing issues
+const container = Container.empty().register(Logger, () => new Logger());
+
+const logger = await container.resolve(Logger); // During setup!
+
+container.register(Database, () => new Database());
+
+// ✅ Good - register everything first, then resolve
+const container = Container.empty()
+	.register(Logger, () => new Logger())
+	.register(Database, () => new Database());
+
+// Now use services
+const logger = await container.resolve(Logger);
+```
+
+However, it's perfectly fine to resolve and even use dependencies inside another dependency factory function.
+
+```typescript
+// ✅ Also good - resolve dependency inside factory function during the registration
+const container = Container.empty()
+	.register(Logger, () => new Logger())
+	.register(Database, (ctx) => {
+		const db = new Database();
+		const logger = await ctx.resolve(Logger);
+		logger.log('Database created successfully');
+		return db;
+	});
+```
+
 ## Working with Layers
 
 Layers are the recommended approach for organizing dependencies in larger applications. While direct container registration works well for small projects, layers provide better code organization, reusability, and developer experience as your application grows.
@@ -1410,12 +1556,12 @@ const userRepositoryLayer = service(UserRepository, async (ctx) => {
 
 // With finalizer
 const databaseLayer = service(Database, {
-	factory: async () => {
+	create: async () => {
 		const db = new Database();
 		await db.connect();
 		return db;
 	},
-	finalizer: (db) => db.disconnect(),
+	cleanup: (db) => db.disconnect(),
 });
 ```
 
@@ -1474,12 +1620,12 @@ const apiClientLayer = autoService(ApiClient, [
 
 **Important**: ValueTag dependencies in constructors must be annotated with `Inject<typeof YourTag>`. This preserves type information for `service()` and `autoService()` to infer the dependency. Without `Inject<>`, TypeScript sees it as a regular value and `service()` and `autoService()` won't know to resolve it from the container.
 
-With finalizer:
+With cleanup:
 
 ```typescript
 const databaseLayer = autoService(Database, {
 	dependencies: ['postgresql://localhost:5432/mydb'],
-	finalizer: (db) => db.disconnect(),
+	cleanup: (db) => db.disconnect(),
 });
 ```
 
@@ -1921,13 +2067,13 @@ But use `service()` when you need custom logic:
 ```typescript
 // ✅ Good - custom initialization logic
 const databaseLayer = service(Database, {
-	factory: async () => {
+	create: async () => {
 		const db = new Database();
 		await db.connect();
 		await db.runMigrations();
 		return db;
 	},
-	finalizer: (db) => db.disconnect(),
+	cleanup: (db) => db.disconnect(),
 });
 ```
 
@@ -2277,23 +2423,23 @@ When a scope is destroyed, finalizers run in this order:
 
 ```typescript
 const appScope = ScopedContainer.empty('app').register(Database, {
-	factory: () => new Database(),
-	finalizer: (db) => {
+	create: () => new Database(),
+	cleanup: (db) => {
 		console.log('Closing database');
 		return db.close();
 	},
 });
 
 const request1 = appScope.child('request-1').register(RequestContext, {
-	factory: () => new RequestContext('req-1'),
-	finalizer: (ctx) => {
+	create: () => new RequestContext('req-1'),
+	cleanup: (ctx) => {
 		console.log('Cleaning up request-1');
 	},
 });
 
 const request2 = appScope.child('request-2').register(RequestContext, {
-	factory: () => new RequestContext('req-2'),
-	finalizer: (ctx) => {
+	create: () => new RequestContext('req-2'),
+	cleanup: (ctx) => {
 		console.log('Cleaning up request-2');
 	},
 });
@@ -2565,8 +2711,7 @@ const service = await container.resolve(UserService); // Type-safe
 | -------------------------- | ------- | ---------- | --------------------- | -------- | --------- |
 | Compile-time type safety   | ✅ Full | ❌ None    | ⚠️ Partial            | ❌ None  | ✅ Full   |
 | No experimental decorators | ✅      | ❌         | ❌                    | ❌       | ✅        |
-| Async factories            | ✅      | ✅         | ❌                    | ❌       | ✅        |
-| Async finalizers           | ✅      | ✅         | ❌                    | ❌       | ✅        |
+| Async lifecycle methods    | ✅      | ✅         | ❌                    | ❌       | ✅        |
 | Framework-agnostic         | ✅      | ❌         | ✅                    | ✅       | ✅        |
 | Learning curve             | Low     | Medium     | Medium                | Low      | Very High |
 | Bundle size                | Small   | Large      | Medium                | Small    | Large     |