@nowarajs/singleton-manager/README.md

Singleton Manager is a package that provides a simple way to manage singletons in your application. It allows you to create, retrieve, and manage singletons with ease and type safety.

# 🎯 NowaraJS - Singleton Manager

## 📌 Table of Contents

- [🎯 Singleton Manager](#-singleton-manager)
	- [📌 Table of Contents](#-table-of-contents)
	- [📝 Description](#-description)
	- [✨ Features](#-features)
	- [🔧 Installation](#-installation)
	- [⚙️ Usage](#-usage)
		- [Basic Usage](#basic-usage)
		- [With Constructor Parameters](#with-constructor-parameters)
		- [Type Safety](#type-safety)
		- [API Methods](#api-methods)
	- [📚 API Reference](#-api-reference)
	- [⚖️ License](#-license)
	- [📧 Contact](#-contact)

## 📝 Description

> A powerful and type-safe singleton manager for TypeScript/JavaScript applications.

**Singleton Manager** provides a centralized way to manage singleton instances in your application. It ensures that only one instance of each registered class exists throughout the application lifecycle, with full TypeScript support and type safety.

## ✨ Features

- 🔒 **Type-safe**: Full TypeScript support with generics
- 🎯 **Centralized Management**: Single registry for all your singletons
- 🔧 **Constructor Arguments**: Support for classes with constructor parameters
- 🛡️ **Error Handling**: Clear error messages for common mistakes
- ⚡ **Lightweight**: Minimal overhead with maximum functionality
- 🧪 **Well Tested**: Comprehensive test suite included

## 🔧 Installation

```bash
bun add @nowarajs/singleton-manager @nowarajs/error
```

## ⚙️ Usage

### Basic Usage

```typescript
import { SingletonManager } from '@nowarajs/singleton-manager';

// Define your singleton class
class DatabaseConnection {
	private _isConnected = false;

	public constructor() {
		console.log('Database connection created');
		this._isConnected = true;
	}

	public get isConnected(): boolean {
		return this._isConnected;
	}

	public query(sql: string): string[] {
		console.log(`Executing query: ${sql}`);
		return ['result1', 'result2'];
	}
}

// Register the singleton
SingletonManager.register('DatabaseConnection', DatabaseConnection);

// Get the singleton instance (same instance every time)
const db1 = SingletonManager.get<DatabaseConnection>('DatabaseConnection');
const db2 = SingletonManager.get<DatabaseConnection>('DatabaseConnection');

console.log(db1 === db2); // true - same instance
```

### With Constructor Parameters

```typescript
class ApiClient {
	private readonly _baseUrl: string;
	private readonly _apiKey: string;

	public constructor(baseUrl: string, apiKey: string) {
		this._baseUrl = baseUrl;
		this._apiKey = apiKey;
	}

	public get baseUrl(): string {
		return this._baseUrl;
	}
}

// Register with constructor arguments
SingletonManager.register(
	'ApiClient', 
	ApiClient, 
	'https://api.example.com', 
	'your-api-key'
);

// Use the singleton
const client = SingletonManager.get<ApiClient>('ApiClient');
console.log(client.baseUrl); // https://api.example.com
```

### Type Safety

```typescript
// TypeScript provides full type safety
const dbConnection = SingletonManager.get<DatabaseConnection>('DatabaseConnection');
dbConnection.query('SELECT * FROM users'); // ✅ TypeScript knows this method exists

// Attempting to call non-existent methods will cause TypeScript errors
// dbConnection.nonExistentMethod(); // ❌ TypeScript error
```

### API Methods

```typescript
// Check if a singleton is registered
if (SingletonManager.has('DatabaseConnection'))
	const db = SingletonManager.get<DatabaseConnection>('DatabaseConnection');

// Unregister a singleton (removes the instance)
SingletonManager.unregister('DatabaseConnection');

// Re-register will create a new instance
SingletonManager.register('DatabaseConnection', DatabaseConnection);
```

## 📚 API Reference

You can find the complete API reference documentation for `SingletonManager` at:

- [Reference Documentation](https://nowarajs.github.io/singleton-manager/)

## ⚖️ License

Distributed under the MIT License. See [LICENSE](./LICENSE) for more information.

## 📧 Contact

- GitHub: [NowaraJS](https://github.com/NowaraJS)
- Package: [@nowarajs/singleton-manager](https://www.npmjs.com/package/@nowarajs/singleton-manager)