sandly 2.1.0 → 3.0.1

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
@@ -483,11 +500,10 @@ try {
 | `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                                |
-| `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                        |
+| `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
 

package/dist/index.d.ts

@@ -165,9 +165,16 @@ type WithBuilderTags<TBuilder, TNewTags extends AnyTag> = TBuilder extends Scope
  * - A ServiceTag (class) whose instances are assignable to T
  * - A ValueTag whose value type is assignable to T
  * - A raw value of type T
+ *
+ * The conditional uses `[T] extends [object]` (tuple-wrapped) to prevent
+ * distribution over union types. Without this, a parameter typed as a
+ * string union (e.g. `'SANDBOX' | 'PRODUCTION'`) would distribute into
+ * `ValueTag<any, 'SANDBOX'> | ValueTag<any, 'PRODUCTION'>`, and a
+ * `ValueTag<any, 'SANDBOX' | 'PRODUCTION'>` would not be assignable to
+ * either branch (ValueTag is invariant in its value parameter).
  * @internal
  */
-type ValidDepFor<T> = (T extends object ? ServiceTag<T> | ValueTag<any, T> : ValueTag<any, T>) | T;
+type ValidDepFor<T> = ([T] extends [object] ? ServiceTag<T> | ValueTag<any, T> : ValueTag<any, T>) | T;
 /**
  * Maps constructor parameters to valid dependency types.
  * Each parameter type T becomes ValidDepFor<T>.
@@ -239,6 +246,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 +256,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.
@@ -443,8 +451,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
@@ -455,12 +466,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);
+	return createMergedLayer(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);
-		}
-	};
-}
-/**
-* 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.
@@ -907,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.1.0",
+	"version": "3.0.1",
 	"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",