npm package: @revas-hq/kit-container
Description: 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 dictio
Latest version: 0.0.16

# 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

```bash
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:

```typescript
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`.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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`.

```typescript
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.

```typescript
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.