Deprecated 'inject' option in favor of 'provide'

Author: benoitlahoz

docs/assemblerjs/core-concepts/assemblage.md

@@ -52,7 +52,7 @@ The `@Assemblage` decorator accepts a configuration object:
 ```typescript
 @Assemblage({
   singleton: true, // Default: true - share instance across the application
-  inject: [],      // Dependencies to inject
+  provide: [],     // Dependencies to provide (recommended)
   use: [],         // Objects/instances to register
   tags: [],        // Tags for grouping
   events: [],      // Event channels to register
@@ -69,7 +69,8 @@ export class MyService implements AbstractAssemblage {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `singleton` | `boolean` | `true` | If `true`, one instance is shared. If `false`, new instance per injection. |
-| `inject` | `Array` | `[]` | Dependencies to inject (see [Dependency Injection](./dependency-injection.md)) |
+| `provide` | `Array` | `[]` | Dependencies to provide (see [Dependency Injection](./dependency-injection.md)) |
+| `inject` | `Array` | `[]` | **⚠️ Deprecated** - Use `provide` instead. Will be removed in a future version. |
 | `use` | `Array` | `[]` | Objects/instances to register for `@Use()` decorator |
 | `tags` | `string[]` | `[]` | Tags for grouping (see [Tags](../features/tags.md)) |
 | `events` | `string[]` | `[]` | Event channels to register (see [Events](../features/events.md)) |

docs/assemblerjs/core-concepts/dependency-injection.md

@@ -1,14 +1,16 @@
 # Dependency Injection
 
-Dependencies are declared in the `inject` property of the `@Assemblage` decorator and injected via the constructor.
+Dependencies are declared in the `provide` property of the `@Assemblage` decorator and injected via the constructor.
+
+> **Note:** The `inject` property is deprecated in favor of `provide`. While `inject` still works, it will be removed in a future version.
 
 ## Basic Injection
 
-The simplest form injects a concrete class:
+The simplest form provides a concrete class:
 
 ```typescript
 @Assemblage({
-  inject: [[ConcreteClass]],
+  provide: [[ConcreteClass]],
 })
 class MyApp implements AbstractAssemblage {
   constructor(private service: ConcreteClass) {
@@ -23,7 +25,7 @@ Bind an abstraction to a concrete implementation:
 
 ```typescript
 @Assemblage({
-  inject: [
+  provide: [
     [AbstractClass, ConcreteClass], // AbstractClass must implement AbstractAssemblage
   ],
 })
@@ -49,7 +51,7 @@ Pass configuration to dependencies:
 
 ```typescript
 @Assemblage({
-  inject: [
+  provide: [
     [DatabaseService, { host: 'localhost', port: 5432 }],
   ],
 })
@@ -71,7 +73,7 @@ Inject multiple dependencies:
 
 ```typescript
 @Assemblage({
-  inject: [
+  provide: [
     [Logger],
     [DatabaseService],
     [CacheService],
@@ -88,7 +90,7 @@ class MyApp implements AbstractAssemblage {
 }
 ```
 
-**Note:** Dependencies are resolved by type using TypeScript's reflection system. The order of constructor parameters doesn't need to match the `inject` array order.
+**Note:** Dependencies are resolved by type using TypeScript's reflection system. The order of constructor parameters doesn't need to match the `provide` array order.
 
 ## Dependency Resolution
 

docs/assemblerjs/guides/migration-inject-to-provide.md

@@ -0,0 +1,214 @@
+# Migration Guide: `inject` → `provide`
+
+## Overview
+
+The `inject` option in the `@Assemblage` decorator has been deprecated in favor of `provide`. This change improves semantic clarity: you **provide** dependencies to a class rather than **inject** them.
+
+## Why the Change?
+
+The term "provide" better describes what happens at the decorator level:
+- You **provide** a list of dependencies that the class needs
+- The DI container **injects** those dependencies into the constructor
+
+This aligns better with dependency injection terminology used in other frameworks.
+
+## Backward Compatibility
+
+✅ **Your existing code continues to work** - No breaking changes  
+⚠️ **Console warnings** will appear when using `inject`  
+🔮 **Future removal** - `inject` will be removed in a future major version
+
+## Migration Steps
+
+### Before (Deprecated)
+```typescript
+@Assemblage({
+  inject: [[Logger], [Database]]
+})
+class UserService {
+  constructor(
+    private logger: Logger,
+    private database: Database
+  ) {}
+}
+```
+
+### After (Recommended)
+```typescript
+@Assemblage({
+  provide: [[Logger], [Database]]
+})
+class UserService {
+  constructor(
+    private logger: Logger,
+    private database: Database
+  ) {}
+}
+```
+
+## Examples
+
+### Simple Dependency
+
+**Before:**
+```typescript
+@Assemblage({
+  inject: [[ConcreteService]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private service: ConcreteService) {}
+}
+```
+
+**After:**
+```typescript
+@Assemblage({
+  provide: [[ConcreteService]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private service: ConcreteService) {}
+}
+```
+
+### With Abstraction
+
+**Before:**
+```typescript
+@Assemblage({
+  inject: [[AbstractLogger, ConsoleLogger]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private logger: AbstractLogger) {}
+}
+```
+
+**After:**
+```typescript
+@Assemblage({
+  provide: [[AbstractLogger, ConsoleLogger]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private logger: AbstractLogger) {}
+}
+```
+
+### With Configuration
+
+**Before:**
+```typescript
+@Assemblage({
+  inject: [[DatabaseService, { host: 'localhost', port: 5432 }]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private db: DatabaseService) {}
+}
+```
+
+**After:**
+```typescript
+@Assemblage({
+  provide: [[DatabaseService, { host: 'localhost', port: 5432 }]]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(private db: DatabaseService) {}
+}
+```
+
+### Multiple Dependencies
+
+**Before:**
+```typescript
+@Assemblage({
+  inject: [
+    [Logger],
+    [DatabaseService],
+    [CacheService]
+  ]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(
+    private logger: Logger,
+    private db: DatabaseService,
+    private cache: CacheService
+  ) {}
+}
+```
+
+**After:**
+```typescript
+@Assemblage({
+  provide: [
+    [Logger],
+    [DatabaseService],
+    [CacheService]
+  ]
+})
+class MyApp implements AbstractAssemblage {
+  constructor(
+    private logger: Logger,
+    private db: DatabaseService,
+    private cache: CacheService
+  ) {}
+}
+```
+
+## Automated Migration
+
+You can use a simple search and replace in your IDE:
+
+**Find:**
+```regex
+inject:\s*\[
+```
+
+**Replace with:**
+```
+provide: [
+```
+
+This will update all occurrences in your codebase.
+
+## Transition Behavior
+
+If both options are present, `provide` takes precedence:
+
+```typescript
+@Assemblage({
+  inject: [[OldService]],   // ⚠️ Ignored
+  provide: [[NewService]]   // ✅ Used
+})
+class MyService {
+  constructor(private service: NewService) {} // NewService is injected
+}
+```
+
+A console warning will notify you of this situation.
+
+## Deprecation Timeline
+
+- **Current Version**: `provide` introduced, `inject` deprecated with warnings
+- **Future Major Version**: `inject` will be completely removed
+
+## FAQ
+
+### Q: Do I need to migrate immediately?
+**A:** No, but it's recommended. Your code will continue working, but you'll see deprecation warnings in the console.
+
+### Q: Is there any behavioral difference?
+**A:** No. `provide` works exactly like `inject`. It's purely a semantic improvement.
+
+### Q: What happens if I use both?
+**A:** `provide` takes priority, and you'll see a warning. Choose one or the other.
+
+### Q: How do I silence the warnings?
+**A:** Replace all `inject:` with `provide:` in your `@Assemblage` decorators.
+
+### Q: Will TypeScript autocomplete work?
+**A:** Yes! Full TypeScript support is maintained for both options during the transition period.
+
+## Need Help?
+
+If you encounter any issues during migration, please:
+- Check the [Dependency Injection](../core-concepts/dependency-injection.md) guide
+- Review the [Assemblage](../core-concepts/assemblage.md) documentation
+- Open an issue on GitHub

docs/assemblerjs/index.md

@@ -30,7 +30,7 @@ class Logger implements AbstractAssemblage {
   }
 }
 
-@Assemblage({ inject: [[Logger]] })
+@Assemblage({ provide: [[Logger]] })
 class App implements AbstractAssemblage {
   constructor(private logger: Logger) {}
 

packages/assemblerjs/README.md

@@ -83,7 +83,7 @@ class Logger implements AbstractAssemblage {
 
 // Define an application that depends on Logger
 @Assemblage({
-  inject: [[Logger]], // Declare dependencies
+  provide: [[Logger]], // Declare dependencies
 })
 class App implements AbstractAssemblage {
   constructor(private logger: Logger) {}

packages/assemblerjs/coverage/coverage-final.json

@@ -1,24 +1,24 @@
-{"total": {"lines":{"total":1152,"covered":1023,"skipped":0,"pct":88.8},"statements":{"total":1215,"covered":1056,"skipped":0,"pct":86.91},"functions":{"total":327,"covered":299,"skipped":0,"pct":91.43},"branches":{"total":648,"covered":476,"skipped":0,"pct":73.45},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":100}}
+{"total": {"lines":{"total":1181,"covered":1069,"skipped":0,"pct":90.51},"statements":{"total":1246,"covered":1104,"skipped":0,"pct":88.6},"functions":{"total":335,"covered":308,"skipped":0,"pct":91.94},"branches":{"total":677,"covered":511,"skipped":0,"pct":75.48},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/decorator.ts": {"lines":{"total":8,"covered":8,"skipped":0,"pct":100},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":8,"covered":8,"skipped":0,"pct":100},"branches":{"total":2,"covered":2,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/helpers.ts": {"lines":{"total":6,"covered":5,"skipped":0,"pct":83.33},"functions":{"total":3,"covered":2,"skipped":0,"pct":66.66},"statements":{"total":6,"covered":5,"skipped":0,"pct":83.33},"branches":{"total":2,"covered":2,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/definition/inject.ts": {"lines":{"total":21,"covered":20,"skipped":0,"pct":95.23},"functions":{"total":16,"covered":15,"skipped":0,"pct":93.75},"statements":{"total":23,"covered":22,"skipped":0,"pct":95.65},"branches":{"total":4,"covered":4,"skipped":0,"pct":100}}
-,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/definition/schema.ts": {"lines":{"total":59,"covered":59,"skipped":0,"pct":100},"functions":{"total":33,"covered":33,"skipped":0,"pct":100},"statements":{"total":59,"covered":59,"skipped":0,"pct":100},"branches":{"total":46,"covered":46,"skipped":0,"pct":100}}
+,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/definition/schema.ts": {"lines":{"total":67,"covered":66,"skipped":0,"pct":98.5},"functions":{"total":37,"covered":36,"skipped":0,"pct":97.29},"statements":{"total":67,"covered":66,"skipped":0,"pct":98.5},"branches":{"total":60,"covered":60,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assemblage/lib/definition/use.ts": {"lines":{"total":11,"covered":10,"skipped":0,"pct":90.9},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":11,"covered":10,"skipped":0,"pct":90.9},"branches":{"total":12,"covered":9,"skipped":0,"pct":75}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/assembler-builder.ts": {"lines":{"total":32,"covered":28,"skipped":0,"pct":87.5},"functions":{"total":4,"covered":3,"skipped":0,"pct":75},"statements":{"total":32,"covered":28,"skipped":0,"pct":87.5},"branches":{"total":6,"covered":4,"skipped":0,"pct":66.66}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/assembler.ts": {"lines":{"total":39,"covered":38,"skipped":0,"pct":97.43},"functions":{"total":16,"covered":15,"skipped":0,"pct":93.75},"statements":{"total":39,"covered":38,"skipped":0,"pct":97.43},"branches":{"total":12,"covered":12,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/context-provider.ts": {"lines":{"total":3,"covered":3,"skipped":0,"pct":100},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":3,"covered":3,"skipped":0,"pct":100},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
-,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/cycle-detector.ts": {"lines":{"total":35,"covered":8,"skipped":0,"pct":22.85},"functions":{"total":8,"covered":4,"skipped":0,"pct":50},"statements":{"total":38,"covered":8,"skipped":0,"pct":21.05},"branches":{"total":16,"covered":0,"skipped":0,"pct":0}}
-,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/debug-logger.ts": {"lines":{"total":64,"covered":51,"skipped":0,"pct":79.68},"functions":{"total":30,"covered":25,"skipped":0,"pct":83.33},"statements":{"total":73,"covered":54,"skipped":0,"pct":73.97},"branches":{"total":66,"covered":41,"skipped":0,"pct":62.12}}
+,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/cycle-detector.ts": {"lines":{"total":34,"covered":27,"skipped":0,"pct":79.41},"functions":{"total":8,"covered":6,"skipped":0,"pct":75},"statements":{"total":37,"covered":27,"skipped":0,"pct":72.97},"branches":{"total":14,"covered":8,"skipped":0,"pct":57.14}}
+,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/debug-logger.ts": {"lines":{"total":81,"covered":66,"skipped":0,"pct":81.48},"functions":{"total":34,"covered":29,"skipped":0,"pct":85.29},"statements":{"total":92,"covered":71,"skipped":0,"pct":77.17},"branches":{"total":80,"covered":51,"skipped":0,"pct":63.75}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/hook-manager.ts": {"lines":{"total":41,"covered":35,"skipped":0,"pct":85.36},"functions":{"total":11,"covered":8,"skipped":0,"pct":72.72},"statements":{"total":50,"covered":38,"skipped":0,"pct":76},"branches":{"total":24,"covered":15,"skipped":0,"pct":62.5}}
-,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/injectable-manager.ts": {"lines":{"total":92,"covered":65,"skipped":0,"pct":70.65},"functions":{"total":13,"covered":12,"skipped":0,"pct":92.3},"statements":{"total":105,"covered":68,"skipped":0,"pct":64.76},"branches":{"total":79,"covered":34,"skipped":0,"pct":43.03}}
+,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/injectable-manager.ts": {"lines":{"total":97,"covered":70,"skipped":0,"pct":72.16},"functions":{"total":13,"covered":12,"skipped":0,"pct":92.3},"statements":{"total":110,"covered":73,"skipped":0,"pct":66.36},"branches":{"total":81,"covered":36,"skipped":0,"pct":44.44}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/object-manager.ts": {"lines":{"total":21,"covered":20,"skipped":0,"pct":95.23},"functions":{"total":6,"covered":6,"skipped":0,"pct":100},"statements":{"total":21,"covered":20,"skipped":0,"pct":95.23},"branches":{"total":12,"covered":8,"skipped":0,"pct":66.66}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/assembler/lib/resolution-strategies.ts": {"lines":{"total":13,"covered":13,"skipped":0,"pct":100},"functions":{"total":2,"covered":2,"skipped":0,"pct":100},"statements":{"total":13,"covered":13,"skipped":0,"pct":100},"branches":{"total":4,"covered":4,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/events/lib/helpers.ts": {"lines":{"total":26,"covered":22,"skipped":0,"pct":84.61},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":27,"covered":23,"skipped":0,"pct":85.18},"branches":{"total":16,"covered":10,"skipped":0,"pct":62.5}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/events/lib/collection/listener-collection.ts": {"lines":{"total":52,"covered":45,"skipped":0,"pct":86.53},"functions":{"total":24,"covered":20,"skipped":0,"pct":83.33},"statements":{"total":53,"covered":46,"skipped":0,"pct":86.79},"branches":{"total":16,"covered":12,"skipped":0,"pct":75}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/events/lib/manager/event-manager.ts": {"lines":{"total":55,"covered":48,"skipped":0,"pct":87.27},"functions":{"total":17,"covered":15,"skipped":0,"pct":88.23},"statements":{"total":56,"covered":49,"skipped":0,"pct":87.5},"branches":{"total":22,"covered":19,"skipped":0,"pct":86.36}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/injectable/lib/dependencies.ts": {"lines":{"total":42,"covered":40,"skipped":0,"pct":95.23},"functions":{"total":4,"covered":4,"skipped":0,"pct":100},"statements":{"total":44,"covered":42,"skipped":0,"pct":95.45},"branches":{"total":21,"covered":17,"skipped":0,"pct":80.95}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/injectable/lib/injectable-builder.ts": {"lines":{"total":18,"covered":16,"skipped":0,"pct":88.88},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":18,"covered":16,"skipped":0,"pct":88.88},"branches":{"total":12,"covered":8,"skipped":0,"pct":66.66}}
-,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/injectable/lib/injectable.ts": {"lines":{"total":115,"covered":108,"skipped":0,"pct":93.91},"functions":{"total":19,"covered":18,"skipped":0,"pct":94.73},"statements":{"total":117,"covered":110,"skipped":0,"pct":94.01},"branches":{"total":105,"covered":84,"skipped":0,"pct":80}}
+,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/injectable/lib/injectable.ts": {"lines":{"total":115,"covered":108,"skipped":0,"pct":93.91},"functions":{"total":19,"covered":18,"skipped":0,"pct":94.73},"statements":{"total":117,"covered":110,"skipped":0,"pct":94.01},"branches":{"total":106,"covered":85,"skipped":0,"pct":80.18}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/transversals/decorators/affect.ts": {"lines":{"total":7,"covered":7,"skipped":0,"pct":100},"functions":{"total":3,"covered":3,"skipped":0,"pct":100},"statements":{"total":7,"covered":7,"skipped":0,"pct":100},"branches":{"total":4,"covered":4,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/transversals/lib/decorators.ts": {"lines":{"total":25,"covered":25,"skipped":0,"pct":100},"functions":{"total":10,"covered":10,"skipped":0,"pct":100},"statements":{"total":25,"covered":25,"skipped":0,"pct":100},"branches":{"total":17,"covered":17,"skipped":0,"pct":100}}
 ,"/Users/benoitlahoz/Documents/Development/assemblerjs/packages/assemblerjs/src/features/transversals/lib/pointcut-matcher.ts": {"lines":{"total":15,"covered":14,"skipped":0,"pct":93.33},"functions":{"total":4,"covered":4,"skipped":0,"pct":100},"statements":{"total":15,"covered":14,"skipped":0,"pct":93.33},"branches":{"total":6,"covered":5,"skipped":0,"pct":83.33}}