Revas Kit: Service Container (@revas-hq/kit-service-container)

A simple, type-safe service container for managing dependencies in TypeScript applications, part of the Revas Kit library. Inspired by dependency injection containers, it allows registering and resolving service instances using dedicated methods or dictionary-style access.

Installation

npm install @revas-hq/kit-service-container
# or
yarn add @revas-hq/kit-service-container

Features

• Type-safe registration (register) and resolution (resolve).
• Support for checking service existence (has).
• Support for removing services (unregister, delete).
• Optional dictionary-style access (container['myKey']) for compatibility (use with caution).
• Prevents registration/assignment of undefined.
• Prevents overwriting container methods or using reserved keys.
• Throws errors on invalid operations (duplicate registration via register, resolving non-existent keys, invalid direct assignments).

Usage

Create the Service Container

Import the factory function and create an instance:

import { createServiceContainer, ServiceContainer } from "@revas-hq/kit-service-container";

const container: ServiceContainer = createServiceContainer();

Registering a Service

Use the register method. Provide a unique string key and the service instance. The service cannot be undefined.

interface LoggerService {
  log: (message: string) => void;
  error: (message: string) => void;
}

const myLogger: LoggerService = {
  log: (message) => console.log(`[LOG] ${message}`),
  error: (message) => console.error(`[ERR] ${message}`),
};

try {
  container.register<LoggerService>('logger', myLogger);
  console.log("Logger service registered.");

  // Attempting to register again with the same key throws an error
  // container.register('logger', { log: console.log }); // Throws Error
} catch (e) {
  console.error("Registration failed:", (e as Error).message);
}

Resolving a Service

Use the resolve method with the key. You must provide the expected type as a generic argument for type safety. Resolving a non-existent key throws an error.

try {
  // Resolve the service with its type
  const logger = container.resolve<LoggerService>('logger');

  // Use the service
  logger.log("Hello from the container!"); // Output: [LOG] Hello from the container!

  // Attempting to resolve a non-existent service throws an error
  // const nonExistent = container.resolve<any>('dbService'); // Throws Error
} catch (e) {
  console.error("Resolution failed:", (e as Error).message);
}

Checking for a Service

Use the has method to safely check if a key corresponds to a registered service or a container method.

console.log(`Has 'logger'?`, container.has('logger')); // Output: Has 'logger'? true
console.log(`Has 'dbService'?`, container.has('dbService')); // Output: Has 'dbService'? false
console.log(`Has 'resolve'?`, container.has('resolve')); // Output: Has 'resolve'? true (it's a method)

Unregistering a Service

Use the unregister method or the standard delete operator. You cannot unregister container methods.

let wasUnregistered = container.unregister('logger');
console.log(`Unregister 'logger' successful?`, wasUnregistered); // Output: Unregister 'logger' successful? true
console.log(`Has 'logger' after unregister?`, container.has('logger')); // Output: Has 'logger' after unregister? false

// Or using delete
container.register('tempService', { id: 1 });
console.log(`Has 'tempService'?`, container.has('tempService')); // Output: Has 'tempService'? true
delete container['tempService'];
console.log(`Has 'tempService' after delete?`, container.has('tempService')); // Output: Has 'tempService' after delete? false

// Cannot unregister methods
wasUnregistered = container.unregister('register');
console.log(`Unregister 'register' successful?`, wasUnregistered); // Output: Unregister 'register' successful? false
// delete container['resolve']; // Also returns false and logs a warning

Dictionary-Style Access (Use with Caution)

The container also allows direct property access like a dictionary (container['key']).

• Reading: Accessing a registered key returns the service value (typed as unknown). Accessing an unregistered key returns undefined.

container.register('config', { timeout: 5000 });
const config = container['config'] as { timeout: number }; // Type assertion needed!
console.log(config?.timeout); // Output: 5000
const missing = container['missing'];
console.log(missing); // Output: undefined

• Writing: Direct assignment (container['key'] = value) is possible but bypasses duplicate checks performed by register. Assigning undefined or assigning to reserved method keys (register, resolve, etc.) will throw an Error.

try {
  container['newService'] = { data: 'abc' }; // Allowed (bypasses duplicate check)
  console.log(container.resolve<{ data: string }>('newService').data); // Output: abc

  // container['newService'] = { data: 'xyz' }; // Allowed, overwrites without check!

  // container['register'] = () => {}; // Throws Error: Cannot assign to reserved key...
  // container['another'] = undefined; // Throws Error: Cannot assign undefined...
} catch(e) {
   console.error("Direct assignment failed:", (e as Error).message);
}

Recommendation: Prefer the type-safe register, resolve, has, and unregister methods over dictionary-style access for improved safety and clarity.

Error Handling Philosophy

Errors thrown by register (duplicate key, reserved key, undefined service) or resolve (key not found) typically indicate programming errors (e.g., configuration issues, typos). Your application setup logic should generally ensure services are registered correctly before they are resolved. Catching these errors might be appropriate during an initialization phase, but typically not during normal request handling where resolution is expected to succeed.

Errors thrown by direct assignment (container['key'] = undefined, container['reservedKey'] = value) indicate misuse of the dictionary-style access and should be avoided by using the proper methods.

License

This project is licensed under the MIT License. See the LICENSE file for details.