katagami 2.3.0 → 3.0.0

package/dist/index.cjs

@@ -29,12 +29,65 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
+  createScope: () => createScope,
   createContainer: () => createContainer,
+  Scope: () => Scope,
   ContainerError: () => ContainerError,
   Container: () => Container
 });
 module.exports = __toCommonJS(exports_src);
 
+// src/internal.ts
+var INTERNALS = Symbol("katagami.internals");
+
+// src/container/index.ts
+function createContainer() {
+  return new Container;
+}
+
+class Container {
+  registrations;
+  singletonCache;
+  disposed = false;
+  [INTERNALS];
+  constructor() {
+    this.registrations = new Map;
+    this.singletonCache = new Map;
+    this[INTERNALS] = {
+      isDisposed: () => this.disposed,
+      markDisposed: () => {
+        this.disposed = true;
+      },
+      ownCache: this.singletonCache,
+      registrations: this.registrations,
+      singletonCache: this.singletonCache
+    };
+  }
+  registerSingleton(token, factory) {
+    return this.addRegistration(token, factory, "singleton");
+  }
+  registerTransient(token, factory) {
+    return this.addRegistration(token, factory, "transient");
+  }
+  registerScoped(token, factory) {
+    return this.addRegistration(token, factory, "scoped");
+  }
+  use(source) {
+    for (const [token, registrations] of source[INTERNALS].registrations) {
+      this.registrations.set(token, [...registrations]);
+    }
+    return this;
+  }
+  addRegistration(token, factory, lifetime) {
+    const existing = this.registrations.get(token);
+    if (existing !== undefined) {
+      existing.push({ factory, lifetime });
+    } else {
+      this.registrations.set(token, [{ factory, lifetime }]);
+    }
+    return this;
+  }
+}
 // src/error/index.ts
 class ContainerError extends Error {
   constructor(message) {
@@ -42,10 +95,6 @@ class ContainerError extends Error {
     this.name = "ContainerError";
   }
 }
-
-// src/internal.ts
-var INTERNALS = Symbol("katagami.internals");
-
 // src/resolver/index.ts
 function tokenToString(token) {
   if (typeof token === "function") {
@@ -71,46 +120,38 @@ function buildCircularPath(resolvingTokens, token) {
   return path.join(" -> ");
 }
 
-// src/container/index.ts
-function createContainer() {
-  return new Container;
+// src/scope/index.ts
+function createScope(source) {
+  const internals = source[INTERNALS];
+  if (internals.isDisposed()) {
+    throw new ContainerError("Cannot create a scope from a disposed container.");
+  }
+  return new Scope(internals.registrations, internals.singletonCache);
 }
 
-class Container {
+class Scope {
   registrations;
   singletonCache;
+  scopedCache;
   resolvingTokens;
+  singletonDepth = 0;
   disposed = false;
   [INTERNALS];
-  constructor() {
-    this.registrations = new Map;
-    this.singletonCache = new Map;
+  constructor(registrations, singletonCache) {
+    this.registrations = registrations;
+    this.singletonCache = singletonCache;
+    this.scopedCache = new Map;
     this.resolvingTokens = new Set;
     this[INTERNALS] = {
       isDisposed: () => this.disposed,
       markDisposed: () => {
         this.disposed = true;
       },
-      ownCache: this.singletonCache,
+      ownCache: this.scopedCache,
       registrations: this.registrations,
       singletonCache: this.singletonCache
     };
   }
-  registerSingleton(token, factory) {
-    return this.addRegistration(token, factory, "singleton");
-  }
-  registerTransient(token, factory) {
-    return this.addRegistration(token, factory, "transient");
-  }
-  registerScoped(token, factory) {
-    return this.addRegistration(token, factory, "scoped");
-  }
-  use(source) {
-    for (const [token, registrations] of source[INTERNALS].registrations) {
-      this.registrations.set(token, [...registrations]);
-    }
-    return this;
-  }
   resolve(token) {
     return this.resolveToken(token, true);
   }
@@ -125,7 +166,7 @@ class Container {
   }
   resolveToken(token, required) {
     if (this.disposed) {
-      throw new ContainerError("Cannot resolve from a disposed container.");
+      throw new ContainerError("Cannot resolve from a disposed scope.");
     }
     const registrations = this.registrations.get(token);
     if (registrations === undefined || registrations.length === 0) {
@@ -135,30 +176,42 @@ class Container {
       return;
     }
     const registration = registrations[registrations.length - 1];
-    const cached = this.singletonCache.get(registration);
-    if (cached !== undefined) {
-      return cached;
+    const singletonCached = this.singletonCache.get(registration);
+    if (singletonCached !== undefined) {
+      return singletonCached;
+    }
+    if (registration.lifetime === "scoped" && this.singletonDepth > 0) {
+      throw new ContainerError(`Captive dependency detected: scoped token "${tokenToString(token)}" cannot be resolved inside a singleton factory. Scoped instances must not be captured by singletons.`);
     }
-    if (registration.lifetime === "scoped") {
-      throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+    const scopedCached = this.scopedCache.get(registration);
+    if (scopedCached !== undefined) {
+      return scopedCached;
     }
     if (this.resolvingTokens.has(token)) {
       throw new ContainerError(`Circular dependency detected: ${buildCircularPath(this.resolvingTokens, token)}`);
     }
     this.resolvingTokens.add(token);
+    if (registration.lifetime === "singleton") {
+      this.singletonDepth++;
+    }
     try {
       const instance = registration.factory(this);
       if (registration.lifetime === "singleton") {
         this.singletonCache.set(registration, instance);
+      } else if (registration.lifetime === "scoped") {
+        this.scopedCache.set(registration, instance);
       }
       return instance;
     } finally {
+      if (registration.lifetime === "singleton") {
+        this.singletonDepth--;
+      }
       this.resolvingTokens.delete(token);
     }
   }
   resolveAllTokens(token, required) {
     if (this.disposed) {
-      throw new ContainerError("Cannot resolve from a disposed container.");
+      throw new ContainerError("Cannot resolve from a disposed scope.");
     }
     const registrations = this.registrations.get(token);
     if (registrations === undefined || registrations.length === 0) {
@@ -174,30 +227,36 @@ class Container {
     try {
       return registrations.map((registration) => {
         const reg = registration;
-        const cached = this.singletonCache.get(registration);
-        if (cached !== undefined) {
-          return cached;
+        const singletonCached = this.singletonCache.get(registration);
+        if (singletonCached !== undefined) {
+          return singletonCached;
         }
-        if (reg.lifetime === "scoped") {
-          throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+        if (reg.lifetime === "scoped" && this.singletonDepth > 0) {
+          throw new ContainerError(`Captive dependency detected: scoped token "${tokenToString(token)}" cannot be resolved inside a singleton factory. Scoped instances must not be captured by singletons.`);
+        }
+        const scopedCached = this.scopedCache.get(registration);
+        if (scopedCached !== undefined) {
+          return scopedCached;
         }
-        const instance = reg.factory(this);
         if (reg.lifetime === "singleton") {
-          this.singletonCache.set(registration, instance);
+          this.singletonDepth++;
+        }
+        try {
+          const instance = reg.factory(this);
+          if (reg.lifetime === "singleton") {
+            this.singletonCache.set(registration, instance);
+          } else if (reg.lifetime === "scoped") {
+            this.scopedCache.set(registration, instance);
+          }
+          return instance;
+        } finally {
+          if (reg.lifetime === "singleton") {
+            this.singletonDepth--;
+          }
         }
-        return instance;
       });
     } finally {
       this.resolvingTokens.delete(token);
     }
   }
-  addRegistration(token, factory, lifetime) {
-    const existing = this.registrations.get(token);
-    if (existing !== undefined) {
-      existing.push({ factory, lifetime });
-    } else {
-      this.registrations.set(token, [{ factory, lifetime }]);
-    }
-    return this;
-  }
 }

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export type { DisposableContainer, DisposableScope, disposable } from './disposa
 export { ContainerError } from './error';
 export type { lazy } from './lazy';
 export type { Resolver } from './resolver';
-export type { createScope, Scope } from './scope';
+export { createScope, Scope } from './scope';

package/dist/index.js

@@ -1,8 +1,3 @@
-import {
-  ContainerError,
-  buildCircularPath,
-  tokenToString
-} from "./index-g50fxds1.js";
 import {
   INTERNALS
 } from "./index-jx8b52m0.js";
@@ -15,13 +10,11 @@ function createContainer() {
 class Container {
   registrations;
   singletonCache;
-  resolvingTokens;
   disposed = false;
   [INTERNALS];
   constructor() {
     this.registrations = new Map;
     this.singletonCache = new Map;
-    this.resolvingTokens = new Set;
     this[INTERNALS] = {
       isDisposed: () => this.disposed,
       markDisposed: () => {
@@ -47,6 +40,80 @@ class Container {
     }
     return this;
   }
+  addRegistration(token, factory, lifetime) {
+    const existing = this.registrations.get(token);
+    if (existing !== undefined) {
+      existing.push({ factory, lifetime });
+    } else {
+      this.registrations.set(token, [{ factory, lifetime }]);
+    }
+    return this;
+  }
+}
+// src/error/index.ts
+class ContainerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContainerError";
+  }
+}
+// src/resolver/index.ts
+function tokenToString(token) {
+  if (typeof token === "function") {
+    return token.name || "anonymous function";
+  }
+  if (typeof token === "symbol") {
+    return token.toString();
+  }
+  return String(token);
+}
+function buildCircularPath(resolvingTokens, token) {
+  const path = [];
+  let found = false;
+  for (const t of resolvingTokens) {
+    if (t === token) {
+      found = true;
+    }
+    if (found) {
+      path.push(tokenToString(t));
+    }
+  }
+  path.push(tokenToString(token));
+  return path.join(" -> ");
+}
+
+// src/scope/index.ts
+function createScope(source) {
+  const internals = source[INTERNALS];
+  if (internals.isDisposed()) {
+    throw new ContainerError("Cannot create a scope from a disposed container.");
+  }
+  return new Scope(internals.registrations, internals.singletonCache);
+}
+
+class Scope {
+  registrations;
+  singletonCache;
+  scopedCache;
+  resolvingTokens;
+  singletonDepth = 0;
+  disposed = false;
+  [INTERNALS];
+  constructor(registrations, singletonCache) {
+    this.registrations = registrations;
+    this.singletonCache = singletonCache;
+    this.scopedCache = new Map;
+    this.resolvingTokens = new Set;
+    this[INTERNALS] = {
+      isDisposed: () => this.disposed,
+      markDisposed: () => {
+        this.disposed = true;
+      },
+      ownCache: this.scopedCache,
+      registrations: this.registrations,
+      singletonCache: this.singletonCache
+    };
+  }
   resolve(token) {
     return this.resolveToken(token, true);
   }
@@ -61,7 +128,7 @@ class Container {
   }
   resolveToken(token, required) {
     if (this.disposed) {
-      throw new ContainerError("Cannot resolve from a disposed container.");
+      throw new ContainerError("Cannot resolve from a disposed scope.");
     }
     const registrations = this.registrations.get(token);
     if (registrations === undefined || registrations.length === 0) {
@@ -71,30 +138,42 @@ class Container {
       return;
     }
     const registration = registrations[registrations.length - 1];
-    const cached = this.singletonCache.get(registration);
-    if (cached !== undefined) {
-      return cached;
+    const singletonCached = this.singletonCache.get(registration);
+    if (singletonCached !== undefined) {
+      return singletonCached;
+    }
+    if (registration.lifetime === "scoped" && this.singletonDepth > 0) {
+      throw new ContainerError(`Captive dependency detected: scoped token "${tokenToString(token)}" cannot be resolved inside a singleton factory. Scoped instances must not be captured by singletons.`);
     }
-    if (registration.lifetime === "scoped") {
-      throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+    const scopedCached = this.scopedCache.get(registration);
+    if (scopedCached !== undefined) {
+      return scopedCached;
     }
     if (this.resolvingTokens.has(token)) {
       throw new ContainerError(`Circular dependency detected: ${buildCircularPath(this.resolvingTokens, token)}`);
     }
     this.resolvingTokens.add(token);
+    if (registration.lifetime === "singleton") {
+      this.singletonDepth++;
+    }
     try {
       const instance = registration.factory(this);
       if (registration.lifetime === "singleton") {
         this.singletonCache.set(registration, instance);
+      } else if (registration.lifetime === "scoped") {
+        this.scopedCache.set(registration, instance);
       }
       return instance;
     } finally {
+      if (registration.lifetime === "singleton") {
+        this.singletonDepth--;
+      }
       this.resolvingTokens.delete(token);
     }
   }
   resolveAllTokens(token, required) {
     if (this.disposed) {
-      throw new ContainerError("Cannot resolve from a disposed container.");
+      throw new ContainerError("Cannot resolve from a disposed scope.");
     }
     const registrations = this.registrations.get(token);
     if (registrations === undefined || registrations.length === 0) {
@@ -110,35 +189,43 @@ class Container {
     try {
       return registrations.map((registration) => {
         const reg = registration;
-        const cached = this.singletonCache.get(registration);
-        if (cached !== undefined) {
-          return cached;
+        const singletonCached = this.singletonCache.get(registration);
+        if (singletonCached !== undefined) {
+          return singletonCached;
+        }
+        if (reg.lifetime === "scoped" && this.singletonDepth > 0) {
+          throw new ContainerError(`Captive dependency detected: scoped token "${tokenToString(token)}" cannot be resolved inside a singleton factory. Scoped instances must not be captured by singletons.`);
         }
-        if (reg.lifetime === "scoped") {
-          throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+        const scopedCached = this.scopedCache.get(registration);
+        if (scopedCached !== undefined) {
+          return scopedCached;
         }
-        const instance = reg.factory(this);
         if (reg.lifetime === "singleton") {
-          this.singletonCache.set(registration, instance);
+          this.singletonDepth++;
+        }
+        try {
+          const instance = reg.factory(this);
+          if (reg.lifetime === "singleton") {
+            this.singletonCache.set(registration, instance);
+          } else if (reg.lifetime === "scoped") {
+            this.scopedCache.set(registration, instance);
+          }
+          return instance;
+        } finally {
+          if (reg.lifetime === "singleton") {
+            this.singletonDepth--;
+          }
         }
-        return instance;
       });
     } finally {
       this.resolvingTokens.delete(token);
     }
   }
-  addRegistration(token, factory, lifetime) {
-    const existing = this.registrations.get(token);
-    if (existing !== undefined) {
-      existing.push({ factory, lifetime });
-    } else {
-      this.registrations.set(token, [{ factory, lifetime }]);
-    }
-    return this;
-  }
 }
 export {
+  createScope,
   createContainer,
+  Scope,
   ContainerError,
   Container
 };

package/dist/lazy/index.d.ts

@@ -1,5 +1,4 @@
-import type { Container } from '../container';
-import type { DisposableContainer, DisposableScope } from '../disposable';
+import type { DisposableScope } from '../disposable';
 import type { AbstractConstructor } from '../resolver';
 import type { Scope } from '../scope';
 /**
@@ -12,24 +11,23 @@ import type { Scope } from '../scope';
  * Only **sync class tokens** are supported. Async tokens and PropertyKey tokens
  * are rejected at the type level.
  *
- * @param source A Container, Scope, DisposableContainer, or DisposableScope
+ * @param source A Scope or DisposableScope
  * @param token  A sync class constructor token
  * @returns A proxy that transparently forwards to the lazily-resolved instance
  *
  * @example
  * ```ts
- * import { createContainer } from 'katagami';
+ * import { createContainer, createScope } from 'katagami';
  * import { lazy } from 'katagami/lazy';
  *
  * const container = createContainer()
  *   .registerSingleton(HeavyService, () => new HeavyService());
  *
- * const service = lazy(container, HeavyService);
+ * const scope = createScope(container);
+ * const service = lazy(scope, HeavyService);
  * // Instance is NOT created yet
  * service.doSomething(); // resolved here, then cached
  * ```
  */
-export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
 export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;
-export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
 export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "katagami",
-	"version": "2.3.0",
+	"version": "3.0.0",
 	"description": "Lightweight DI container for TypeScript and JavaScript — full type inference, no decorators, no reflect-metadata, hybrid class & PropertyKey tokens.",
 	"license": "MIT",
 	"type": "module",
@@ -11,11 +11,6 @@
 			"import": "./dist/index.js",
 			"require": "./dist/index.cjs"
 		},
-		"./scope": {
-			"types": "./dist/scope/index.d.ts",
-			"import": "./dist/scope/index.js",
-			"require": "./dist/scope/index.cjs"
-		},
 		"./disposable": {
 			"types": "./dist/disposable/index.d.ts",
 			"import": "./dist/disposable/index.js",
@@ -50,8 +45,8 @@
 		"clean": "rm -rf dist",
 		"build": "bun run clean && bun run build:types && bun run build:esm && bun run build:cjs",
 		"build:types": "tsc -p tsconfig.build.json",
-		"build:esm": "bun build ./src/index.ts ./src/scope/index.ts ./src/disposable/index.ts ./src/lazy/index.ts --outdir dist --format esm --splitting",
-		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs && bun build ./src/scope/index.ts --outfile dist/scope/index.cjs --format cjs && bun build ./src/disposable/index.ts --outfile dist/disposable/index.cjs --format cjs && bun build ./src/lazy/index.ts --outfile dist/lazy/index.cjs --format cjs",
+		"build:esm": "bun build ./src/index.ts ./src/disposable/index.ts ./src/lazy/index.ts --outdir dist --format esm --splitting",
+		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs && bun build ./src/disposable/index.ts --outfile dist/disposable/index.cjs --format cjs && bun build ./src/lazy/index.ts --outfile dist/lazy/index.cjs --format cjs",
 		"prepublishOnly": "bun run build",
 		"check": "bun run format",
 		"lint": "biome lint .",

package/dist/index-g50fxds1.js

@@ -1,34 +0,0 @@
-// src/error/index.ts
-class ContainerError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ContainerError";
-  }
-}
-
-// src/resolver/index.ts
-function tokenToString(token) {
-  if (typeof token === "function") {
-    return token.name || "anonymous function";
-  }
-  if (typeof token === "symbol") {
-    return token.toString();
-  }
-  return String(token);
-}
-function buildCircularPath(resolvingTokens, token) {
-  const path = [];
-  let found = false;
-  for (const t of resolvingTokens) {
-    if (t === token) {
-      found = true;
-    }
-    if (found) {
-      path.push(tokenToString(t));
-    }
-  }
-  path.push(tokenToString(token));
-  return path.join(" -> ");
-}
-
-export { ContainerError, tokenToString, buildCircularPath };