@tstdl/base 0.93.139 → 0.93.141

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

package/errors/README.md

@@ -0,0 +1,267 @@
+# Errors
+
+A comprehensive collection of custom, robust, and extensible error classes for TypeScript applications. It provides a standardized hierarchy for common failure scenarios, performance optimizations, and built-in localization support.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [The CustomError Base](#the-customerror-base)
+  - [Standardized Error Types](#standardized-error-types)
+  - [Localization](#localization)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Creating Custom Errors](#creating-custom-errors)
+  - [Attaching Details to Errors](#attaching-details-to-errors)
+  - [Aggregating Multiple Errors](#aggregating-multiple-errors)
+  - [Formatting and Serialization](#formatting-and-serialization)
+  - [Performance Optimization (Fast Mode)](#performance-optimization-fast-mode)
+  - [Unwrapping Errors](#unwrapping-errors)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Extensible Base Class:** `CustomError` simplifies creating domain-specific errors with support for causes and stack trace management.
+- **Standard Library:** Includes a rich set of pre-defined errors for HTTP status codes (400, 401, 403, 404, etc.) and common application failures.
+- **Type Safety:** Designed for use with `instanceof` checks to allow precise error handling logic.
+- **Contextual Data:** `DetailsError` allows attaching arbitrary structured data to an error.
+- **Error Aggregation:** `MultiError` groups multiple errors into a single throwable object.
+- **Performance Mode:** Optional `fast` mode skips stack trace generation for high-throughput scenarios.
+- **Localization:** Built-in English and German localization maps for user-facing error messages.
+
+## Core Concepts
+
+### The CustomError Base
+
+All errors in this module inherit from `CustomError`. This abstract class extends the native JavaScript `Error` and adds:
+
+- **Static `errorName`**: A reliable identifier for the error type, safe against code minification.
+- **Options Object**: A constructor argument to set the message, cause, stack, and performance flags.
+
+### Standardized Error Types
+
+The module provides specific classes for common scenarios, such as:
+
+- **Authentication/Authorization**: `UnauthorizedError`, `ForbiddenError`, `InvalidCredentialsError`, `InvalidTokenError`.
+- **Request Handling**: `BadRequestError`, `NotFoundError`, `MethodNotAllowedError`, `UnsupportedMediaTypeError`, `MaxBytesExceededError`.
+- **System State**: `NotImplementedError`, `NotSupportedError`, `TimeoutError`, `AssertionError`.
+
+### Localization
+
+The module exports `englishTstdlErrorsLocalization` and `germanTstdlErrorsLocalization`. These objects map error classes to user-friendly headers and messages, making it easier to display errors in a UI without hardcoding strings.
+
+## 🚀 Basic Usage
+
+The most common use case is throwing standard errors to interrupt control flow when a specific condition is not met.
+
+```ts
+import { NotFoundError, ForbiddenError } from '@tstdl/base/errors';
+
+interface User {
+  id: string;
+  isAdmin: boolean;
+}
+
+function getUser(id: string, currentUser: User): User {
+  // Simulate a database lookup
+  const user = database.find(id);
+
+  if (!user) {
+    throw new NotFoundError(`User with ID "${id}" was not found.`);
+  }
+
+  if (!currentUser.isAdmin && currentUser.id !== user.id) {
+    throw new ForbiddenError('You do not have permission to view this user.');
+  }
+
+  return user;
+}
+
+// Mock database for the example
+const database = {
+  find: (id: string) => (id === '123' ? { id: '123', isAdmin: false } : null),
+};
+```
+
+Handling errors using `instanceof` ensures you only catch and process specific types.
+
+```ts
+import { NotFoundError, ForbiddenError } from '@tstdl/base/errors';
+
+try {
+  getUser('999', { id: '123', isAdmin: false });
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('Resource missing:', error.message);
+  } else if (error instanceof ForbiddenError) {
+    console.error('Access denied:', error.message);
+  } else {
+    console.error('Unexpected error:', error);
+    throw error; // Re-throw unknown errors
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Creating Custom Errors
+
+Extend `CustomError` to define domain-specific errors. Define a static `errorName` to ensure the error can be reliably identified even if class names are mangled during build processes.
+
+```ts
+import { CustomError } from '@tstdl/base/errors';
+
+export class InsufficientFundsError extends CustomError {
+  static readonly errorName = 'InsufficientFundsError';
+
+  constructor(accountId: string, required: number, available: number) {
+    super({
+      message: `Account ${accountId} has insufficient funds. Required: ${required}, Available: ${available}.`,
+    });
+  }
+}
+
+// Usage
+throw new InsufficientFundsError('ACC-123', 100.0, 50.0);
+```
+
+### Attaching Details to Errors
+
+Use `DetailsError` when you need to pass structured data along with the error message. This is useful for validation errors or passing context to an error handler.
+
+```ts
+import { DetailsError } from '@tstdl/base/errors';
+
+type ValidationFailure = {
+  field: string;
+  reason: string;
+};
+
+function validateProfile(profile: any): void {
+  const failures: ValidationFailure[] = [];
+
+  if (!profile.username) {
+    failures.push({ field: 'username', reason: 'Required' });
+  }
+
+  if (failures.length > 0) {
+    throw new DetailsError('Validation failed', failures);
+  }
+}
+
+try {
+  validateProfile({});
+} catch (error) {
+  if (error instanceof DetailsError) {
+    console.log('Validation details:', error.details);
+  }
+}
+```
+
+### Aggregating Multiple Errors
+
+`MultiError` is useful when an operation performs multiple independent tasks (like processing a batch of files) and you want to report all failures at the end.
+
+```ts
+import { MultiError } from '@tstdl/base/errors';
+
+function processItems(items: string[]): void {
+  const errors: Error[] = [];
+
+  for (const item of items) {
+    try {
+      // potentially failing operation
+      if (item === 'fail') throw new Error('Failed item');
+    } catch (error) {
+      if (error instanceof Error) {
+        errors.push(error);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new MultiError(errors, `Processed items with ${errors.length} errors.`);
+  }
+}
+```
+
+### Formatting and Serialization
+
+When logging errors or sending them over the wire (e.g., in a REST API response), you often need a structured or stringified representation. The `serializeError` and `formatError` functions handle this, including support for nested causes and `MultiError` aggregation.
+
+```ts
+import { formatError, serializeError, ForbiddenError } from '@tstdl/base/errors';
+
+const error = new ForbiddenError('Access Denied', { cause: new Error('Permission bit 0 not set') });
+
+// Get a structured JSON-cloneable object
+const serialized = serializeError(error);
+
+// Get a formatted string with indentation and causes
+const formatted = formatError(error, { includeStack: true });
+console.log(formatted);
+/*
+ForbiddenError: Access Denied
+Caused by:
+  Error: Permission bit 0 not set
+    at Object.<anonymous> ...
+*/
+```
+
+### Performance Optimization (Fast Mode)
+
+Generating a stack trace is an expensive operation in JavaScript. If you are using exceptions for control flow in a high-performance loop (e.g., a parser) and do not need the stack trace, you can use the `fast: true` option.
+
+```ts
+import { CustomError } from '@tstdl/base/errors';
+
+class ParserError extends CustomError {
+  static readonly errorName = 'ParserError';
+
+  constructor(message: string) {
+    // fast: true skips super() call to Error, avoiding stack trace generation
+    super({ message, fast: true });
+  }
+}
+```
+
+### Unwrapping Errors
+
+Sometimes errors are wrapped in other objects or generic error containers. `unwrapError` helps extract the original underlying error.
+
+```ts
+import { unwrapError } from '@tstdl/base/errors';
+
+const originalError = new Error('Database connection failed');
+const wrappedError = { reason: originalError };
+
+const error = unwrapError(wrappedError);
+console.log(error.message); // "Database connection failed"
+```
+
+## 📚 API
+
+| Class / Function                 | Description                                                                                                     |
+| :------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| `CustomError`                    | Abstract base class for all errors. Accepts `CustomErrorOptions` (`name`, `message`, `cause`, `stack`, `fast`). |
+| `ApiError`                       | Wraps an `ErrorResponse` from an API, exposing the `response` and `details`.                                    |
+| `AssertionError`                 | Indicates a failed assertion check.                                                                             |
+| `BadRequestError`                | Indicates a client-side error (HTTP 400). Default message: "bad request".                                       |
+| `DetailsError<T>`                | An error that carries an additional `details` payload of type `T`.                                              |
+| `ForbiddenError`                 | Indicates the client is authenticated but lacks permissions (HTTP 403). Default message: "forbidden".           |
+| `InvalidCredentialsError`        | Indicates authentication failed due to bad credentials. Default message: "Invalid credentials.".                |
+| `InvalidTokenError`              | Indicates an authentication token is invalid or expired. Default message: "invalid token".                      |
+| `MaxBytesExceededError`          | Indicates a size limit was exceeded. Includes static `fromBytes(bytes)` factory.                                |
+| `MethodNotAllowedError`          | Indicates the HTTP method is not supported for the resource (HTTP 405).                                         |
+| `MultiError`                     | Aggregates an array of `Error` objects into a single error.                                                     |
+| `NotFoundError`                  | Indicates a resource could not be found (HTTP 404). Default message: "not found".                               |
+| `NotImplementedError`            | Indicates functionality is not yet implemented (HTTP 501).                                                      |
+| `NotSupportedError`              | Indicates an operation or value is not supported. Includes static `fromEnum(...)` factory.                      |
+| `TimeoutError`                   | Indicates an operation exceeded its time limit.                                                                 |
+| `UnauthorizedError`              | Indicates authentication is required (HTTP 401). Default message: "Unauthorized".                               |
+| `UnsupportedMediaTypeError`      | Indicates the payload format is not supported (HTTP 415).                                                       |
+| `unwrapError(error)`             | Utility function to extract the underlying error from a wrapper object (checks `rejection`, `reason`, `error`). |
+| `serializeError(error, options)`  | Serializes an error into a structured JSON-cloneable `SerializedError` object.                                 |
+| `formatError(error, options)`     | Formats an error into a human-readable string, including causes and sub-errors.                                 |
+| `englishTstdlErrorsLocalization` | Localization object containing English headers and messages for standard errors.                                |
+| `germanTstdlErrorsLocalization`  | Localization object containing German headers and messages for standard errors.                                 |

package/examples/document-management/main.d.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 import '../../polyfills.js';
 import { DocumentManagementAuthorizationService, type DocumentCollection, type DocumentCollectionMetadata } from '../../document-management/index.js';
 import { DocumentManagementAncillaryService } from '../../document-management/server/index.js';

package/examples/document-management/main.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -10,22 +11,23 @@ import { MockApiRequestTokenProvider } from '../../api/server/api-request-token.
 import { configureApiServer } from '../../api/server/module.js';
 import { Application } from '../../application/application.js';
 import { provideInitializer, provideModule, provideSignalHandler } from '../../application/index.js';
-import { configurePostgresCircuitBreaker, migratePostgresCircuitBreaker } from '../../circuit-breaker/postgres/module.js';
+import { configureAudit } from '../../audit/module.js';
+import { configurePostgresCircuitBreaker } from '../../circuit-breaker/postgres/module.js';
 import { DocumentManagementAuthorizationService } from '../../document-management/index.js';
 import { configureDocumentManagement } from '../../document-management/server/configure.js';
 import { DocumentCategoryTypeService, DocumentCollectionService, DocumentManagementAncillaryService, DocumentManagementApiController, DocumentRequestService } from '../../document-management/server/index.js';
-import { migrateDocumentManagementSchema } from '../../document-management/server/module.js';
 import { DocumentManagementService } from '../../document-management/server/services/document-management.service.js';
 import { configureNodeHttpServer } from '../../http/server/node/module.js';
-import { Injector, Singleton } from '../../injector/index.js';
-import { inject, injectManyAsync, runInInjectionContext } from '../../injector/inject.js';
+import { Singleton } from '../../injector/index.js';
+import { injectManyAsync } from '../../injector/inject.js';
 import { PrettyPrintLogFormatter, provideConsoleLogTransport } from '../../logger/index.js';
 import { configureLocalMessageBus } from '../../message-bus/index.js';
 import { WebServerModule } from '../../module/index.js';
 import { configureS3ObjectStorage } from '../../object-storage/s3/index.js';
-import { configureOrm } from '../../orm/server/index.js';
+import { configureOrm, provideDatabaseMigrator } from '../../orm/server/index.js';
+import { configurePostgresRateLimiter } from '../../rate-limit/postgres/module.js';
 import { configureDefaultSignalsImplementation } from '../../signals/implementation/configure.js';
-import { configurePostgresTaskQueue, migratePostgresTaskQueueSchema } from '../../task-queue/postgres/index.js';
+import { configurePostgresTaskQueue } from '../../task-queue/postgres/index.js';
 import { boolean, positiveInteger, string } from '../../utils/config-parser.js';
 import { ExampleAiProviderService } from './ai-provider.js';
 import { TstdlCategoryParents, TstdlDocumentCategoryLabels, TstdlDocumentPropertyConfiguration, TstdlDocumentTypeCategories, TstdlDocumentTypeLabels, TstdlDocumentTypeProperties } from './categories-and-types.js';
@@ -84,11 +86,13 @@ AllowAllDocumentManagementAuthorizationService = __decorate([
     Singleton()
 ], AllowAllDocumentManagementAuthorizationService);
 export { AllowAllDocumentManagementAuthorizationService };
-async function bootstrap() {
-    const injector = inject(Injector);
+function bootstrap() {
+    configureAudit();
     configureNodeHttpServer();
     configurePostgresTaskQueue();
     configurePostgresCircuitBreaker();
+    configurePostgresTaskQueue();
+    configurePostgresRateLimiter();
     configureLocalMessageBus();
     configureDefaultSignalsImplementation();
     configureGenkit({
@@ -119,6 +123,7 @@ async function bootstrap() {
         bucketPerModule: config.s3.bucketPerModule,
         accessKey: config.s3.accessKey,
         secretKey: config.s3.secretKey,
+        forcePathStyle: true,
     });
     configureApiServer({
         controllers: [DocumentManagementApiController],
@@ -139,9 +144,6 @@ async function bootstrap() {
             location: config.ai.vertex.location,
         },
     });
-    await runInInjectionContext(injector, migrateDocumentManagementSchema);
-    await runInInjectionContext(injector, migratePostgresCircuitBreaker);
-    await runInInjectionContext(injector, migratePostgresTaskQueueSchema);
 }
 async function main() {
     const tenantId = '00000000-0000-0000-0000-000000000000';
@@ -171,4 +173,5 @@ Application.run('DocumentManagementTest', [
     provideModule(main, WebServerModule),
     provideSignalHandler(),
     provideConsoleLogTransport(PrettyPrintLogFormatter),
+    provideDatabaseMigrator(),
 ]);

package/file/README.md

@@ -0,0 +1,191 @@
+# File Module
+
+A utility module for robust MIME type detection and server-side temporary file management. It provides tools to identify file types from various sources and a safe, RAII-style wrapper for handling temporary files in Node.js.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Detecting MIME Types](#detecting-mime-types)
+  - [Getting Extensions](#getting-extensions)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Managing Temporary Files](#managing-temporary-files)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Robust MIME Detection**: Identify file types by checking magic numbers (binary signatures) rather than just file extensions.
+- **Versatile Input**: Supports detection from file paths, `Uint8Array` buffers, and `ReadableStream`s.
+- **Extension Lookup**: Retrieve valid file extensions for a specific MIME type.
+- **Automatic Cleanup**: Server-side `TemporaryFile` class implements `AsyncDisposable` for automatic file deletion when the scope exits.
+- **Stream Support**: seamless integration with Node.js and Web Streams for writing to and reading from temporary files.
+
+## Core Concepts
+
+### MIME Type Detection
+
+The module uses the `file-type` library under the hood to inspect the binary signature of a file. This is more secure and accurate than relying on filenames. It supports a wide range of formats including images, video, audio, and archives.
+
+### Temporary File Management (Server)
+
+When processing file uploads or generating reports, you often need to store data on disk temporarily. The `TemporaryFile` class wraps Node.js filesystem operations. It generates a unique path in the OS's temporary directory and ensures the file is deleted when you are done with it, leveraging TypeScript's `using` keyword (Explicit Resource Management).
+
+## 🚀 Basic Usage
+
+### Detecting MIME Types
+
+You can detect the MIME type of a file using a buffer or a stream.
+
+```typescript
+import { getMimeType } from '@tstdl/base/file';
+import { readFile } from 'node:fs/promises';
+
+async function checkFiles() {
+  // 1. From a Uint8Array / Buffer
+  const buffer = await readFile('/path/to/document.pdf');
+  const mimeFromBuffer = await getMimeType(buffer);
+  console.log(mimeFromBuffer); // 'application/pdf'
+
+  // 2. With a fallback if detection fails
+  const mimeWithFallback = await getMimeType(buffer, 'application/octet-stream');
+  console.log(mimeWithFallback);
+}
+```
+
+To detect MIME types from a file path (Node.js only), use the server-specific module:
+
+```typescript
+import { getMimeTypeFromFile } from '@tstdl/base/file/server';
+
+async function checkPath() {
+  const mimeFromPath = await getMimeTypeFromFile('/path/to/image.png');
+  console.log(mimeFromPath); // 'image/png'
+}
+```
+
+### Getting Extensions
+
+Retrieve the list of known extensions for a given MIME type.
+
+```typescript
+import { getMimeTypeExtensions } from '@tstdl/base/file';
+
+const extensions = getMimeTypeExtensions('image/jpeg');
+console.log(extensions); // ['jpeg', 'jpg', 'jpe']
+
+const pdfExt = getMimeTypeExtensions('application/pdf');
+console.log(pdfExt); // ['pdf']
+```
+
+## 🔧 Advanced Topics
+
+### Managing Temporary Files
+
+The `TemporaryFile` class is located in the `server` submodule. It is designed to be used with the `await using` syntax to guarantee cleanup.
+
+> **Note:** This feature requires a Node.js environment.
+
+#### Basic Usage
+
+The most common way to create a temporary file is from a stream, buffer, or string.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function processUpload(uploadStream: ReadableStream<Uint8Array>) {
+  // Create a temp file from a stream. The file is created in os.tmpdir() with a random UUID name.
+  // Optional: pass an extension as the second argument.
+  await using tempFile = await TemporaryFile.from(uploadStream, '.png');
+
+  console.log(`Processing file at: ${tempFile.path}`);
+  console.log(`File size: ${await tempFile.size()} bytes`);
+
+  // Read content back if needed
+  const content = await tempFile.readText();
+
+  // Perform operations (e.g., virus scan, image processing, parsing)
+  await performHeavyProcessing(tempFile.path);
+} // <--- tempFile.delete() is automatically called here!
+```
+
+#### Manual Control and Extensions
+
+You can create an empty temporary file and specify an extension.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function generateReport() {
+  await using tempFile = TemporaryFile.create('.pdf');
+
+  await tempFile.write('Report Content');
+  // ... do something with tempFile.path
+}
+```
+
+#### Persistent Files
+
+If you want to keep the file even after the scope ends (e.g., if you successfully moved it to a final destination), use `keep()` or `moveTo()`.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function savePermanent(stream: ReadableStream<Uint8Array>, destination: string) {
+  await using tempFile = await TemporaryFile.from(stream);
+
+  // ... validate file ...
+
+  // Move the file and mark it to be kept (not deleted on disposal)
+  await tempFile.moveTo(destination, true);
+}
+```
+
+#### Adopting Existing Files
+
+You can wrap an existing file in `TemporaryFile` to ensure it gets deleted when done.
+
+```typescript
+import { TemporaryFile } from '@tstdl/base/file/server';
+
+async function processExisting(path: string) {
+  await using tempFile = TemporaryFile.adopt(path);
+  // path will be deleted at the end of the scope
+}
+```
+
+## 📚 API
+
+### `@tstdl/base/file`
+
+| Export                  | Type     | Description                                                                                                           |
+| :---------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `getMimeType`           | Function | Async function to detect MIME type from `Uint8Array` or `ReadableStream`. Accepts an optional fallback.               |
+| `getMimeTypeExtensions` | Function | Returns an array of file extensions associated with a MIME type string.                                               |
+| `mimeTypes`             | Object   | A dictionary mapping MIME types to arrays of file extensions.                                                         |
+| `mimeTypesMap`          | Map      | A `Map` version of the `mimeTypes` object for efficient lookup.                                                       |
+
+### `@tstdl/base/file/server`
+
+| Export                 | Type     | Description                                                   |
+| :--------------------- | :------- | :------------------------------------------------------------ |
+| `getMimeTypeFromFile`  | Function | Async function to detect MIME type from a string file path (Node.js only). |
+| `TemporaryFile`        | Class    | A wrapper for temporary files implementing `AsyncDisposable`. |
+
+#### `TemporaryFile` Class
+
+| Method/Property           | Description                                                                                                  |
+| :------------------------ | :----------------------------------------------------------------------------------------------------------- |
+| `path`                    | Getter for the absolute file path.                                                                                             |
+| `static create(ext?)`     | Creates a new empty `TemporaryFile` instance with an optional extension.                                                       |
+| `static adopt(path)`      | Creates a `TemporaryFile` instance wrapping an existing file path.                                                            |
+| `static from(content, ext?)` | Creates a `TemporaryFile` and writes the provided content (string, Uint8Array, or Stream) to it, with an optional extension. |
+| `read()`                  | Reads the file content as a `Uint8Array`.                                                                                     |
+| `readText()`              | Reads the file content as a UTF-8 string.                                                                                     |
+| `readStream()`            | Returns a `ReadableStream<Uint8Array>` of the file content.                                                                   |
+| `write(content)`          | Overwrites the file with the provided content.                                                                                |
+| `moveTo(path, keep?)`     | Moves the file to a new location. If `keep` is true, it won't be deleted on disposal.                                         |
+| `keep()`                  | Prevents the file from being deleted when the object is disposed.                                                             |
+| `delete()`                | Manually deletes the file.                                                                                                    |
+| `size()`                  | Returns the size of the file in bytes.                                                                                        |
+| `[Symbol.asyncDispose]()` | Automatically calls `delete()` when used with `await using`, unless `keep()` was called.                                     |