@orchestr-sh/orchestr 1.2.1 → 1.3.0

package/README.md

@@ -26,6 +26,11 @@ npm install @orchestr-sh/orchestr reflect-metadata
 
 **Note**: `reflect-metadata` is required for dependency injection to work.
 
+## Documentation
+
+- **[Dependency Injection Guide](./DEPENDENCY_INJECTION.md)** - Complete guide to using DI with troubleshooting
+- **[DI Example](./examples/dependency-injection/)** - Working example with services and controllers
+
 ## Quick Start
 
 ```typescript
@@ -78,6 +83,45 @@ app.singleton('Database', () => new Database());
 const userService = app.make('UserService');
 ```
 
+### Dependency Injection
+
+Orchestr supports automatic constructor-based dependency injection using TypeScript's reflection:
+
+```typescript
+import { Injectable, Controller, Request, Response } from 'orchestr';
+
+// Define a service
+export class UserService {
+  getUsers() {
+    return [{ id: 1, name: 'John' }];
+  }
+}
+
+// Use @Injectable() decorator to enable DI
+@Injectable()
+export class UserController extends Controller {
+  // Dependencies are automatically injected
+  constructor(private userService: UserService) {
+    super();
+  }
+
+  async index(req: Request, res: Response) {
+    const users = this.userService.getUsers();
+    return res.json({ users });
+  }
+}
+
+// Register the service in a provider
+class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    // Bind the service to the container
+    this.app.singleton(UserService, () => new UserService());
+  }
+}
+```
+
+**Important**: The `@Injectable()` decorator is required for dependency injection to work. It triggers TypeScript to emit metadata about constructor parameters.
+
 ### Service Providers
 
 Organize service registration and bootstrapping:
@@ -211,19 +255,28 @@ Route.get('/profile', handler).addMiddleware(authMiddleware);
 
 ### Controllers
 
-MVC pattern with base controller:
+MVC pattern with base controller and dependency injection:
 
 ```typescript
-import { Controller, Request, Response, Route } from 'orchestr';
+import { Injectable, Controller, Request, Response, Route } from 'orchestr';
 
+// Use @Injectable() when injecting dependencies
+@Injectable()
 class UserController extends Controller {
+  // Services are automatically injected
+  constructor(private userService: UserService) {
+    super();
+  }
+
   async index(req: Request, res: Response) {
-    return res.json({ users: [] });
+    const users = await this.userService.getAll();
+    return res.json({ users });
   }
 
   async show(req: Request, res: Response) {
     const id = req.routeParam('id');
-    return res.json({ user: { id } });
+    const user = await this.userService.findById(id);
+    return res.json({ user });
   }
 
   async store(req: Request, res: Response) {
@@ -231,7 +284,8 @@ class UserController extends Controller {
       name: 'required',
       email: 'required|email',
     });
-    return res.status(201).json({ user: validated });
+    const user = await this.userService.create(validated);
+    return res.status(201).json({ user });
   }
 }
 
@@ -241,6 +295,8 @@ Route.get('/users/:id', [UserController, 'show']);
 Route.post('/users', [UserController, 'store']);
 ```
 
+**Note**: The `@Injectable()` decorator must be used on any class that needs constructor dependency injection. Without it, TypeScript won't emit the metadata needed for automatic resolution.
+
 ### Request
 
 Powerful request helper methods:

package/dist/Support/Injectable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Injectable Decorator
+ *
+ * Marks a class as injectable, enabling TypeScript to emit decorator metadata
+ * required for automatic dependency injection via reflect-metadata.
+ *
+ * This decorator does nothing at runtime - it only triggers TypeScript's
+ * emitDecoratorMetadata feature to include parameter type information.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserController extends Controller {
+ *   constructor(private userService: UserService) {
+ *     super();
+ *   }
+ * }
+ * ```
+ */
+export declare function Injectable(): ClassDecorator;
+//# sourceMappingURL=Injectable.d.ts.map

package/dist/Support/Injectable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Injectable.d.ts","sourceRoot":"","sources":["../../src/Support/Injectable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAM3C"}

package/dist/Support/Injectable.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Injectable = Injectable;
+/**
+ * Injectable Decorator
+ *
+ * Marks a class as injectable, enabling TypeScript to emit decorator metadata
+ * required for automatic dependency injection via reflect-metadata.
+ *
+ * This decorator does nothing at runtime - it only triggers TypeScript's
+ * emitDecoratorMetadata feature to include parameter type information.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserController extends Controller {
+ *   constructor(private userService: UserService) {
+ *     super();
+ *   }
+ * }
+ * ```
+ */
+function Injectable() {
+    return (target) => {
+        // This decorator is intentionally empty.
+        // Its sole purpose is to trigger TypeScript's emitDecoratorMetadata
+        // feature, which adds reflection metadata to the class constructor.
+    };
+}
+//# sourceMappingURL=Injectable.js.map

package/dist/Support/Injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Injectable.js","sourceRoot":"","sources":["../../src/Support/Injectable.ts"],"names":[],"mappings":";;AAmBA,gCAMC;AAzBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU;IACxB,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,yCAAyC;QACzC,oEAAoE;QACpE,oEAAoE;IACtE,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { Controller } from './Routing/Controller';
 export { Facade } from './Support/Facade';
 export { Route } from './Facades/Route';
 export { loadRoutes, base_path, routes_path } from './Support/helpers';
+export { Injectable } from './Support/Injectable';
 export { RouteServiceProvider } from './Providers/RouteServiceProvider';
 export { DatabaseServiceProvider } from './Database/DatabaseServiceProvider';
 export { DatabaseManager } from './Database/DatabaseManager';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGxC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGpE,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAG9D,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAC/H,YAAY,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAGnE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACzG,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,4CAA4C,CAAC;AACpD,YAAY,EACV,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC3E,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGxC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGpE,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAG9D,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAC/H,YAAY,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAGnE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACzG,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,4CAA4C,CAAC;AACpD,YAAY,EACV,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC3E,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -4,7 +4,7 @@
  * Main exports
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.softDeletes = exports.EnsembleCollection = exports.EnsembleBuilder = exports.Ensemble = exports.DB = exports.DrizzleAdapter = exports.raw = exports.Expression = exports.QueryBuilder = exports.Connection = exports.DatabaseManager = exports.DatabaseServiceProvider = exports.RouteServiceProvider = exports.routes_path = exports.base_path = exports.loadRoutes = exports.Route = exports.Facade = exports.Controller = exports.Response = exports.Request = exports.RouteClass = exports.Router = exports.Container = exports.Kernel = exports.ServiceProvider = exports.Application = void 0;
+exports.softDeletes = exports.EnsembleCollection = exports.EnsembleBuilder = exports.Ensemble = exports.DB = exports.DrizzleAdapter = exports.raw = exports.Expression = exports.QueryBuilder = exports.Connection = exports.DatabaseManager = exports.DatabaseServiceProvider = exports.RouteServiceProvider = exports.Injectable = exports.routes_path = exports.base_path = exports.loadRoutes = exports.Route = exports.Facade = exports.Controller = exports.Response = exports.Request = exports.RouteClass = exports.Router = exports.Container = exports.Kernel = exports.ServiceProvider = exports.Application = void 0;
 // Foundation
 var Application_1 = require("./Foundation/Application");
 Object.defineProperty(exports, "Application", { enumerable: true, get: function () { return Application_1.Application; } });
@@ -36,6 +36,9 @@ var helpers_1 = require("./Support/helpers");
 Object.defineProperty(exports, "loadRoutes", { enumerable: true, get: function () { return helpers_1.loadRoutes; } });
 Object.defineProperty(exports, "base_path", { enumerable: true, get: function () { return helpers_1.base_path; } });
 Object.defineProperty(exports, "routes_path", { enumerable: true, get: function () { return helpers_1.routes_path; } });
+// Decorators
+var Injectable_1 = require("./Support/Injectable");
+Object.defineProperty(exports, "Injectable", { enumerable: true, get: function () { return Injectable_1.Injectable; } });
 // Providers
 var RouteServiceProvider_1 = require("./Providers/RouteServiceProvider");
 Object.defineProperty(exports, "RouteServiceProvider", { enumerable: true, get: function () { return RouteServiceProvider_1.RouteServiceProvider; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,aAAa;AACb,wDAAuD;AAA9C,0GAAA,WAAW,OAAA;AACpB,gEAA+D;AAAtD,kHAAA,eAAe,OAAA;AACxB,mDAAkD;AAAzC,gGAAA,MAAM,OAAA;AAEf,YAAY;AACZ,mDAAkD;AAAzC,sGAAA,SAAS,OAAA;AAElB,UAAU;AACV,2CAA0C;AAAjC,gGAAA,MAAM,OAAA;AACf,yCAAsD;AAA7C,mGAAA,KAAK,OAAc;AAC5B,6CAA4C;AAAnC,kGAAA,OAAO,OAAA;AAChB,+CAA8C;AAArC,oGAAA,QAAQ,OAAA;AACjB,mDAAkD;AAAzC,wGAAA,UAAU,OAAA;AAEnB,UAAU;AACV,2CAA0C;AAAjC,gGAAA,MAAM,OAAA;AACf,yCAAwC;AAA/B,8FAAA,KAAK,OAAA;AAEd,UAAU;AACV,6CAAuE;AAA9D,qGAAA,UAAU,OAAA;AAAE,oGAAA,SAAS,OAAA;AAAE,sGAAA,WAAW,OAAA;AAE3C,YAAY;AACZ,yEAAwE;AAA/D,4HAAA,oBAAoB,OAAA;AAC7B,8EAA6E;AAApE,kIAAA,uBAAuB,OAAA;AAEhC,WAAW;AACX,8DAA6D;AAApD,kHAAA,eAAe,OAAA;AACxB,oDAAmD;AAA1C,wGAAA,UAAU,OAAA;AACnB,oDAAmE;AAA1D,uGAAA,OAAO,OAAgB;AAChC,0DAA8D;AAArD,wGAAA,UAAU,OAAA;AAAE,iGAAA,GAAG,OAAA;AACxB,qEAAoE;AAA3D,gHAAA,cAAc,OAAA;AAEvB,mBAAmB;AACnB,mCAAkC;AAAzB,wFAAA,EAAE,OAAA;AAEX,eAAe;AACf,yDAAwD;AAA/C,oGAAA,QAAQ,OAAA;AACjB,uEAAsE;AAA7D,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,wHAAA,kBAAkB,OAAA;AAC3B,+DAA8D;AAArD,0GAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,aAAa;AACb,wDAAuD;AAA9C,0GAAA,WAAW,OAAA;AACpB,gEAA+D;AAAtD,kHAAA,eAAe,OAAA;AACxB,mDAAkD;AAAzC,gGAAA,MAAM,OAAA;AAEf,YAAY;AACZ,mDAAkD;AAAzC,sGAAA,SAAS,OAAA;AAElB,UAAU;AACV,2CAA0C;AAAjC,gGAAA,MAAM,OAAA;AACf,yCAAsD;AAA7C,mGAAA,KAAK,OAAc;AAC5B,6CAA4C;AAAnC,kGAAA,OAAO,OAAA;AAChB,+CAA8C;AAArC,oGAAA,QAAQ,OAAA;AACjB,mDAAkD;AAAzC,wGAAA,UAAU,OAAA;AAEnB,UAAU;AACV,2CAA0C;AAAjC,gGAAA,MAAM,OAAA;AACf,yCAAwC;AAA/B,8FAAA,KAAK,OAAA;AAEd,UAAU;AACV,6CAAuE;AAA9D,qGAAA,UAAU,OAAA;AAAE,oGAAA,SAAS,OAAA;AAAE,sGAAA,WAAW,OAAA;AAE3C,aAAa;AACb,mDAAkD;AAAzC,wGAAA,UAAU,OAAA;AAEnB,YAAY;AACZ,yEAAwE;AAA/D,4HAAA,oBAAoB,OAAA;AAC7B,8EAA6E;AAApE,kIAAA,uBAAuB,OAAA;AAEhC,WAAW;AACX,8DAA6D;AAApD,kHAAA,eAAe,OAAA;AACxB,oDAAmD;AAA1C,wGAAA,UAAU,OAAA;AACnB,oDAAmE;AAA1D,uGAAA,OAAO,OAAgB;AAChC,0DAA8D;AAArD,wGAAA,UAAU,OAAA;AAAE,iGAAA,GAAG,OAAA;AACxB,qEAAoE;AAA3D,gHAAA,cAAc,OAAA;AAEvB,mBAAmB;AACnB,mCAAkC;AAAzB,wFAAA,EAAE,OAAA;AAEX,eAAe;AACf,yDAAwD;AAA/C,oGAAA,QAAQ,OAAA;AACjB,uEAAsE;AAA7D,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,wHAAA,kBAAkB,OAAA;AAC3B,+DAA8D;AAArD,0GAAA,WAAW,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestr-sh/orchestr",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A 1:1 Laravel replica in TypeScript - Brings Laravel's elegant syntax and architecture to Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",