sandly 2.0.1 → 3.0.0

package/README.md

@@ -1,6 +1,18 @@
-# Sandly
-
-Sandly ("Services And Layers") is a type-safe dependency injection library for TypeScript. No decorators, no runtime reflection, just compile-time safety that catches errors before your code runs.
+<h1 align="center">Sandly</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sandly"><img src="https://img.shields.io/npm/v/sandly?color=3178c6&label=npm" alt="npm version"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0%2B-blue?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://codecov.io/gh/borisrakovan/sandly"><img src="https://codecov.io/gh/borisrakovan/sandly/branch/main/graph/badge.svg" alt="coverage"></a>
+  <br />
+  <a href="https://github.com/borisrakovan/sandly/actions/workflows/ci.yml"><img src="https://github.com/borisrakovan/sandly/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/borisrakovan/sandly/blob/main/LICENSE"><img src="https://img.shields.io/github/license/borisrakovan/sandly" alt="license"></a>
+  <a href="https://github.com/borisrakovan/sandly"><img src="https://img.shields.io/github/stars/borisrakovan/sandly?style=social" alt="GitHub stars"></a>
+</p>
+
+<p align="center">
+  Type-safe dependency injection for TypeScript, without decorators or reflection.
+</p>
 
 ## Why Sandly?
 
@@ -40,6 +52,7 @@ const orders = await container.resolve(OrderService);
 
 - **Compile-time safety**: TypeScript catches missing dependencies before runtime
 - **No decorators**: Works with standard TypeScript, no experimental features
+- **Inject anything**: Classes, objects, primitives, or functions
 - **Async support**: Factories and cleanup functions can be async
 - **Composable layers**: Organize dependencies into reusable modules
 - **Scoped containers**: Hierarchical dependency management for web servers
@@ -183,19 +196,23 @@ const cacheLayer = Layer.create({
 });
 ```
 
-Compose layers with `provide()`, `provideMerge()`, and `merge()`:
+Compose layers with `provide()` and `merge()`:
 
 ```typescript
 // provide: satisfy dependencies, expose only this layer's provisions
 const appLayer = userLayer.provide(dbLayer);
 
-// merge: combine independent layers
-const infraLayer = Layer.merge(dbLayer, loggerLayer);
-// or
-const infraLayer = Layer.mergeAll(dbLayer, loggerLayer, cacheLayer);
+// merge: combine layers, exposing both provisions. Internally satisfied
+// requirements are subtracted from the result's requirements.
+const infraLayer = dbLayer.merge(loggerLayer);
+
+// merge wires dependencies in either direction. dbLayer requires Config and
+// configLayer provides it - the result has no outstanding requirements.
+const fullInfra = dbLayer.merge(configLayer);
 
-// provideMerge: satisfy dependencies and expose both layers
-const fullLayer = userLayer.provideMerge(dbLayer);
+// Static helpers for two or more layers
+const appInfra = Layer.merge(dbLayer, loggerLayer);
+const infra = Layer.mergeAll(dbLayer, loggerLayer, cacheLayer);
 ```
 
 ### Scoped Containers
@@ -276,12 +293,35 @@ const dbLayer = Layer.service(Database, [], {
 const ApiKeyTag = Tag.of('apiKey')<string>();
 const configLayer = Layer.value(ApiKeyTag, process.env.API_KEY!);
 
-// ServiceTag (pre-instantiated instances, useful for testing)
+// ServiceTag (pre-instantiated instances)
 class UserService {
-  getUsers() { return []; }
+	getUsers() {
+		return [];
+	}
 }
-const mockUserService = new UserService();
-const testLayer = Layer.value(UserService, mockUserService);
+const userService = new UserService();
+const testLayer = Layer.value(UserService, userService);
+```
+
+**Layer.mock**: Partial mocks for testing (ServiceTags only)
+
+```typescript
+class UserService {
+	constructor(private db: Database) {}
+	getUsers() {
+		return this.db.query('SELECT * FROM users');
+	}
+	getUserById(id: number) {
+		return this.db.query(`...`);
+	}
+}
+
+// Mock only the methods you need - no constructor dependencies required
+const testLayer = Layer.mock(UserService, {
+	getUsers: () => Promise.resolve([{ id: 1, name: 'Alice' }]),
+});
+
+// TypeScript still validates the mock's method signatures
 ```
 
 **Layer.create**: Custom factory logic
@@ -453,17 +493,17 @@ try {
 
 ### Layer
 
-| Method                                 | Description                       |
-| -------------------------------------- | --------------------------------- |
-| `Layer.service(class, deps, options?)` | Create layer for a class          |
-| `Layer.value(tag, value)`              | Create layer for a constant value |
-| `Layer.create({ requires, apply })`    | Create custom layer               |
-| `Layer.empty()`                        | Create empty layer                |
-| `Layer.merge(a, b)`                    | Merge two layers                  |
-| `Layer.mergeAll(...layers)`            | Merge multiple layers             |
-| `layer.provide(dep)`                   | Satisfy dependencies              |
-| `layer.provideMerge(dep)`              | Satisfy and merge provisions      |
-| `layer.merge(other)`                   | Merge with another layer          |
+| Method                                 | Description                                     |
+| -------------------------------------- | ----------------------------------------------- |
+| `Layer.service(class, deps, options?)` | Create layer for a class                        |
+| `Layer.value(tag, value)`              | Create layer for a constant value               |
+| `Layer.mock(tag, implementation)`      | Create layer with mock (partial for ServiceTag) |
+| `Layer.create({ requires, apply })`    | Create custom layer                             |
+| `Layer.empty()`                        | Create empty layer                              |
+| `Layer.merge(a, b)`                    | Merge two layers (smart subtraction)            |
+| `Layer.mergeAll(...layers)`            | Merge multiple layers (smart subtraction)       |
+| `layer.provide(dep)`                   | Satisfy dependencies, expose only target's      |
+| `layer.merge(other)`                   | Merge layers, expose both, subtract satisfied   |
 
 ### ScopedContainer
 
@@ -483,6 +523,57 @@ try {
 | `Tag.id(tag)`      | Get tag's string identifier |
 | `Tag.isTag(value)` | Check if value is a tag     |
 
+## Testing
+
+Sandly makes testing easy with `Layer.mock()`, which allows you to create partial mocks without satisfying constructor dependencies. Import your production layers and override dependencies with mocks:
+
+```typescript
+// Production code (e.g., src/services/user-service.ts)
+import { Layer } from 'sandly';
+import { ResourcesRepository } from '../repositories/resources-repository';
+
+export class UserService {
+	constructor(private repo: ResourcesRepository) {}
+	async getUsers() {
+		return this.repo.listByCrawlId('crawl-123');
+	}
+}
+
+// Layer definition in the same file
+export const userServiceLayer = Layer.service(UserService, [
+	ResourcesRepository,
+]);
+
+// Test file (e.g., src/services/user-service.test.ts)
+import { Container, Layer } from 'sandly';
+import { userServiceLayer } from './user-service';
+import { ResourcesRepository } from '../repositories/resources-repository';
+
+// Override production dependencies with mocks
+const testLayer = userServiceLayer.provide(
+	Layer.mock(ResourcesRepository, {
+		listByCrawlId: async () => [
+			{ id: '1', name: 'Alice' },
+			{ id: '2', name: 'Bob' },
+		],
+	})
+);
+
+const container = Container.from(testLayer);
+const userService = await container.resolve(UserService);
+
+// Use the service - mock is automatically injected
+const users = await userService.getUsers();
+expect(users).toHaveLength(2);
+```
+
+**Benefits:**
+
+- ✅ No need to satisfy constructor dependencies for mocks
+- ✅ TypeScript validates mock method signatures
+- ✅ Works seamlessly with `Layer.service()` composition
+- ✅ Clear intent: `mock()` for tests, `value()` for production
+
 ## Comparison with Alternatives
 
 | Feature                    | Sandly | NestJS | InversifyJS | TSyringe |

package/dist/index.d.ts

@@ -239,6 +239,9 @@ interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
    * Provides a dependency layer to this layer, creating a pipeline.
    * The result only exposes this layer's provisions (not the dependency's).
    *
+   * Requirements satisfied internally (by either layer's provisions) are
+   * subtracted from the result's requirements.
+   *
    * @example
    * ```typescript
    * const appLayer = apiLayer
@@ -246,28 +249,26 @@ interface Layer<TRequires extends AnyTag, TProvides extends AnyTag> {
    *   .provide(databaseLayer);
    * ```
    */
-  provide: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides>;
+  provide: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<Exclude<TRequires | TDepRequires, TProvides | TDepProvides>, TProvides>;
   /**
-   * Provides a dependency layer and merges both layers' provisions.
-   * Unlike `.provide()`, this exposes both this layer's and the dependency's provisions.
+   * Merges this layer with another layer, exposing both layers' provisions.
    *
-   * @example
-   * ```typescript
-   * const infraLayer = dbLayer.provideMerge(configLayer);
-   * // Provides both Database and Config
-   * ```
-   */
-  provideMerge: <TDepRequires extends AnyTag, TDepProvides extends AnyTag>(dependency: Layer<TDepRequires, TDepProvides>) => Layer<TDepRequires | Exclude<TRequires, TDepProvides>, TProvides | TDepProvides>;
-  /**
-   * Merges this layer with another independent layer.
-   * Combines their requirements and provisions.
+   * Requirements satisfied internally (by either layer's provisions) are
+   * subtracted from the result's requirements. This means a merge of two
+   * layers where one provides what the other requires produces a layer with
+   * those requirements already satisfied.
    *
    * @example
    * ```typescript
+   * // Independent layers
    * const infraLayer = persistenceLayer.merge(loggingLayer);
+   *
+   * // Self-satisfying merge: dbLayer requires Config, configLayer provides it
+   * const fullInfra = dbLayer.merge(configLayer);
+   * // Result: requires nothing, provides Database | Config
    * ```
    */
-  merge: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<TRequires | TOtherRequires, TProvides | TOtherProvides>;
+  merge: <TOtherRequires extends AnyTag, TOtherProvides extends AnyTag>(other: Layer<TOtherRequires, TOtherProvides>) => Layer<Exclude<TRequires | TOtherRequires, TProvides | TOtherProvides>, TProvides | TOtherProvides>;
 }
 /**
  * Consolidated Layer API for creating and composing dependency layers.
@@ -352,6 +353,46 @@ declare const Layer: {
    * ```
    */
   value<T extends AnyTag>(tag: T, value: TagType<T>): Layer<never, T>;
+  /**
+   * Creates a layer with a mock implementation for testing.
+   *
+   * Similar to `Layer.value()`, but allows partial implementations for ServiceTags,
+   * making it easier to create test mocks without satisfying constructor dependencies.
+   *
+   * **Use this for testing only.** For production code, use `Layer.value()` or `Layer.service()`.
+   *
+   * @param tag - The tag (ServiceTag or ValueTag) to register
+   * @param implementation - The mock implementation (can be partial for ServiceTags)
+   *
+   * @example ServiceTag with partial mock
+   * ```typescript
+   * class UserService {
+   *   constructor(private db: Database) {}
+   *   getUsers() { return this.db.query('SELECT * FROM users'); }
+   * }
+   *
+   * // Mock only the methods you need - no need to satisfy constructor
+   * const testLayer = Layer.mock(UserService, {
+   *   getUsers: () => Promise.resolve([{ id: 1, name: 'Alice' }])
+   * });
+   * ```
+   *
+   * @example ServiceTag with full mock instance
+   * ```typescript
+   * const mockUserService = {
+   *   getUsers: () => Promise.resolve([])
+   * } as UserService;
+   *
+   * const testLayer = Layer.mock(UserService, mockUserService);
+   * ```
+   *
+   * @example ValueTag (works same as Layer.value)
+   * ```typescript
+   * const ConfigTag = Tag.of('config')<{ port: number }>();
+   * const testLayer = Layer.mock(ConfigTag, { port: 3000 });
+   * ```
+   */
+  mock<T extends AnyTag>(tag: T, implementation: T extends ServiceTag ? Partial<TagType<T>> | TagType<T> : TagType<T>): Layer<never, T>;
   /**
    * Creates a custom layer with full control over the factory logic.
    *
@@ -403,8 +444,11 @@ declare const Layer: {
   /**
    * Merges multiple layers at once.
    *
+   * Requirements satisfied internally (by any merged layer's provisions)
+   * are subtracted from the result's requirements.
+   *
    * @param layers - At least 2 layers to merge
-   * @returns A layer combining all requirements and provisions
+   * @returns A layer combining all provisions, with internally-satisfied requirements removed
    *
    * @example
    * ```typescript
@@ -415,12 +459,12 @@ declare const Layer: {
    * );
    * ```
    */
-  mergeAll<T extends readonly [AnyLayer, AnyLayer, ...AnyLayer[]]>(...layers: T): Layer<UnionOfRequires<T>, UnionOfProvides<T>>;
+  mergeAll<T extends readonly [AnyLayer, AnyLayer, ...AnyLayer[]]>(...layers: T): Layer<Exclude<UnionOfRequires<T>, UnionOfProvides<T>>, UnionOfProvides<T>>;
   /**
    * Merges exactly two layers.
    * Equivalent to `layer1.merge(layer2)`.
    */
-  merge<TRequires1 extends AnyTag, TProvides1 extends AnyTag, TRequires2 extends AnyTag, TProvides2 extends AnyTag>(layer1: Layer<TRequires1, TProvides1>, layer2: Layer<TRequires2, TProvides2>): Layer<TRequires1 | TRequires2, TProvides1 | TProvides2>;
+  merge<TRequires1 extends AnyTag, TProvides1 extends AnyTag, TRequires2 extends AnyTag, TProvides2 extends AnyTag>(layer1: Layer<TRequires1, TProvides1>, layer2: Layer<TRequires2, TProvides2>): Layer<Exclude<TRequires1 | TRequires2, TProvides1 | TProvides2>, TProvides1 | TProvides2>;
 };
 
 //#endregion

package/dist/index.js

@@ -793,9 +793,6 @@ function createLayer(applyFn) {
 		provide(dependency) {
 			return createProvidedLayer(dependency, layerImpl);
 		},
-		provideMerge(dependency) {
-			return createComposedLayer(dependency, layerImpl);
-		},
 		merge(other) {
 			return createMergedLayer(layerImpl, other);
 		}
@@ -804,52 +801,38 @@ function createLayer(applyFn) {
 }
 /**
 * Creates a layer that only exposes the target's provisions.
+*
+* Runtime is identical to merge: both layers' factories are added to the
+* builder, and resolutions across them work transparently. Only the result
+* type narrows provisions to the target's.
 * @internal
 */
 function createProvidedLayer(dependency, target) {
-	return createComposedLayer(dependency, target);
-}
-/**
-* 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);
-		}
-	};
+	return createMergedLayer(dependency, target);
 }
 /**
-* Creates a merged layer from two independent layers.
+* Creates a merged layer from two layers, exposing both layers' provisions.
+*
+* Requirements satisfied internally (by either layer's provisions) are
+* subtracted from the result's requirements at the type level. The runtime
+* behavior is unchanged - both layers' factories are added to the builder
+* and resolutions are wired transparently in either direction.
 * @internal
 */
 function createMergedLayer(layer1, layer2) {
-	return {
+	const merged = {
 		apply: (builder) => {
 			const with1 = layer1.apply(builder);
 			return layer2.apply(with1);
 		},
 		provide(dep) {
-			return createProvidedLayer(dep, this);
-		},
-		provideMerge(dep) {
-			return createComposedLayer(dep, this);
+			return createProvidedLayer(dep, merged);
 		},
 		merge(other) {
-			return createMergedLayer(this, other);
+			return createMergedLayer(merged, other);
 		}
 	};
+	return merged;
 }
 /**
 * Consolidated Layer API for creating and composing dependency layers.
@@ -894,6 +877,11 @@ const Layer = {
 			return builder.add(tag, () => value);
 		});
 	},
+	mock(tag, implementation) {
+		return createLayer((builder) => {
+			return builder.add(tag, () => implementation);
+		});
+	},
 	create(options) {
 		const layer = {
 			apply: (builder) => {
@@ -902,9 +890,6 @@ const Layer = {
 			provide(dep) {
 				return createProvidedLayer(dep, layer);
 			},
-			provideMerge(dep) {
-				return createComposedLayer(dep, layer);
-			},
 			merge(other) {
 				return createMergedLayer(layer, other);
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sandly",
-	"version": "2.0.1",
+	"version": "3.0.0",
 	"keywords": [
 		"typescript",
 		"sandly",
@@ -49,6 +49,7 @@
 		"lint:check": "eslint . --max-warnings=0",
 		"type:check": "tsc --noEmit",
 		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
 		"tag": "git tag v$(node -p \"require('./package.json').version\") && git push --tags",
 		"release": "changeset version && changeset publish"
 	},
@@ -56,6 +57,7 @@
 		"@changesets/cli": "^2.29.5",
 		"@eslint/js": "^9.26.0",
 		"@types/node": "^22.15.3",
+		"@vitest/coverage-v8": "^3.2.4",
 		"eslint": "^9.26.0",
 		"prettier": "^3.5.3",
 		"prettier-plugin-organize-imports": "^4.1.0",