feat: hierarchical dependency injection

Author: DrewImm

.eslintrc.js

@@ -41,7 +41,11 @@ module.exports = {
 		"@typescript-eslint/no-floating-promises": 2,
 		"@typescript-eslint/no-misused-new": 2,
 		"@typescript-eslint/no-namespace": 1,
-		"@typescript-eslint/no-unused-vars": 1,
+		"@typescript-eslint/no-unused-vars": [1, {
+			"argsIgnorePattern": "^_",
+			"varsIgnorePattern": "^_",
+			"caughtErrorsIgnorePattern": "^_"
+		}],
 		"@typescript-eslint/promise-function-async": 1,
 		"@typescript-eslint/no-var-requires": 2,
 	},

examples/complete-example/README.md

@@ -72,6 +72,39 @@ curl "http://localhost:3000/api/express/search?q=test&page=2&limit=20"
 curl http://localhost:3000/api/health
 ```
 
+### Dependency Injection
+
+API-Machine uses `hidi`. You can register dependencies at the server, router or endpoint level.
+
+```typescript
+class MyService {
+	...
+}
+
+class MyRouter extends BaseApiRouter {
+	override inject() {
+		super.inject();
+
+		// Register a dependency at the router level
+		this.container.register(MyService, new MyService());
+	}
+}
+
+class MyEndpoint extends BaseApiEndpoint {
+	protected myService: MyService;
+
+	override inject() {
+		super.inject();
+
+		this.myService = this.container.require(MyService);
+	}
+
+	async handle(request: ApiRequest, response: ApiResponse) {
+		this.myService.performAction();
+	}
+}
+```
+
 ### Bearer Token Authentication (Inline, Stateless)
 
 Bearer authentication validates a token on every request without maintaining session state.

examples/complete-example/server.ts

@@ -2,6 +2,8 @@ import { RestServer } from '../../src/index';
 import { MainRouter } from './router';
 import { Log } from 'ts-tiny-log';
 
+import { UsersRepository } from './users/users-repository';
+
 /**
  * Complete Example - Server
  *
@@ -12,6 +14,12 @@ import { Log } from 'ts-tiny-log';
 export class MyServer extends RestServer {
 	override router = MainRouter;
 
+	override async inject(): Promise<void> {
+		await super.inject();
+
+		this.container.register(UsersRepository, new UsersRepository());
+	}
+
 	protected override async setupExpress(): Promise<void> {
 		await super.setupExpress();
 		// Add middleware to parse sessionId from cookies

examples/complete-example/users/create-user-endpoint.ts

@@ -1,5 +1,5 @@
 import { ApiRequest, ApiResponse, PostEndpoint } from '../../../src/index';
-import { usersRepo, User } from './users-repository';
+import { UsersRepository } from './users-repository';
 import { ObjectValSan, EmailValidator, IntegerValidator } from 'valsan';
 import { NameValSan } from './name-valsan';
 
@@ -11,6 +11,8 @@ import { NameValSan } from './name-valsan';
 export class CreateUserEndpoint extends PostEndpoint {
 	override path = '/';
 
+	protected usersRepo: UsersRepository;
+
 	override bodyExample = {
 		name: 'John Doe',
 		email: 'john@example.com',
@@ -38,22 +40,15 @@ export class CreateUserEndpoint extends PostEndpoint {
 		},
 	});
 
+	override inject(): void {
+		this.usersRepo = this.container.require(UsersRepository);
+	}
+
 	async handle(request: ApiRequest, response: ApiResponse) {
 		const { name, email } = request.body;
 
-		// Generate new ID
-		const newId = Math.max(...Object.keys(usersRepo).map(Number)) + 1;
-
-		// Create new user
-		const newUser: User = {
-			id: newId,
-			name,
-			email,
-			created: new Date(),
-		};
-
-		// Add to repository
-		usersRepo[newId] = newUser;
+		// Create and add to repository
+		const newUser = this.usersRepo.add({ name, email });
 
 		// Return new user (PostEndpoint automatically sets 201 status)
 		return newUser;

examples/complete-example/users/delete-user-endpoint.ts

@@ -4,7 +4,7 @@ import {
 	DeleteEndpoint,
 	NotFoundError,
 } from '../../../src/index';
-import { usersRepo } from './users-repository';
+import { UsersRepository } from './users-repository';
 
 /**
  * Complete Example - Delete User Endpoint (DELETE)
@@ -14,18 +14,23 @@ import { usersRepo } from './users-repository';
 export class DeleteUserEndpoint extends DeleteEndpoint {
 	override path = '/:id';
 
+	protected usersRepo: UsersRepository;
+
+	override inject(): void {
+		this.usersRepo = this.container.require(UsersRepository);
+	}
+
 	async handle(request: ApiRequest, response: ApiResponse) {
 		const userId = parseInt(request.params['id'], 10);
-		const user = usersRepo[userId];
+		const user = this.usersRepo.getById(userId);
 
 		if (!user) {
 			throw new NotFoundError('User not found', {
 				details: { userId },
 			});
 		}
 
-		// Delete user from repository
-		delete usersRepo[userId];
+		this.usersRepo.delete(userId);
 
 		// DeleteEndpoint automatically sets 204 status
 		return {};

examples/complete-example/users/get-user-endpoint.ts

@@ -1,6 +1,6 @@
 import { ApiRequest, ApiResponse, GetEndpoint } from '../../../src/index';
 import { NotFoundError } from '../../../src/error';
-import { usersRepo } from './users-repository';
+import { UsersRepository } from './users-repository';
 import { IntegerValidator, EmailValidator, ObjectValSan } from 'valsan';
 import { NameValSan } from './name-valsan';
 
@@ -13,6 +13,8 @@ import { NameValSan } from './name-valsan';
 export class GetUserEndpoint extends GetEndpoint {
 	override path = '/:id';
 
+	protected usersRepo: UsersRepository;
+
 	override responseExample = {
 		id: 1,
 		name: 'Alice',
@@ -28,9 +30,13 @@ export class GetUserEndpoint extends GetEndpoint {
 		},
 	});
 
+	override inject(): void {
+		this.usersRepo = this.container.require(UsersRepository);
+	}
+
 	async handle(request: ApiRequest, response: ApiResponse) {
 		const userId = parseInt(request.params['id'], 10);
-		const user = usersRepo[userId];
+		const user = this.usersRepo.getById(userId);
 
 		if (!user) {
 			// Throw HTTPError - server will automatically format response

examples/complete-example/users/list-users-endpoint.ts

@@ -5,7 +5,7 @@ import {
 	TrimSanitizer,
 } from 'valsan';
 import { ApiRequest, ApiResponse, GetEndpoint } from '../../../src/index';
-import { usersRepo } from './users-repository';
+import { UsersRepository } from './users-repository';
 
 /**
  * Complete Example - List Users Endpoint
@@ -16,6 +16,8 @@ import { usersRepo } from './users-repository';
 export class ListUsersEndpoint extends GetEndpoint {
 	override path = '/';
 
+	protected usersRepo: UsersRepository;
+
 	override params = new ObjectValSan({
 		schema: {
 			name: new ComposedValSan(
@@ -29,7 +31,11 @@ export class ListUsersEndpoint extends GetEndpoint {
 		},
 	});
 
+	override inject(): void {
+		this.usersRepo = this.container.require(UsersRepository);
+	}
+
 	async handle(request: ApiRequest, response: ApiResponse) {
-		return Object.values(usersRepo);
+		return this.usersRepo.getAll();
 	}
 }

examples/complete-example/users/update-user-endpoint.ts

@@ -1,5 +1,5 @@
 import { ApiRequest, PutEndpoint, NotFoundError } from '../../../src/index';
-import { usersRepo } from './users-repository';
+import { UsersRepository } from './users-repository';
 
 /**
  * Complete Example - Update User Endpoint (PUT)
@@ -9,26 +9,25 @@ import { usersRepo } from './users-repository';
 export class UpdateUserEndpoint extends PutEndpoint {
 	override path = '/:id';
 
+	protected usersRepo: UsersRepository;
+
+	override inject(): void {
+		this.usersRepo = this.container.require(UsersRepository);
+	}
+
 	async handle(request: ApiRequest) {
 		const userId = parseInt(request.params['id'], 10);
-		const user = usersRepo[userId];
-
-		if (!user) {
-			throw new NotFoundError('User not found', {
-				details: { userId },
-			});
-		}
 
 		// Update user properties
 		const { name, email } = request.body;
-		if (name) {
-			user.name = name;
-		}
+		const updatedUser = this.usersRepo.update(userId, { name, email });
 
-		if (email) {
-			user.email = email;
+		if (!updatedUser) {
+			throw new NotFoundError('User not found', {
+				details: { userId },
+			});
 		}
 
-		return user;
+		return updatedUser;
 	}
 }

examples/complete-example/users/users-repository.ts

@@ -5,17 +5,63 @@ export interface User {
 	created: Date;
 }
 
-export const usersRepo: { [id: number]: User } = {
-	1: {
-		id: 1,
-		name: 'Alice',
-		email: 'alice@example.com',
-		created: new Date('2023-01-01'),
-	},
-	2: {
-		id: 2,
-		name: 'Bob',
-		email: 'bob@example.com',
-		created: new Date('2023-01-02'),
-	},
-};
+export class UsersRepository {
+	protected readonly users: { [id: number]: User } = {
+		1: {
+			id: 1,
+			name: 'Alice',
+			email: 'alice@example.com',
+			created: new Date('2023-01-01'),
+		},
+		2: {
+			id: 2,
+			name: 'Bob',
+			email: 'bob@example.com',
+			created: new Date('2023-01-02'),
+		},
+	};
+
+	public getAll(): User[] {
+		return Object.values(this.users);
+	}
+
+	public getById(id: number): User | undefined {
+		return this.users[id];
+	}
+
+	public add(user: Omit<User, 'id' | 'created'>): User {
+		const id = Math.max(...Object.keys(this.users).map(Number)) + 1;
+
+		const newUser: User = {
+			...user,
+			id,
+			created: new Date(),
+		};
+
+		this.users[id] = newUser;
+
+		return newUser;
+	}
+
+	public update(
+		id: number,
+		user: Partial<Omit<User, 'id' | 'created'>>
+	): User | undefined {
+		if (!this.users[id]) {
+			return undefined;
+		}
+		this.users[id] = { ...this.users[id], ...user };
+
+		return this.users[id];
+	}
+
+	public delete(id: number): boolean {
+		if (!this.users[id]) {
+			return false;
+		}
+
+		delete this.users[id];
+
+		return true;
+	}
+}

examples/index.ts

@@ -0,0 +1 @@
+import './complete-example/index';