@djodjonx/neo-syringe 1.1.5 → 1.2.0

package/.github/workflows/ci.yml

@@ -69,11 +69,12 @@ jobs:
 
       - name: Verify build output
         run: |
-          test -f dist/index.js
-          test -f dist/index.d.ts
-          test -f dist/unplugin/index.js
-          test -f dist/lsp/index.js
-          test -f dist/cli/index.js
+          test -f dist/index.mjs
+          test -f dist/index.cjs
+          test -f dist/index.d.mts
+          test -f dist/unplugin/index.mjs
+          test -f dist/lsp/index.mjs
+          test -f dist/cli/index.mjs
 
   security:
     runs-on: ubuntu-latest

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.2.0](https://github.com/djodjonx/neo-syringe/compare/v1.1.5...v1.2.0) (2026-01-18)
+
+
+### Features
+
+* rename 'scope' to 'lifecycle' to avoid confusion with 'scoped' ([b246121](https://github.com/djodjonx/neo-syringe/commit/b246121a5f71cbf26ce80ffba6ec6ea5b09017f8))
+* **scoped:** add scoped injection support for parent container overrides ([170204c](https://github.com/djodjonx/neo-syringe/commit/170204c48f2c65dc7158adc11931fad4d2a91d6b))
+
+
+### Bug Fixes
+
+* correct build output paths for ESM/CJS ([8ff7b74](https://github.com/djodjonx/neo-syringe/commit/8ff7b7476b3333540cb840cd21051ce935de88ac))
+
 ### [1.1.5](https://github.com/djodjonx/neo-syringe/compare/v1.1.4...v1.1.5) (2026-01-18)
 
 ### [1.1.4](https://github.com/djodjonx/neo-syringe/compare/v1.1.3...v1.1.4) (2026-01-18)

package/README.md

@@ -4,6 +4,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@djodjonx/neo-syringe"><img src="https://img.shields.io/npm/v/@djodjonx/neo-syringe.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://github.com/djodjonx/neo-syringe/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/djodjonx/neo-syringe/ci.yml?style=flat-square&label=tests" alt="Tests"></a>
   <a href="https://github.com/djodjonx/neo-syringe/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/djodjonx/neo-syringe/ci.yml?style=flat-square" alt="CI"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0+-blue.svg?style=flat-square" alt="TypeScript"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
@@ -71,20 +72,18 @@ const config = defineBuilderConfig({
 ```bash
 # With npm
 npm install @djodjonx/neo-syringe
+npm install -D unplugin
 
 # With pnpm
 pnpm add @djodjonx/neo-syringe
+pnpm add -D unplugin
 ```
 
-> **Note**: `typescript` (>=5.0.0) is a required peer dependency.
-
-### Build System Integration (Recommended)
+> **Note**: `typescript` (>=5.0.0) and `unplugin` are required peer dependencies.
 
-For compile-time code generation, install `unplugin`:
+### Build System Integration
 
-```bash
-pnpm add -D unplugin
-```
+Configure the plugin in your bundler to enable compile-time code generation.
 
 <details>
 <summary><strong>Vite</strong></summary>
@@ -286,19 +285,61 @@ export const config = defineBuilderConfig({
 - ✅ LSP validation: Detects if parameter doesn't exist
 - ✅ Refactoring-friendly: Rename parameter → LSP error
 
-### Scopes
+### Lifecycle
 
 ```typescript
-{ token: UserService, scope: 'transient' } // Default is 'singleton'
+{ token: UserService, lifecycle: 'transient' } // Default is 'singleton'
 
-// Factories support scopes too
-{ 
-  token: useInterface<IRequest>(), 
+// Factories support lifecycle too
+{
+  token: useInterface<IRequest>(),
   provider: () => ({ id: crypto.randomUUID() }),
-  scope: 'transient'
+  lifecycle: 'transient'
 }
 ```
 
+### Scoped Injections (`scoped: true`)
+
+Override a token from a parent container **without causing a duplicate error**. Useful for testing or module-specific overrides.
+
+```typescript
+// SharedKernel - Production logger
+const sharedKernel = defineBuilderConfig({
+  name: 'SharedKernel',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger, lifecycle: 'singleton' }
+  ]
+});
+
+// TestModule - Override with MockLogger, scoped to this container
+const testModule = defineBuilderConfig({
+  name: 'TestModule',
+  useContainer: sharedKernel,
+  injections: [
+    { 
+      token: useInterface<ILogger>(), 
+      provider: MockLogger,
+      lifecycle: 'transient',  // Can use different lifecycle than parent
+      scoped: true         // 👈 Allows override without duplicate error
+    },
+    { token: UserService }  // Uses MockLogger from this container
+  ]
+});
+```
+
+**Behavior:**
+
+| Scenario | Without `scoped` | With `scoped: true` |
+|----------|------------------|---------------------|
+| Token exists in parent | ❌ Duplicate error | ✅ Override locally |
+| Token does not exist in parent | ✅ OK | ✅ OK |
+| Resolution | Delegates to parent | Uses local instance |
+
+**Use Cases:**
+- 🧪 **Testing**: Override production services with mocks
+- 🔧 **Module isolation**: Each module has its own instance
+- ⚙️ **Different lifecycle**: Parent uses singleton, child uses transient
+
 ---
 
 ## Generated Code Example

package/dist/{GraphValidator-G0F4QiLk.cjs → GraphValidator-CV4VoJl0.cjs}

@@ -204,16 +204,19 @@ var Analyzer = class {
 	parseInjectionObject(obj, graph) {
 		let tokenNode;
 		let providerNode;
-		let scope = "singleton";
+		let lifecycle = "singleton";
 		let useFactory = false;
+		let isScoped = false;
 		for (const prop of obj.properties) {
 			if (!typescript.isPropertyAssignment(prop) || !typescript.isIdentifier(prop.name)) continue;
 			if (prop.name.text === "token") tokenNode = prop.initializer;
 			else if (prop.name.text === "provider") providerNode = prop.initializer;
-			else if (prop.name.text === "scope" && typescript.isStringLiteral(prop.initializer)) {
-				if (prop.initializer.text === "transient") scope = "transient";
+			else if (prop.name.text === "lifecycle" && typescript.isStringLiteral(prop.initializer)) {
+				if (prop.initializer.text === "transient") lifecycle = "transient";
 			} else if (prop.name.text === "useFactory") {
 				if (prop.initializer.kind === typescript.SyntaxKind.TrueKeyword) useFactory = true;
+			} else if (prop.name.text === "scoped") {
+				if (prop.initializer.kind === typescript.SyntaxKind.TrueKeyword) isScoped = true;
 			}
 		}
 		if (!tokenNode) return;
@@ -250,17 +253,18 @@ var Analyzer = class {
 			factorySource = providerNode.getText();
 			type = "factory";
 			if (tokenId) {
-				if (graph.nodes.has(tokenId)) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+				if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
 				const definition = {
 					tokenId,
 					tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
 					registrationNode: obj,
 					type: "factory",
-					scope,
+					lifecycle,
 					isInterfaceToken,
 					isValueToken,
 					isFactory: true,
-					factorySource
+					factorySource,
+					isScoped
 				};
 				graph.nodes.set(tokenId, {
 					service: definition,
@@ -282,15 +286,16 @@ var Analyzer = class {
 			type = "autowire";
 		}
 		if (tokenId && implementationSymbol) {
-			if (graph.nodes.has(tokenId)) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+			if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
 			const definition = {
 				tokenId,
 				implementationSymbol: this.resolveSymbol(implementationSymbol),
 				tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
 				registrationNode: obj,
 				type,
-				scope,
-				isInterfaceToken: isInterfaceToken || typescript.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode)
+				lifecycle,
+				isInterfaceToken: isInterfaceToken || typescript.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode),
+				isScoped
 			};
 			graph.nodes.set(tokenId, {
 				service: definition,
@@ -433,7 +438,10 @@ var GraphValidator = class {
 		const visited = /* @__PURE__ */ new Set();
 		const recursionStack = /* @__PURE__ */ new Set();
 		const parentTokens = graph.parentProvidedTokens ?? /* @__PURE__ */ new Set();
-		for (const nodeId of graph.nodes.keys()) if (parentTokens.has(nodeId)) throw new Error(`Duplicate registration: '${nodeId}' is already registered in the parent container. Remove the local registration or use a different token.`);
+		for (const [nodeId, node] of graph.nodes) if (parentTokens.has(nodeId)) {
+			if (node.service.isScoped) continue;
+			throw new Error(`Duplicate registration: '${nodeId}' is already registered in the parent container. Use 'scoped: true' to override the parent's registration intentionally.`);
+		}
 		for (const [nodeId, node] of graph.nodes) for (const depId of node.dependencies) {
 			const isProvidedLocally = graph.nodes.has(depId);
 			const isProvidedByParent = parentTokens.has(depId);

package/dist/{GraphValidator-C8ldJtNp.mjs → GraphValidator-DXqqkNdS.mjs}

@@ -176,16 +176,19 @@ var Analyzer = class {
 	parseInjectionObject(obj, graph) {
 		let tokenNode;
 		let providerNode;
-		let scope = "singleton";
+		let lifecycle = "singleton";
 		let useFactory = false;
+		let isScoped = false;
 		for (const prop of obj.properties) {
 			if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
 			if (prop.name.text === "token") tokenNode = prop.initializer;
 			else if (prop.name.text === "provider") providerNode = prop.initializer;
-			else if (prop.name.text === "scope" && ts.isStringLiteral(prop.initializer)) {
-				if (prop.initializer.text === "transient") scope = "transient";
+			else if (prop.name.text === "lifecycle" && ts.isStringLiteral(prop.initializer)) {
+				if (prop.initializer.text === "transient") lifecycle = "transient";
 			} else if (prop.name.text === "useFactory") {
 				if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) useFactory = true;
+			} else if (prop.name.text === "scoped") {
+				if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) isScoped = true;
 			}
 		}
 		if (!tokenNode) return;
@@ -222,17 +225,18 @@ var Analyzer = class {
 			factorySource = providerNode.getText();
 			type = "factory";
 			if (tokenId) {
-				if (graph.nodes.has(tokenId)) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+				if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
 				const definition = {
 					tokenId,
 					tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
 					registrationNode: obj,
 					type: "factory",
-					scope,
+					lifecycle,
 					isInterfaceToken,
 					isValueToken,
 					isFactory: true,
-					factorySource
+					factorySource,
+					isScoped
 				};
 				graph.nodes.set(tokenId, {
 					service: definition,
@@ -254,15 +258,16 @@ var Analyzer = class {
 			type = "autowire";
 		}
 		if (tokenId && implementationSymbol) {
-			if (graph.nodes.has(tokenId)) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+			if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
 			const definition = {
 				tokenId,
 				implementationSymbol: this.resolveSymbol(implementationSymbol),
 				tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
 				registrationNode: obj,
 				type,
-				scope,
-				isInterfaceToken: isInterfaceToken || ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode)
+				lifecycle,
+				isInterfaceToken: isInterfaceToken || ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode),
+				isScoped
 			};
 			graph.nodes.set(tokenId, {
 				service: definition,
@@ -405,7 +410,10 @@ var GraphValidator = class {
 		const visited = /* @__PURE__ */ new Set();
 		const recursionStack = /* @__PURE__ */ new Set();
 		const parentTokens = graph.parentProvidedTokens ?? /* @__PURE__ */ new Set();
-		for (const nodeId of graph.nodes.keys()) if (parentTokens.has(nodeId)) throw new Error(`Duplicate registration: '${nodeId}' is already registered in the parent container. Remove the local registration or use a different token.`);
+		for (const [nodeId, node] of graph.nodes) if (parentTokens.has(nodeId)) {
+			if (node.service.isScoped) continue;
+			throw new Error(`Duplicate registration: '${nodeId}' is already registered in the parent container. Use 'scoped: true' to override the parent's registration intentionally.`);
+		}
 		for (const [nodeId, node] of graph.nodes) for (const depId of node.dependencies) {
 			const isProvidedLocally = graph.nodes.has(depId);
 			const isProvidedByParent = parentTokens.has(depId);

package/dist/cli/index.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_GraphValidator = require('../GraphValidator-G0F4QiLk.cjs');
+const require_GraphValidator = require('../GraphValidator-CV4VoJl0.cjs');
 let typescript = require("typescript");
 typescript = require_GraphValidator.__toESM(typescript);
 

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as Analyzer, t as GraphValidator } from "../GraphValidator-C8ldJtNp.mjs";
+import { n as Analyzer, t as GraphValidator } from "../GraphValidator-DXqqkNdS.mjs";
 import * as ts from "typescript";
 
 //#region src/cli/index.ts

package/dist/index.d.cts

@@ -5,11 +5,11 @@
  */
 type Constructor<T = unknown> = new (...args: unknown[]) => T;
 /**
- * Defines the lifecycle scope of a service.
+ * Defines the lifecycle of a service.
  * - `singleton`: One instance per container.
  * - `transient`: A new instance every time it is resolved.
  */
-type Scope = 'singleton' | 'transient';
+type Lifecycle = 'singleton' | 'transient';
 /**
  * The dependency injection container interface.
  * Provides access to the registered services.
@@ -74,7 +74,33 @@ interface Injection<T = any> {
        * Required when provider is a function, not a class.
        */
   useFactory?: boolean;
-  scope?: Scope;
+  /**
+       * Lifecycle of the service.
+       * - `singleton`: One instance per container (default).
+       * - `transient`: A new instance every time it is resolved.
+       */
+  lifecycle?: Lifecycle;
+  /**
+       * If true, this injection is scoped to this container only.
+       * Allows overriding a token from a parent container without causing a duplicate error.
+       * The local instance will be used instead of delegating to the parent.
+       *
+       * @example
+       * ```typescript
+       * const parent = defineBuilderConfig({
+       *   injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+       * });
+       *
+       * const child = defineBuilderConfig({
+       *   useContainer: parent,
+       *   injections: [
+       *     // Override parent's ILogger with a local FileLogger
+       *     { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+       *   ]
+       * });
+       * ```
+       */
+  scoped?: boolean;
 }
 /**
  * Partial configuration that can be shared/extended.
@@ -139,4 +165,4 @@ declare function useProperty<T, C extends Constructor<any>>(targetClass: C, para
  */
 declare function declareContainerTokens<T extends Record<string, any>>(container: any): T & { [K in keyof T]: T[K] };
 //#endregion
-export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, PartialConfig, PropertyToken, Provider, Scope, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/index.d.mts

@@ -5,11 +5,11 @@
  */
 type Constructor<T = unknown> = new (...args: unknown[]) => T;
 /**
- * Defines the lifecycle scope of a service.
+ * Defines the lifecycle of a service.
  * - `singleton`: One instance per container.
  * - `transient`: A new instance every time it is resolved.
  */
-type Scope = 'singleton' | 'transient';
+type Lifecycle = 'singleton' | 'transient';
 /**
  * The dependency injection container interface.
  * Provides access to the registered services.
@@ -74,7 +74,33 @@ interface Injection<T = any> {
        * Required when provider is a function, not a class.
        */
   useFactory?: boolean;
-  scope?: Scope;
+  /**
+       * Lifecycle of the service.
+       * - `singleton`: One instance per container (default).
+       * - `transient`: A new instance every time it is resolved.
+       */
+  lifecycle?: Lifecycle;
+  /**
+       * If true, this injection is scoped to this container only.
+       * Allows overriding a token from a parent container without causing a duplicate error.
+       * The local instance will be used instead of delegating to the parent.
+       *
+       * @example
+       * ```typescript
+       * const parent = defineBuilderConfig({
+       *   injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+       * });
+       *
+       * const child = defineBuilderConfig({
+       *   useContainer: parent,
+       *   injections: [
+       *     // Override parent's ILogger with a local FileLogger
+       *     { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+       *   ]
+       * });
+       * ```
+       */
+  scoped?: boolean;
 }
 /**
  * Partial configuration that can be shared/extended.
@@ -139,4 +165,4 @@ declare function useProperty<T, C extends Constructor<any>>(targetClass: C, para
  */
 declare function declareContainerTokens<T extends Record<string, any>>(container: any): T & { [K in keyof T]: T[K] };
 //#endregion
-export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, PartialConfig, PropertyToken, Provider, Scope, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/lsp/index.cjs

@@ -1,4 +1,4 @@
-const require_GraphValidator = require('../GraphValidator-G0F4QiLk.cjs');
+const require_GraphValidator = require('../GraphValidator-CV4VoJl0.cjs');
 
 //#region src/lsp/index.ts
 /**

package/dist/lsp/index.mjs

@@ -1,4 +1,4 @@
-import { n as Analyzer, t as GraphValidator } from "../GraphValidator-C8ldJtNp.mjs";
+import { n as Analyzer, t as GraphValidator } from "../GraphValidator-DXqqkNdS.mjs";
 
 //#region src/lsp/index.ts
 /**

package/dist/unplugin/index.cjs

@@ -1,4 +1,4 @@
-const require_GraphValidator = require('../GraphValidator-G0F4QiLk.cjs');
+const require_GraphValidator = require('../GraphValidator-CV4VoJl0.cjs');
 let unplugin = require("unplugin");
 let typescript = require("typescript");
 typescript = require_GraphValidator.__toESM(typescript);
@@ -53,7 +53,7 @@ function ${factoryId}(container: NeoContainer) {
   return new ${className}(${args});
 }`);
 			}
-			const isTransient = node.service.scope === "transient";
+			const isTransient = node.service.lifecycle === "transient";
 			let tokenKey;
 			let tokenCheck;
 			if (node.service.isInterfaceToken) {

package/dist/unplugin/index.mjs

@@ -1,4 +1,4 @@
-import { n as Analyzer, t as GraphValidator } from "../GraphValidator-C8ldJtNp.mjs";
+import { n as Analyzer, t as GraphValidator } from "../GraphValidator-DXqqkNdS.mjs";
 import { createUnplugin } from "unplugin";
 import * as ts from "typescript";
 
@@ -52,7 +52,7 @@ function ${factoryId}(container: NeoContainer) {
   return new ${className}(${args});
 }`);
 			}
-			const isTransient = node.service.scope === "transient";
+			const isTransient = node.service.lifecycle === "transient";
 			let tokenKey;
 			let tokenCheck;
 			if (node.service.isInterfaceToken) {

package/package.json

@@ -1,29 +1,30 @@
 {
   "name": "@djodjonx/neo-syringe",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Zero-Overhead, Compile-Time Dependency Injection for TypeScript",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/index.cjs",
   "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "types": "dist/index.d.mts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "require": "./dist/index.cjs"
     },
     "./plugin": {
-      "types": "./dist/unplugin/index.d.ts",
+      "types": "./dist/unplugin/index.d.mts",
       "import": "./dist/unplugin/index.mjs",
-      "require": "./dist/unplugin/index.js"
+      "require": "./dist/unplugin/index.cjs"
     },
     "./lsp": {
-      "types": "./dist/lsp/index.d.ts",
-      "require": "./dist/lsp/index.js"
+      "types": "./dist/lsp/index.d.mts",
+      "import": "./dist/lsp/index.mjs",
+      "require": "./dist/lsp/index.cjs"
     }
   },
   "bin": {
-    "neo-syringe": "./dist/cli/index.js"
+    "neo-syringe": "./dist/cli/index.mjs"
   },
   "scripts": {
     "build": "tsdown",

package/src/analyzer/Analyzer.ts

@@ -283,11 +283,12 @@ export class Analyzer {
   }
 
   private parseInjectionObject(obj: ts.ObjectLiteralExpression, graph: DependencyGraph): void {
-      // Extract properties: token, provider, scope, useFactory
+      // Extract properties: token, provider, lifecycle, useFactory, scoped
       let tokenNode: ts.Expression | undefined;
       let providerNode: ts.Expression | undefined;
-      let scope: 'singleton' | 'transient' = 'singleton';
+      let lifecycle: 'singleton' | 'transient' = 'singleton';
       let useFactory = false;
+      let isScoped = false;
 
       for (const prop of obj.properties) {
           if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
@@ -296,13 +297,18 @@ export class Analyzer {
               tokenNode = prop.initializer;
           } else if (prop.name.text === 'provider') {
               providerNode = prop.initializer;
-          } else if (prop.name.text === 'scope' && ts.isStringLiteral(prop.initializer)) {
-              if (prop.initializer.text === 'transient') scope = 'transient';
+          } else if (prop.name.text === 'lifecycle' && ts.isStringLiteral(prop.initializer)) {
+              if (prop.initializer.text === 'transient') lifecycle = 'transient';
           } else if (prop.name.text === 'useFactory') {
               // Check if useFactory: true
               if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
                   useFactory = true;
               }
+          } else if (prop.name.text === 'scoped') {
+              // Check if scoped: true
+              if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                  isScoped = true;
+              }
           }
       }
 
@@ -362,7 +368,8 @@ export class Analyzer {
           type = 'factory';
 
           if (tokenId) {
-              if (graph.nodes.has(tokenId)) {
+              // Check for duplicate - allow if scoped: true (intentional override)
+              if (graph.nodes.has(tokenId) && !isScoped) {
                   throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
               }
 
@@ -371,11 +378,12 @@ export class Analyzer {
                   tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : undefined,
                   registrationNode: obj,
                   type: 'factory',
-                  scope: scope,
+                  lifecycle: lifecycle,
                   isInterfaceToken,
                   isValueToken,
                   isFactory: true,
-                  factorySource
+                  factorySource,
+                  isScoped
               };
               graph.nodes.set(tokenId, { service: definition, dependencies: [] });
           }
@@ -406,7 +414,8 @@ export class Analyzer {
       }
 
       if (tokenId && implementationSymbol) {
-         if (graph.nodes.has(tokenId)) {
+         // Check for duplicate - allow if scoped: true (intentional override)
+         if (graph.nodes.has(tokenId) && !isScoped) {
               throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
          }
 
@@ -416,8 +425,9 @@ export class Analyzer {
              tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : undefined,
              registrationNode: obj,
              type: type,
-             scope: scope,
-             isInterfaceToken: isInterfaceToken || (ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode))
+             lifecycle: lifecycle,
+             isInterfaceToken: isInterfaceToken || (ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode)),
+             isScoped
          };
          graph.nodes.set(tokenId, { service: definition, dependencies: [] });
       }

package/src/analyzer/types.ts

@@ -24,7 +24,7 @@ export interface ServiceDefinition {
   registrationNode: Node;
 
   type: RegistrationType;
-  scope: 'singleton' | 'transient';
+  lifecycle: 'singleton' | 'transient';
 
   /**
    * True if the token is an Interface (requires string literal key).
@@ -47,6 +47,12 @@ export interface ServiceDefinition {
    * The raw source text of the factory function (for code generation).
    */
   factorySource?: string;
+
+  /**
+   * True if this injection is scoped to the local container.
+   * Allows overriding a token from a parent container without duplicate error.
+   */
+  isScoped?: boolean;
 }
 
 export interface DependencyNode {

package/src/generator/Generator.ts

@@ -78,7 +78,7 @@ function ${factoryId}(container: NeoContainer) {
       }
 
       // 2. Generate Resolve Switch Case
-      const isTransient = node.service.scope === 'transient';
+      const isTransient = node.service.lifecycle === 'transient';
 
       // Determine key for instances Map and token check
       let tokenKey: string;

package/src/generator/GraphValidator.ts

@@ -19,11 +19,15 @@ export class GraphValidator {
     const parentTokens = graph.parentProvidedTokens ?? new Set<TokenId>();
 
     // 1. Check for Duplicate Registrations (local token already in parent)
-    for (const nodeId of graph.nodes.keys()) {
+    for (const [nodeId, node] of graph.nodes) {
         if (parentTokens.has(nodeId)) {
+            // Allow if scoped: true (intentional override)
+            if (node.service.isScoped) {
+                continue;
+            }
             throw new Error(
                 `Duplicate registration: '${nodeId}' is already registered in the parent container. ` +
-                `Remove the local registration or use a different token.`
+                `Use 'scoped: true' to override the parent's registration intentionally.`
             );
         }
     }