@dws-std/registry 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominus Web Services (DWS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# 🎯 DWS Registry
+
+If you've ever copy-pasted a `getInstance()` pattern into yet another class, this package is for you.
+It gives you a single, centralized registry to store and retrieve instances — type-safe, predictable, and easy to test.
+
+## Why this package?
+
+The classic singleton pattern works, but it scatters `static instance` fields across your codebase.
+Every class re-implements the same boilerplate. With `Registry`, you register instances once and retrieve them anywhere by name.
+One registry, no duplication.
+
+## 📌 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
+
+## ✨ Features
+
+- 🔒 **Type-safe** — Full generics support, no `any` casting required.
+- 🎯 **Centralized** — One place to manage all your instances.
+- ⚡ **Lightweight** — Minimal overhead, does exactly what it says.
+
+## 🔧 Installation
+
+```bash
+bun add @dws-std/registry
+```
+
+## ⚙️ Usage
+
+### Registering instances
+
+Register your instances once at startup. They're available everywhere after that.
+
+```ts
+import { Registry } from '@dws-std/registry';
+
+class DatabaseConnection {
+	private _isConnected: boolean = false;
+
+	public constructor() {
+		console.log('Database connection created');
+		this._isConnected = true;
+	}
+
+	public query(sql: string): string[] {
+		return ['result1', 'result2'];
+	}
+}
+
+class ApiClient {
+	public constructor(
+		private readonly _baseUrl: string,
+		private readonly _apiKey: string
+	) {}
+
+	public get baseUrl(): string {
+		return this._baseUrl;
+	}
+}
+
+Registry.register('DatabaseConnection', new DatabaseConnection());
+Registry.register('ApiClient', new ApiClient('https://api.example.com', 'key'));
+```
+
+### Retrieving instances
+
+Same instance, every time. You specify the type via the generic, and TypeScript takes care of the rest.
+
+```ts
+const db1 = Registry.get<DatabaseConnection>('DatabaseConnection');
+const db2 = Registry.get<DatabaseConnection>('DatabaseConnection');
+
+console.log(db1 === db2); // true — same reference
+
+db1.query('SELECT * FROM users'); // type-safe
+```
+
+### Checking & swapping
+
+```ts
+if (Registry.has('ApiClient')) {
+	const client = Registry.get<ApiClient>('ApiClient');
+	console.log(client.baseUrl);
+}
+
+// Need to replace an instance? Unregister first, then register the new one.
+Registry.unregister('DatabaseConnection');
+Registry.register('DatabaseConnection', new DatabaseConnection());
+```
+
+## 📚 API Reference
+
+Full docs: [Dominus-Web-Service.github.io/packages](https://Dominus-Web-Service.github.io/packages/)
+
+## ⚖️ License
+
+MIT — Feel free to use it.
+
+## 📧 Contact
+
+- GitHub: [Dominus-Web-Service](https://github.com/Dominus-Web-Service/packages)

package/dist/constant/registry-error-keys.d.ts

@@ -0,0 +1,5 @@
+/** Error codes thrown by the {@link Registry} class. */
+export declare const REGISTRY_ERROR_KEYS: {
+    readonly CLASS_INSTANCE_ALREADY_REGISTERED: "registry.classInstanceAlreadyRegistered";
+    readonly CLASS_INSTANCE_NOT_REGISTERED: "registry.classInstanceNotRegistered";
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { REGISTRY_ERROR_KEYS } from './constant/registry-error-keys';
+export { Registry } from './registry';

package/dist/index.js

@@ -0,0 +1,45 @@
+// @bun
+// src/constant/registry-error-keys.ts
+var REGISTRY_ERROR_KEYS = {
+  CLASS_INSTANCE_ALREADY_REGISTERED: "registry.classInstanceAlreadyRegistered",
+  CLASS_INSTANCE_NOT_REGISTERED: "registry.classInstanceNotRegistered"
+};
+// src/registry.ts
+import { Exception } from "@dws-std/error";
+class Registry {
+  static _registry = new Map;
+  static register(name, instance) {
+    if (this._registry.has(name))
+      throw new Exception(`Instance already registered: ${name}`, {
+        code: REGISTRY_ERROR_KEYS.CLASS_INSTANCE_ALREADY_REGISTERED,
+        cause: name
+      });
+    this._registry.set(name, instance);
+  }
+  static unregister(name) {
+    if (!this._registry.delete(name))
+      throw new Exception(`Instance not registered: ${name}`, {
+        code: REGISTRY_ERROR_KEYS.CLASS_INSTANCE_NOT_REGISTERED,
+        cause: name
+      });
+  }
+  static get(name) {
+    const instance = this._registry.get(name);
+    if (!instance)
+      throw new Exception(`Instance not registered: ${name}`, {
+        code: REGISTRY_ERROR_KEYS.CLASS_INSTANCE_NOT_REGISTERED,
+        cause: name
+      });
+    return instance;
+  }
+  static has(name) {
+    return this._registry.has(name);
+  }
+  static clear() {
+    this._registry.clear();
+  }
+}
+export {
+  Registry,
+  REGISTRY_ERROR_KEYS
+};

package/dist/registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Global, type-safe store for named instances.
+ *
+ * Register an instance once at startup, then retrieve it anywhere
+ * by name without passing references around.
+ *
+ * @example
+ * ```ts
+ * Registry.register('db', new DatabaseConnection());
+ * const db = Registry.get<DatabaseConnection>('db');
+ * ```
+ */
+export declare class Registry {
+    private static readonly _registry;
+    /**
+     * Stores `instance` under the given `name`.
+     *
+     * Each name can only be registered once. Call {@link unregister} first
+     * if you need to replace an existing instance.
+     *
+     * @template TClass - The type of the instance being stored.
+     *
+     * @param name - Unique identifier for this instance.
+     * @param instance - The object to store.
+     *
+     * @throws ({@link Exception}) – `name` is already taken.
+     */
+    static register<TClass extends object>(name: string, instance: TClass): void;
+    /**
+     * Removes the instance stored under `name`.
+     *
+     * After this call, `name` can be registered again with a new instance.
+     *
+     * @param name - Identifier of the instance to remove.
+     *
+     * @throws ({@link Exception}) – `name` is not registered.
+     */
+    static unregister(name: string): void;
+    /**
+     * Retrieves the instance stored under `name`.
+     *
+     * The caller specifies the expected type via the generic parameter;
+     * no runtime type-check is performed.
+     *
+     * @template TClass - Expected type of the stored instance.
+     *
+     * @param name - Identifier of the instance to retrieve.
+     *
+     * @throws ({@link Exception}) – `name` is not registered.
+     */
+    static get<TClass>(name: string): TClass;
+    /**
+     * Checks whether an instance is stored under `name`.
+     *
+     * @param name - Identifier to look up.
+     */
+    static has(name: string): boolean;
+    /** Removes every stored instance — useful for test teardown. */
+    static clear(): void;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@dws-std/registry",
+	"version": "1.0.0",
+	"description": "Centralized, type-safe registry for managing named instances.",
+	"keywords": [
+		"bun",
+		"dws",
+		"registry",
+		"type-safe"
+	],
+	"license": "MIT",
+	"author": "Dominus Web Services (DWS)",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Dominus-Web-Service/std",
+		"directory": "packages/registry"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "bun builder.ts",
+		"docs": "bunx typedoc --tsconfig tsconfig.build.json",
+		"fmt:check": "oxfmt --check",
+		"fmt": "oxfmt",
+		"lint:fix": "oxlint --type-aware --type-check --fix ./src",
+		"lint:github": "oxlint --type-aware --type-check --format=github ./src",
+		"lint": "oxlint --type-aware --type-check ./src",
+		"test": "bun test --pass-with-no-tests --coverage"
+	},
+	"dependencies": {
+		"@dws-std/error": "^2.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.10",
+		"oxfmt": "^0.40.0",
+		"oxlint": "^1.55.0",
+		"oxlint-tsgolint": "^0.16.0",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@dws-std/error": "^2.0.0"
+	}
+}