@tstdl/base 0.93.138 → 0.93.140

package/document-management/tests/enum-helpers.test.js

@@ -7,7 +7,6 @@ import { TaskQueue } from '../../task-queue/index.js';
 import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentPropertyDataType } from '../models/document-property.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
-import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
 import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentManagementService } from '../server/services/document-management.service.js';
@@ -24,7 +23,7 @@ describe('Document Management Extended Suite', () => {
     const otherTenantId = crypto.randomUUID();
     beforeAll(async () => {
         ({ injector, database } = await setupIntegrationTest({
-            modules: { taskQueue: false, messageBus: true },
+            modules: { taskQueue: false, messageBus: true, documentManagement: true },
             orm: { schema },
         }));
         injector.register(GenkitModuleOptions, { useValue: {} });
@@ -52,8 +51,8 @@ describe('Document Management Extended Suite', () => {
             fileObjectStorageModule: 'documents',
             fileUploadObjectStorageModule: 'document-uploads',
             filePreviewObjectStorageModule: 'document-previews',
+            injector,
         });
-        await runInInjectionContext(injector, migrateDocumentManagementSchema);
         documentManagementService = await injector.resolveAsync(DocumentManagementService);
         categoryTypeService = await injector.resolveAsync(DocumentCategoryTypeService);
         propertyService = await injector.resolveAsync(DocumentPropertyService);

package/dom/README.md

@@ -0,0 +1,213 @@
+# DOM Utilities
+
+A collection of browser-specific utilities for file interactions and reactive DOM observation. This module bridges standard DOM APIs with RxJS Observables and Signals to provide a modern, declarative developer experience for handling file downloads, uploads, and element observation.
+
+## Table of Contents
+
+1.  [✨ Features](#-features)
+2.  [Core Concepts](#core-concepts)
+3.  [🚀 Basic Usage](#-basic-usage)
+    - [File Download](#file-download)
+    - [File Selection](#file-selection)
+    - [Reactive Resize Observation](#reactive-resize-observation)
+4.  [🔧 Advanced Topics](#-advanced-topics)
+    - [Using Signals for Observation](#using-signals-for-observation)
+    - [Media Query Observation](#media-query-observation)
+    - [Touch Event Streams](#touch-event-streams)
+    - [Mutation & Performance Observation](#mutation--performance-observation)
+5.  [📚 API](#-api)
+
+## ✨ Features
+
+- **Programmatic File Download**: Trigger browser downloads from `Blob` or `File` objects without manual DOM manipulation.
+- **File Selection Dialog**: Open the native file picker programmatically and await the result.
+- **Reactive Observers**: RxJS Observable and Signal wrappers for standard browser observers:
+  - `IntersectionObserver` (Visibility)
+  - `ResizeObserver` (Dimensions)
+  - `MutationObserver` (DOM Tree Changes)
+  - `PerformanceObserver` (Metrics)
+  - `matchMedia` (Media Queries)
+- **Touch Event Stream**: Normalized observable stream for touch interactions.
+
+## Core Concepts
+
+### File Handling
+
+Standard HTML file inputs and download links often require imperative DOM manipulation (e.g., creating a hidden `<a>` tag, clicking it, and removing it). This module abstracts these patterns into simple function calls (`downloadFile`, `openFileSelectDialog`).
+
+### Reactive Observation
+
+Modern browser APIs like `ResizeObserver` and `IntersectionObserver` rely on callbacks. This module converts these APIs into **RxJS Observables** (suffixed with `$`) and **Signals** (no suffix). This allows you to compose DOM events with other asynchronous streams or use them directly in signal-based UI frameworks.
+
+The implementation handles resource management automatically. For example, `observeIntersection$` uses a caching mechanism to share underlying `IntersectionObserver` instances across multiple subscriptions with identical configurations.
+
+## 🚀 Basic Usage
+
+### File Download
+
+Trigger a download for a generated Blob.
+
+```ts
+import { downloadFile } from '@tstdl/base/dom';
+
+const content = new Blob(['Hello, World!'], { type: 'text/plain' });
+
+// Triggers a download of "hello.txt" in the browser
+downloadFile(content, 'hello.txt');
+```
+
+### File Selection
+
+Open a file dialog and await the user's selection.
+
+```ts
+import { openFileSelectDialog } from '@tstdl/base/dom';
+
+async function handleUpload() {
+  // Opens the native file picker
+  const files = await openFileSelectDialog({
+    accept: ['.jpg', '.png', 'image/jpeg'],
+    multiple: true,
+  });
+
+  if (files) {
+    console.log(`User selected ${files.length} files.`);
+    files.forEach((file) => console.log(file.name));
+  } else {
+    console.log('User cancelled the dialog.');
+  }
+}
+```
+
+### Reactive Resize Observation
+
+Observe changes to an element's size using RxJS.
+
+```ts
+import { observeResize$ } from '@tstdl/base/dom';
+
+const element = document.querySelector('#my-component')!;
+
+const subscription = observeResize$(element).subscribe((entry) => {
+  const { width, height } = entry.contentRect;
+  console.log(`New size: ${width}x${height}`);
+});
+
+// Cleanup when done
+// subscription.unsubscribe();
+```
+
+## 🔧 Advanced Topics
+
+### Using Signals for Observation
+
+For state-driven applications, you can use the Signal variants of the observers. These provide the current state synchronously.
+
+```ts
+import { observeIntersection } from '@tstdl/base/dom';
+import { effect } from '@tstdl/base/signals'; // Assuming a signal effect implementation
+
+const element = document.querySelector('#lazy-image')!;
+
+// Returns a Signal<IntersectionObserverEntry | undefined>
+const intersectionSignal = observeIntersection(element, { threshold: 0.5 });
+
+effect(() => {
+  const entry = intersectionSignal();
+  if (entry?.isIntersecting) {
+    console.log('Element is at least 50% visible!');
+    // Load image logic here...
+  }
+});
+```
+
+### Media Query Observation
+
+Reactively track media query matches (e.g., dark mode or viewport width).
+
+```ts
+import { observeMediaQuery$ } from '@tstdl/base/dom';
+
+// RxJS Observable
+observeMediaQuery$('(prefers-color-scheme: dark)').subscribe((isDark) => {
+  console.log('Dark mode is:', isDark ? 'Enabled' : 'Disabled');
+});
+
+// Or as a Signal
+import { observeMediaQuery } from '@tstdl/base/dom';
+const isMobile = observeMediaQuery('(max-width: 768px)');
+```
+
+### Touch Event Streams
+
+Normalize touch events (`start`, `move`, `end`, `cancel`) into a single observable stream. This is useful for building custom gestures.
+
+```ts
+import { observeTouch$ } from '@tstdl/base/dom';
+
+const canvas = document.querySelector('canvas')!;
+
+observeTouch$(canvas).subscribe((event) => {
+  if (event.start) {
+    console.log('Touch started at', event.start.touches[0].clientX);
+  }
+  if (event.move) {
+    // Handle drag
+  }
+  if (event.end) {
+    console.log('Touch ended');
+  }
+});
+```
+
+### Mutation & Performance Observation
+
+Observe DOM tree changes or performance metrics.
+
+```ts
+import { observeMutation$, observePerformance$ } from '@tstdl/base/dom';
+
+// Mutation Observer
+const list = document.querySelector('ul')!;
+observeMutation$(list, { childList: true }).subscribe((records) => {
+  console.log('List changed:', records);
+});
+
+// Performance Observer
+observePerformance$({ entryTypes: ['resource'] }).subscribe((list) => {
+  const entries = list.getEntries();
+  entries.forEach((entry) => console.log(`Resource loaded: ${entry.name}`));
+});
+```
+
+## 📚 API
+
+### File Utilities
+
+| Function                                                  | Description                                                                          |
+| :-------------------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `downloadFile(content: Blob \| File, fileName?: string)`  | Triggers a browser download for the provided content.                                |
+| `openFileSelectDialog(options?: FileSelectDialogOptions)` | Opens a file selection dialog and returns a Promise resolving to `File[]` or `null`. |
+
+### Reactive Observers (RxJS & Signals)
+
+| Function                                  | Return Type                                      | Description                                               |
+| :---------------------------------------- | :----------------------------------------------- | :-------------------------------------------------------- |
+| `observeIntersection$(element, options?)` | `Observable<IntersectionObserverEntry>`          | Observes element intersection changes.                    |
+| `observeIntersection(element, options?)`  | `Signal<IntersectionObserverEntry \| undefined>` | Signal version of intersection observer.                  |
+| `observeResize$(element, options?)`       | `Observable<ResizeObserverEntry>`                | Observes element resize events.                           |
+| `observeResize(element, options?)`        | `Signal<ResizeObserverEntry \| undefined>`       | Signal version of resize observer.                        |
+| `observeMediaQuery$(query)`               | `Observable<boolean>`                            | Observes media query match status.                        |
+| `observeMediaQuery(query)`                | `Signal<boolean>`                                | Signal version of media query observer.                   |
+| `observeMutation$(nodes, options?)`       | `Observable<MutationRecord[]>`                   | Observes DOM mutations.                                   |
+| `observePerformance$(inits?, options?)`   | `Observable<PerformanceObserverEntryListLike>`   | Observes performance entries.                             |
+| `observeTouch$(element, options?)`        | `Observable<TouchEvents>`                        | Observes touch events (`start`, `move`, `end`, `cancel`). |
+
+### Types
+
+| Type                        | Description                                                              |
+| :-------------------------- | :----------------------------------------------------------------------- |
+| `FileSelectDialogOptions`   | Options for file selection (`accept`, `multiple`, `capture`).            |
+| `TouchEvents`               | Object containing optional `start`, `move`, `end`, `cancel` TouchEvents. |
+| `ObserveMutationOptions`    | Extends `MutationObserverInit` with optional triggers.                   |
+| `ObservePerformanceOptions` | Options for performance observation triggers.                            |

package/enumerable/README.md

@@ -0,0 +1,259 @@
+# Enumerable
+
+A powerful, fluent, LINQ-inspired library for querying, transforming, and manipulating synchronous and asynchronous iterables in TypeScript. It unifies array processing, generators, and streams under a single, lazy-evaluation API.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Asynchronous Streams](#asynchronous-streams)
+  - [Parallel Processing](#parallel-processing)
+  - [RxJS Observables](#rxjs-observables)
+  - [Multiplexing Streams](#multiplexing-streams)
+  - [Event Loop Interruption](#event-loop-interruption)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Fluent Interface**: Chain methods like `.filter()`, `.map()`, and `.reduce()` for readable and expressive data pipelines.
+- **Lazy Evaluation**: Operations are deferred until results are materialized, optimizing performance and memory usage.
+- **Unified API**: Consistent methods for both synchronous (`Enumerable`) and asynchronous (`AsyncEnumerable`) data sources.
+- **Parallel Execution**: Built-in support for concurrent processing in asynchronous streams (`parallelMap`, `parallelFilter`, `parallelTap`) to speed up I/O-bound tasks.
+- **Rich Toolset**: Includes advanced operations like `group`, `distinct`, `batch`, `pairwise`, `throttle`, and `retry`.
+- **Interoperability**: Seamlessly convert between Arrays, Sets, Generators, Promises, and RxJS Observables.
+- **Event Loop Friendly**: Built-in methods to yield control back to the event loop during heavy processing (`interruptEvery`, `interruptPerSecond`).
+
+## Core Concepts
+
+### `Enumerable<T>`
+
+Wraps standard synchronous iterables (Arrays, Sets, Maps, Generators). It executes operations synchronously and lazily. No iteration happens until a terminal method (like `toArray`, `first`, or `reduce`) is called.
+
+### `AsyncEnumerable<T>`
+
+Wraps asynchronous iterables (`AsyncIterable`, `Promise<Iterable>`, `Observable`). It allows you to process streams of data over time. It supports **concurrency** control, allowing you to process multiple items in parallel while maintaining a simple fluent chain.
+
+## 🚀 Basic Usage
+
+### Synchronous Data Processing
+
+```typescript
+import { Enumerable } from '@tstdl/base/enumerable';
+
+const users = [
+  { id: 1, name: 'Alice', age: 30, active: true },
+  { id: 2, name: 'Bob', age: 25, active: false },
+  { id: 3, name: 'Charlie', age: 35, active: true },
+];
+
+const names = Enumerable.from(users)
+  .filter((u) => u.active)
+  .sort((a, b) => a.age - b.age)
+  .map((u) => u.name)
+  .toArray();
+
+console.log(names); // ['Alice', 'Charlie']
+```
+
+### Grouping Data
+
+Easily group data into Maps or Arrays.
+
+```typescript
+import { Enumerable } from '@tstdl/base/enumerable';
+
+const numbers = [1, 2, 3, 4, 5, 6];
+
+// Group by even/odd
+const grouped = Enumerable.from(numbers).groupToMap((n) => (n % 2 === 0 ? 'even' : 'odd'));
+
+console.log(grouped.get('even')); // [2, 4, 6]
+console.log(grouped.get('odd')); // [1, 3, 5]
+```
+
+## 🔧 Advanced Topics
+
+### Asynchronous Streams
+
+`AsyncEnumerable` works natively with async generators and APIs.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+async function* fetchPages() {
+  yield [1, 2, 3];
+  await new Promise((r) => setTimeout(r, 100));
+  yield [4, 5, 6];
+}
+
+const total = await AsyncEnumerable.from(fetchPages())
+  .mapMany((page) => page) // Flatten arrays
+  .filter((n) => n % 2 === 0)
+  .reduce((sum, n) => sum + n, 0);
+
+console.log(total); // 12 (2 + 4 + 6)
+```
+
+### Parallel Processing
+
+Process async tasks concurrently to improve throughput. This is ideal for batch API calls or file processing.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const ids = [1, 2, 3, 4, 5];
+
+const results = await AsyncEnumerable.from(ids)
+  .parallelMap(3, true, async (id) => {
+    // Simulate network request with concurrency of 3
+    // 'true' ensures output order matches input order
+    const data = await fetch(`https://api.example.com/items/${id}`);
+    return data.json();
+  })
+  .toArray();
+```
+
+### RxJS Observables
+
+Convert RxJS Observables directly into `AsyncEnumerable` to use LINQ-style operators on streams.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+import { interval } from 'rxjs';
+import { take } from 'rxjs/operators';
+
+const observable = interval(100).pipe(take(5));
+
+await AsyncEnumerable.fromObservable(observable)
+  .map((n) => n * 2)
+  .forEach((n) => console.log(n));
+// Output: 0, 2, 4, 6, 8
+```
+
+### Multiplexing Streams
+
+Split a single async source into multiple independent consumers. This is useful when you need to process the same stream in different ways simultaneously.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const source = AsyncEnumerable.fromRange(1, 5);
+
+// Create 2 independent branches from the source
+const [branchA, branchB] = source.multiplex(2);
+
+const taskA = branchA.filter((n) => n % 2 === 0).toArray();
+
+const taskB = branchB.map((n) => n * 10).toArray();
+
+const [evens, multiplied] = await Promise.all([taskA, taskB]);
+
+console.log(evens); // [2, 4]
+console.log(multiplied); // [10, 20, 30, 40, 50]
+```
+
+### Event Loop Interruption
+
+When processing large datasets asynchronously, you may want to prevent blocking the event loop for too long. `AsyncEnumerable` provides methods to automatically yield control back to the event loop.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const largeDataset = AsyncEnumerable.fromRange(1, 1_000_000);
+
+await largeDataset
+  .interruptEvery(1000) // Yield control every 1000 items
+  .forEach((item) => {
+    // Heavy processing
+  });
+
+await largeDataset
+  .interruptPerSecond(60) // Ensure the event loop is yielded at least 60 times per second
+  .forEach((item) => {
+    // Heavy processing
+  });
+```
+
+## 📚 API
+
+### Static Creation Methods
+
+| Class             | Method                  | Description                                                                    |
+| :---------------- | :---------------------- | :----------------------------------------------------------------------------- |
+| `Enumerable`      | `from(source)`          | Creates an `Enumerable` from an `Iterable`.                                    |
+| `Enumerable`      | `fromDeferred(factory)` | Creates an `Enumerable` that calls the factory function when iteration starts. |
+| `Enumerable`      | `fromRange(from, to)`   | Creates an `Enumerable` of numbers in a range (inclusive).                     |
+| `AsyncEnumerable` | `from(source)`          | Creates an `AsyncEnumerable` from an `AnyIterable` (sync or async).            |
+| `AsyncEnumerable` | `fromDeferred(factory)` | Creates an `AsyncEnumerable` from a factory returning an iterable or promise.  |
+| `AsyncEnumerable` | `fromObservable(obs)`   | Creates an `AsyncEnumerable` from an RxJS `Observable`.                        |
+| `AsyncEnumerable` | `fromRange(from, to)`   | Creates an `AsyncEnumerable` of numbers in a range.                            |
+
+### Common Methods (Sync & Async)
+
+These methods exist on both `Enumerable` and `AsyncEnumerable`. Async versions return `Promise` for terminal operations and `AsyncEnumerable` for transformations.
+
+| Category           | Method                    | Description                                                                              |
+| :----------------- | :------------------------ | :--------------------------------------------------------------------------------------- |
+| **Filtering**      | `filter(predicate)`       | Filters elements based on a predicate.                                                   |
+|                    | `filterNullOrUndefined()` | Removes `null` and `undefined` values.                                                   |
+|                    | `distinct(selector?)`     | Returns distinct elements (optionally by key).                                           |
+|                    | `take(count)`             | Takes the first `N` elements.                                                            |
+|                    | `skip(count)`             | Skips the first `N` elements.                                                            |
+|                    | `takeWhile(yieldLast, p)` | Takes elements while the predicate is true.                                              |
+|                    | `takeUntil(signal)`       | Takes elements until a `CancellationSignal` is triggered.                                |
+|                    | `while(predicate)`        | Iterates while the predicate is true.                                                    |
+| **Transformation** | `map(mapper)`             | Projects each element into a new form.                                                   |
+|                    | `mapMany(mapper)`         | Projects each element to an iterable and flattens the result.                            |
+|                    | `batch(size)`             | Groups elements into arrays of a specific size.                                          |
+|                    | `pairwise()`              | Emits the previous and current element as a tuple `[prev, curr]`.                        |
+|                    | `materialize()`           | Converts the sequence into a sequence of `Notification` objects (next, error, complete). |
+|                    | `metadata()`              | Wraps elements with metadata (index, isFirst, isLast).                                   |
+| **Set Operations** | `concat(...iterables)`    | Concatenates multiple iterables.                                                         |
+|                    | `difference(other, sel?)` | Returns elements present in source but not in other.                                     |
+|                    | `differenceMany(its, s?)` | Returns elements present in source but not in any of the others.                         |
+|                    | `defaultIfEmpty(default)` | Returns a default value if the sequence is empty.                                        |
+| **Aggregation**    | `reduce(reducer, init?)`  | Aggregates the sequence into a single value.                                             |
+|                    | `toArray()`               | Materializes the sequence into an array.                                                 |
+|                    | `toSet()`                 | Materializes the sequence into a Set.                                                    |
+|                    | `group(selector)`         | Groups elements into `[Key, T[]]` pairs.                                                 |
+|                    | `groupSingle(selector)`   | Groups elements into `[Key, T]` pairs (last wins).                                       |
+|                    | `groupToMap(selector)`    | Groups elements into a `Map<Key, T[]>`.                                                  |
+|                    | `groupToSingleMap(sel)`   | Groups elements into a `Map<Key, T>` (last wins).                                        |
+| **Inspection**     | `all(predicate)`          | Checks if all elements satisfy the predicate.                                            |
+|                    | `any(predicate)`          | Checks if any element satisfies the predicate.                                           |
+|                    | `includes(value)`         | Checks if the sequence contains a specific value.                                        |
+|                    | `first(predicate?)`       | Returns the first element (throws if empty).                                             |
+|                    | `firstOrDefault(def, p?)` | Returns the first element or a default value.                                            |
+|                    | `last(predicate?)`        | Returns the last element.                                                                |
+|                    | `lastOrDefault(def, p?)`  | Returns the last element or a default value.                                             |
+|                    | `single(predicate?)`      | Returns the only element (throws if not exactly one).                                    |
+|                    | `singleOrDefault(def, p)` | Returns the single element or a default value.                                           |
+| **Sorting**        | `sort(comparator?)`       | Sorts the sequence lazily.                                                               |
+|                    | `sortToArray(comparator?)`| Sorts the sequence and returns an array immediately.                                     |
+| **Side Effects**   | `tap(action)`             | Executes an action for each element without modifying the stream.                        |
+|                    | `forEach(action)`         | Iterates over the sequence (terminal operation).                                         |
+|                    | `drain()`                 | Consumes the entire sequence and discards results.                                       |
+| **Utility**        | `assert(predicate)`       | Verifies that each element satisfies the predicate, throws otherwise.                    |
+|                    | `cast<TNew>()`            | Casts the sequence to a new type (unsafe).                                               |
+|                    | `forceCast<TNew>()`       | Force casts the sequence to a new type (unsafe).                                         |
+|                    | `toAsync()`               | Converts the sequence to an `AsyncEnumerable`.                                           |
+|                    | `toIterator()`            | Returns the underlying iterator.                                                         |
+
+### Async-Only Methods (`AsyncEnumerable`)
+
+| Method                                              | Description                                                                              |
+| :-------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| `parallelMap(concurrency, keepOrder, mapper)`       | Maps elements concurrently.                                                              |
+| `parallelFilter(concurrency, keepOrder, predicate)` | Filters elements concurrently.                                                           |
+| `parallelTap(concurrency, keepOrder, action)`       | Taps elements concurrently.                                                              |
+| `parallelForEach(concurrency, action)`              | Iterates elements concurrently.                                                          |
+| `parallelGroup(concurrency, selector)`              | Groups elements concurrently (returns `Promise<Map>`).                                   |
+| `interruptEvery(value)`                             | Yields control to the event loop every `N` elements.                                     |
+| `interruptPerSecond(value)`                         | Yields control to the event loop `N` times per second.                                   |
+| `throttle(delayOrFunction)`                         | Limits the rate of emission.                                                             |
+| `retry(throwOnFalse, predicate)`                    | Retries the source sequence on error based on a predicate.                               |
+| `multiplex(count, buffer?)`                         | Splits the stream into multiple independent streams.                                     |
+| `buffer(size)`                                      | Buffers elements and emits them as soon as they are available (flow control).            |
+| `toSync()`                                          | Resolves the entire async sequence into a synchronous `Enumerable` (returns `Promise`).  |

package/enumeration/README.md

@@ -0,0 +1,121 @@
+# @tstdl/base/enumeration
+
+A lightweight utility for creating and registering named, type-safe enumerations in TypeScript using plain objects. It provides runtime name introspection capabilities often missing from native TypeScript enums, making it ideal for framework development, serialization, and logging.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Defining a String Enum](#defining-a-string-enum)
+  - [Defining a Numeric Enum](#defining-a-numeric-enum)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Retrieving an Enum's Name](#retrieving-an-enums-name)
+  - [Working with Enum Values (Utilities)](#working-with-enum-values-utilities)
+- [💡 Best Practices](#-best-practices)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Named Enums:** Associate a string name with an enum-like object, retrievable at runtime.
+- **Type-Safe:** Leverages TypeScript's `const` generics to create precise, type-safe union types from plain objects.
+- **Mixed Types:** Supports both string and numeric values within the same enumeration structure.
+- **Lightweight:** A minimal implementation with zero external dependencies.
+- **Memory-Efficient:** Uses a `WeakMap` to store enum names, allowing for automatic garbage collection if the enum object is no longer referenced.
+
+## Core Concepts
+
+Native TypeScript `enum`s have limitations, especially for framework development. Their declared name is lost at compile time (transpiled away), and numeric enums have complex runtime behavior (reverse mappings). This makes it difficult for systems like ORMs, serializers, or validators to identify an enum type by a consistent name at runtime.
+
+This module provides a simple and robust alternative. The `defineEnum` function allows you to use a standard JavaScript object as an enum. It registers the object with a unique string name in a global, memory-safe registry (`WeakMap`). This name can be retrieved at runtime using `getEnumName`, enabling powerful metaprogramming scenarios where you need to reference the enum's "type" by name.
+
+## 🚀 Basic Usage
+
+### Defining a String Enum
+
+Use the `defineEnum` function to create your enumeration object and register its name. The `EnumType` utility creates a corresponding TypeScript type for the enum values.
+
+```typescript
+import { defineEnum, type EnumType } from '@tstdl/base/enumeration';
+
+export const OrderStatus = defineEnum('OrderStatus', {
+  Pending: 'pending',
+  Processing: 'processing',
+  Shipped: 'shipped',
+  Delivered: 'delivered',
+});
+
+export type OrderStatus = EnumType<typeof OrderStatus>;
+
+const status: OrderStatus = OrderStatus.Shipped; // Type is "pending" | "processing" | "shipped" | "delivered"
+```
+
+### Defining a Numeric Enum
+
+The utility works equally well with numeric values.
+
+```typescript
+import { defineEnum, type EnumType } from '@tstdl/base/enumeration';
+
+export const Priority = defineEnum('Priority', {
+  Low: 0,
+  Medium: 1,
+  High: 2,
+  Urgent: 3,
+});
+
+export type Priority = EnumType<typeof Priority>;
+
+const taskPriority: Priority = Priority.High; // Type is 0 | 1 | 2 | 3
+```
+
+## 🔧 Advanced Topics
+
+### Retrieving an Enum's Name
+
+You can retrieve the registered name of an enum object. This is particularly useful for logging, error messages, or when building libraries that need to serialize the type name of an enum.
+
+```typescript
+import { defineEnum, getEnumName, tryGetEnumName } from '@tstdl/base/enumeration';
+
+const UserRole = defineEnum('UserRole', {
+  Admin: 'admin',
+  Editor: 'editor',
+});
+
+const name = getEnumName(UserRole); // "UserRole"
+const safeName = tryGetEnumName({}); // undefined
+```
+
+### Working with Enum Values (Utilities)
+
+For practical operations like listing all values or finding a key by value, use the utility functions provided in `#/utils/enum.js`.
+
+```typescript
+import { enumValues, enumKeys, enumValueName } from '@tstdl/base/utils/enum';
+import { OrderStatus } from './order-status.js';
+
+const allStatuses = enumValues(OrderStatus); // ["pending", "processing", ...]
+const allKeys = enumKeys(OrderStatus); // ["Pending", "Processing", ...]
+const name = enumValueName(OrderStatus, 'pending'); // "Pending"
+```
+
+## 💡 Best Practices
+
+1.  **Always use `defineEnum`:** Ensure every enum-like object in the codebase is wrapped in `defineEnum` to maintain consistency and support runtime introspection.
+2.  **Export both Value and Type:** Export the constant object and a type alias with the same name for a better developer experience.
+    ```typescript
+    export const MyEnum = defineEnum('MyEnum', { ... });
+    export type MyEnum = EnumType<typeof MyEnum>;
+    ```
+3.  **Unique Names:** Ensure the string name passed to `defineEnum` is unique across the application, typically matching the variable name.
+4.  **Avoid Native Enums:** Prefer this pattern over native TypeScript `enum` to avoid unexpected runtime behavior and missing metadata.
+
+## 📚 API
+
+| Member             | Signature                                                                                | Description                                                                                                                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineEnum()`     | `function defineEnum<const T extends EnumerationObject>(name: string, enumObject: T): T` | Registers an `enumObject` with a given `name` and returns it. The `<const T>` generic ensures that the returned type is inferred as a set of literal types, providing strong type safety. |
+| `getEnumName()`    | `function getEnumName(enumeration: EnumerationObject): string`                           | Retrieves the registered name for an enum object. Throws an `Error` if the enum is not registered.                                                                                        |
+| `tryGetEnumName()` | `function tryGetEnumName(enumeration: EnumerationObject): string \| undefined`           | Safely retrieves the registered name for an enum object. Returns `undefined` if not registered.                                                                                           |
+| `EnumType`         | `type EnumType<T extends EnumerationObject> = T[keyof T]`                                | A utility type that creates a union type from an enum-like object's values.                                                                                                               |