@tstdl/base 0.93.139 → 0.93.141

package/testing/integration-setup.js

@@ -1,30 +1,31 @@
 import { sql } from 'drizzle-orm';
 import { configureApiServer } from '../api/server/index.js';
-import { configureAudit, migrateAuditSchema } from '../audit/index.js';
+import { configureAudit } from '../audit/index.js';
 import { AuthenticationApiClient } from '../authentication/client/api.client.js';
 import { configureAuthenticationClient } from '../authentication/client/index.js';
-import { AuthenticationApiController, configureAuthenticationServer, migrateAuthenticationSchema } from '../authentication/server/index.js';
-import { configurePostgresCircuitBreaker, migratePostgresCircuitBreaker } from '../circuit-breaker/postgres/module.js';
-import { configureDocumentManagement, migrateDocumentManagementSchema } from '../document-management/server/index.js';
+import { AuthenticationApiController, configureAuthenticationServer } from '../authentication/server/index.js';
+import { configurePostgresCircuitBreaker } from '../circuit-breaker/postgres/module.js';
+import { configureDocumentManagement } from '../document-management/server/index.js';
 import { configureUndiciHttpClientAdapter } from '../http/client/adapters/undici.adapter.js';
 import { configureHttpClient } from '../http/client/index.js';
 import { HttpServer } from '../http/server/index.js';
 import { configureNodeHttpServer } from '../http/server/node/module.js';
 import { Injector, runInInjectionContext } from '../injector/index.js';
-import { configurePostgresKeyValueStore, migratePostgresKeyValueStoreSchema } from '../key-value-store/postgres/module.js';
-import { configurePostgresLock, migratePostgresLockSchema } from '../lock/postgres/module.js';
+import { configurePostgresKeyValueStore } from '../key-value-store/postgres/module.js';
+import { configurePostgresLock } from '../lock/postgres/module.js';
 import { ConsoleLogTransport, DEFAULT_LOG_LEVEL, LogFormatter, LogLevel, LogManager, LogTransport, PrettyPrintLogFormatter } from '../logger/index.js';
 import { configureLocalMessageBus } from '../message-bus/index.js';
 import { configureWebServerModule, WebServerModule } from '../module/modules/web-server.module.js';
-import { configureNotification, migrateNotificationSchema } from '../notification/server/index.js';
+import { configureNotification } from '../notification/server/index.js';
 import { configureS3ObjectStorage } from '../object-storage/s3/index.js';
-import { configureOrm, Database } from '../orm/server/index.js';
-import { configurePostgresRateLimiter, migratePostgresRateLimiterSchema } from '../rate-limit/postgres/module.js';
+import { configureOrm, Database, runDatabaseMigrations } from '../orm/server/index.js';
+import { getEntitySchema, getEntityTableName } from '../orm/utils.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 * as configParser from '../utils/config-parser.js';
 import { objectEntries } from '../utils/object/object.js';
-import { isDefined, isNotNull } from '../utils/type-guards.js';
+import { assertDefinedPass, isDefined, isNotNull, isString } from '../utils/type-guards.js';
 /**
  * Standard setup for integration tests.
  */
@@ -51,6 +52,8 @@ export async function setupIntegrationTest(options = {}) {
         ...options.dbConfig,
     };
     // 4. Configure ORM
+    // We disable autoMigrate here because APPLICATION_INITIALIZER is not used in integration tests
+    // We manually run migrations via runDatabaseMigrations below
     configureOrm({
         repositoryConfig: { schema: options.orm?.schema ?? 'test' },
         connection: dbConfig,
@@ -66,35 +69,29 @@ export async function setupIntegrationTest(options = {}) {
             await database.execute(sql `CREATE SCHEMA IF NOT EXISTS ${sql.identifier(options.orm.schema)}`);
         }
         // 7. Optional Modules
-        if (options.modules?.messageBus ?? options.modules?.taskQueue ?? options.modules?.authentication ?? options.modules?.test ?? options.modules?.notification) {
+        if (options.modules?.messageBus ?? options.modules?.taskQueue ?? options.modules?.authentication ?? options.modules?.notification) {
             configureLocalMessageBus({ injector });
         }
         if (options.modules?.taskQueue) {
             configurePostgresTaskQueue({ injector });
-            await runInInjectionContext(injector, migratePostgresTaskQueueSchema);
         }
         if (options.modules?.circuitBreaker ?? options.modules?.taskQueue) {
             configurePostgresCircuitBreaker({ injector });
-            await runInInjectionContext(injector, migratePostgresCircuitBreaker);
         }
         if (options.modules?.rateLimiter ?? options.modules?.taskQueue) {
             configurePostgresRateLimiter({ injector });
-            await runInInjectionContext(injector, migratePostgresRateLimiterSchema);
         }
         if (options.modules?.keyValueStore ?? options.modules?.authentication) {
             configurePostgresKeyValueStore({ injector });
-            await runInInjectionContext(injector, migratePostgresKeyValueStoreSchema);
         }
         if (options.modules?.lock ?? options.modules?.authentication) {
             configurePostgresLock({ injector });
-            await runInInjectionContext(injector, migratePostgresLockSchema);
         }
-        if (options.modules?.signals ?? options.modules?.authentication ?? options.modules?.test ?? options.modules?.notification) {
+        if (options.modules?.signals ?? options.modules?.authentication ?? options.modules?.notification) {
             configureDefaultSignalsImplementation();
         }
         if (options.modules?.audit ?? options.modules?.authentication) {
             configureAudit({ injector });
-            await runInInjectionContext(injector, migrateAuditSchema);
         }
         if (options.modules?.authentication) {
             configureAuthenticationServer({
@@ -106,11 +103,9 @@ export async function setupIntegrationTest(options = {}) {
                 authenticationAncillaryService: options.authenticationAncillaryService,
                 injector,
             });
-            await runInInjectionContext(injector, migrateAuthenticationSchema);
         }
         if (options.modules?.notification) {
             configureNotification({ injector });
-            await runInInjectionContext(injector, migrateNotificationSchema);
         }
         if (options.modules?.documentManagement) {
             configureDocumentManagement({
@@ -122,8 +117,8 @@ export async function setupIntegrationTest(options = {}) {
                 skipAi: true,
                 injector,
             });
-            await runInInjectionContext(injector, migrateDocumentManagementSchema);
         }
+        await runInInjectionContext(injector, runDatabaseMigrations);
         if (options.modules?.objectStorage) {
             const bucketPerModule = options.s3?.bucketPerModule ?? configParser.boolean('S3_BUCKET_PER_MODULE', true);
             configureS3ObjectStorage({
@@ -190,9 +185,18 @@ export async function truncateTables(database, schema, tables) {
     if (tables.length == 0) {
         return;
     }
-    // Using CASCADE to handle foreign keys automatically
-    for (const table of tables) {
-        await database.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier(table)} CASCADE`);
+    const lockId = 987654321; // Different lock ID for table maintenance
+    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
+    try {
+        // Using CASCADE to handle foreign keys automatically
+        for (const table of tables) {
+            const tableName = isString(table) ? table : getEntityTableName(table);
+            const tableSchema = isString(table) ? schema : getEntitySchema(table, schema);
+            await database.execute(sql `TRUNCATE TABLE ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} CASCADE`);
+        }
+    }
+    finally {
+        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
     }
 }
 /**
@@ -203,8 +207,17 @@ export async function clearTenantData(database, schema, tables, tenantId) {
     if (tables.length == 0) {
         return;
     }
-    for (const table of tables) {
-        await database.execute(sql `DELETE FROM ${sql.identifier(schema)}.${sql.identifier(table)} WHERE tenant_id = ${tenantId}`);
+    const lockId = 987654321;
+    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
+    try {
+        for (const table of tables) {
+            const tableName = isString(table) ? table : getEntityTableName(table);
+            const tableSchema = isString(table) ? assertDefinedPass(schema, 'Schema not provided') : getEntitySchema(table, schema);
+            await database.execute(sql `DELETE FROM ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} WHERE tenant_id = ${tenantId}`);
+        }
+    }
+    finally {
+        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
     }
 }
 /**
@@ -212,7 +225,19 @@ export async function clearTenantData(database, schema, tables, tenantId) {
  * Useful in beforeAll() cleanups.
  */
 export async function dropTables(database, schema, tables) {
-    for (const table of tables) {
-        await database.execute(sql `DROP TABLE IF EXISTS ${sql.identifier(schema)}.${sql.identifier(table)} CASCADE`);
+    if (tables.length == 0) {
+        return;
+    }
+    const lockId = 987654321;
+    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
+    try {
+        for (const table of tables) {
+            const tableName = isString(table) ? table : getEntityTableName(table);
+            const tableSchema = isString(table) ? assertDefinedPass(schema, 'Schema not provided') : getEntitySchema(table, schema);
+            await database.execute(sql `DROP TABLE IF EXISTS ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} CASCADE`);
+        }
+    }
+    finally {
+        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
     }
 }

package/text/README.md

@@ -0,0 +1,346 @@
+# @tstdl/base/text
+
+A powerful, reactive, and type-safe text localization module for TypeScript applications, built on signals. It provides seamless integration for internationalization (i18n) with automatic UI updates, parameter interpolation, and strong compile-time safety.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [LocalizationService](#localizationservice)
+  - [Localization Definitions](#localization-definitions)
+  - [DynamicText](#dynamictext)
+  - [Type-Safe Keys](#type-safe-keys)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Define Localization Structure](#1-define-localization-structure)
+  - [2. Create Localization Data](#2-create-localization-data)
+  - [3. Register and Use](#3-register-and-use)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Reactive Localization with Signals](#reactive-localization-with-signals)
+  - [Parameterized Text](#parameterized-text)
+  - [Localization Functions](#localization-functions)
+  - [Localizing Enums](#localizing-enums)
+  - [Resolving Nested Dynamic Text](#resolving-nested-dynamic-text)
+  - [Common Localizations](#common-localizations)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe Keys**: Leverage TypeScript proxies to provide compile-time safety and autocompletion for localization keys, eliminating magic strings.
+- **Reactive Architecture**: Built on Signals, allowing text to automatically update whenever the active language changes without manual subscription management.
+- **Dynamic Text Support**: Uniformly handle static strings, Signals, and Observables as localizable content.
+- **Parameter Interpolation**: Easily inject values into translation strings (e.g., `Hello {{name}}`).
+- **Functional Localization**: Use functions for complex logic like pluralization or conditional formatting.
+- **Enum Support**: First-class utilities for localizing TypeScript enums.
+- **RxJS Compatibility**: Includes Observable-based alternatives for all reactive methods.
+
+## Core Concepts
+
+### LocalizationService
+
+The `LocalizationService` is the singleton central hub. It manages the active language, stores translation data, and performs the actual text resolution. It exposes reactive signals for the current language and available languages.
+
+### Localization Definitions
+
+A `Localization` object defines the translations for a specific language. It consists of:
+
+- **`language`**: Metadata like code (`en`) and name (`English`).
+- **`keys`**: A nested object structure containing the translation strings or functions.
+- **`enums`**: Definitions for translating TypeScript enums.
+
+### DynamicText
+
+`DynamicText` is a type alias for `ReactiveValue<LocalizableText>`. It represents a piece of text that might be:
+
+1. A static string or localization key.
+2. A `Signal` emitting localization keys.
+3. An `Observable` emitting localization keys.
+
+The module provides utilities to "resolve" a `DynamicText` into a `Signal<string>` that updates if either the source value changes _or_ the active language changes.
+
+### Type-Safe Keys
+
+Instead of using dot-notation strings (e.g., `'home.welcome'`), this module uses a proxy object generated by `getLocalizationKeys()`. This allows you to pass around references to keys (e.g., `keys.home.welcome`) that TypeScript understands, enabling refactoring support and compile-time checks.
+
+## 🚀 Basic Usage
+
+### 1. Define Localization Structure
+
+Define the shape of your localization keys using TypeScript types. This ensures all languages implement the same keys.
+
+```typescript
+import { type Localization, type LocalizeItem, getLocalizationKeys } from '@tstdl/base/text';
+
+// Define the structure
+type AppLocalization = Localization<{
+  app: {
+    title: LocalizeItem;
+    greeting: LocalizeItem;
+  };
+}>;
+
+// Create the type-safe key proxy
+export const keys = getLocalizationKeys<AppLocalization>();
+```
+
+### 2. Create Localization Data
+
+Implement the localization for your supported languages.
+
+```typescript
+import { type AppLocalization } from './localization-types'; // from step 1
+
+export const english: AppLocalization = {
+  language: { code: 'en', name: 'English' },
+  keys: {
+    app: {
+      title: 'My Awesome App',
+      greeting: 'Hello World',
+    },
+  },
+  enums: [],
+};
+
+export const german: AppLocalization = {
+  language: { code: 'de', name: 'Deutsch' },
+  keys: {
+    app: {
+      title: 'Meine Tolle App',
+      greeting: 'Hallo Welt',
+    },
+  },
+  enums: [],
+};
+```
+
+### 3. Register and Use
+
+Inject the service, register the languages, and resolve text.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LocalizationService } from '@tstdl/base/text';
+import { keys } from './localization-types';
+import { english, german } from './localizations';
+
+const localizationService = inject(LocalizationService);
+
+// Register languages
+localizationService.registerLocalization(english, german);
+
+// Set active language
+localizationService.setLanguage('en');
+
+// Resolve text reactively (returns a Signal)
+const titleSignal = localizationService.localize(keys.app.title);
+
+console.log(titleSignal()); // "My Awesome App"
+
+// Switch language
+localizationService.setLanguage('de');
+
+// Signal updates automatically
+console.log(titleSignal()); // "Meine Tolle App"
+```
+
+### Modular Localizations
+
+`registerLocalization` automatically merges new keys and enums into existing language definitions if the language code matches. This allows different parts of your application or different modules to contribute translations to the same language incrementally.
+
+### Handling Missing Keys and Parameters
+
+- **Missing Key**: If a localization key is missing for the active language, the service returns the key wrapped in double underscores (e.g., `__app.title__`) and logs a warning.
+- **Missing Parameter**: If a parameter is missing in the data object but required by the template string, it is replaced by the parameter name wrapped in double underscores (e.g., `Hello, __name__!`).
+- **Missing Observable Value**: When resolving an `Observable` based `DynamicText` using `resolveDynamicText`, the initial value before the first emission is `[MISSING LOCALIZATION KEY]`.
+
+## 🔧 Advanced Topics
+
+### Reactive Localization with Signals
+
+The `resolveDynamicText` function is the primary tool for handling text in reactive applications. It accepts static values, Signals, or Observables.
+
+```typescript
+import { signal } from '@tstdl/base/signals';
+import { resolveDynamicText } from '@tstdl/base/text';
+import { keys } from './localization-types';
+
+// A signal that determines which key to show
+const statusSignal = signal(keys.status.online);
+
+// Result is a signal that updates if statusSignal changes OR language changes
+const textSignal = resolveDynamicText(statusSignal);
+```
+
+### Parameterized Text
+
+You can define parameters in your strings using `{{ paramName }}` syntax. Use `localizationData` to bind values to these parameters.
+
+**Definition:**
+
+```typescript
+type AppLocalization = Localization<{
+  messages: {
+    welcome: LocalizeItem<{ name: string }>;
+  };
+}>;
+
+const en: AppLocalization = {
+  // ...
+  keys: {
+    messages: {
+      welcome: 'Welcome, {{name}}!',
+    },
+  },
+  // ...
+};
+```
+
+**Usage:**
+
+```typescript
+import { localizationData, resolveDynamicText } from '@tstdl/base/text';
+import { keys } from './localization-types';
+
+// Create a data object binding the key and parameters
+const data = localizationData(keys.messages.welcome, { name: 'Alice' });
+
+const text = resolveDynamicText(data);
+console.log(text()); // "Welcome, Alice!"
+```
+
+### Localization Functions
+
+For complex logic (like pluralization or conditional formatting), use a function instead of a string. Functions receive the parameters and a context object containing the `LocalizationService`.
+
+```typescript
+const en: AppLocalization = {
+  // ...
+  keys: {
+    items: {
+      count: ({ count }, { localizationService }) => (count === 1 ? '1 Item' : `${count} Items`),
+    },
+  },
+  // ...
+};
+
+// Usage
+const text = resolveDynamicText(localizationData(keys.items.count, { count: 5 }));
+console.log(text()); // "5 Items"
+```
+
+### Localizing Enums
+
+The module provides specific helpers for `enum` types to ensure type safety and ease of use.
+
+```typescript
+import { defineEnum, type EnumType } from '@tstdl/base/enumeration';
+import { enumerationLocalization, localizeEnum } from '@tstdl/base/text';
+
+// 1. Define Enum
+const Status = defineEnum('Status', {
+  Active: 'active',
+  Inactive: 'inactive',
+});
+type Status = EnumType<typeof Status>;
+
+// 2. Add to Localization Type
+type AppLocalization = Localization<
+  {
+    /* ... keys ... */
+  },
+  [typeof Status] // Add enum type here
+>;
+
+// 3. Define Translations
+const en: AppLocalization = {
+  // ...
+  enums: [
+    enumerationLocalization(Status, 'Status', {
+      [Status.Active]: 'Active User',
+      [Status.Inactive]: 'Inactive User',
+    }),
+  ],
+};
+
+// 4. Usage
+const statusText = localizationService.localizeEnum(Status, Status.Active);
+console.log(statusText()); // "Active User"
+```
+
+### Resolving Nested Dynamic Text
+
+When working with lists of objects where one property is a `DynamicText` (e.g., a navigation menu or a list of options), `resolveNestedDynamicTexts` helps transform the entire array efficiently.
+
+```typescript
+import { resolveNestedDynamicTexts, type DynamicText } from '@tstdl/base/text';
+
+type MenuItem = {
+  id: string;
+  label: DynamicText; // Can be a string, key, or localizationData
+};
+
+const menuItems: MenuItem[] = [
+  { id: 'home', label: keys.nav.home },
+  { id: 'settings', label: keys.nav.settings },
+];
+
+// Returns a Signal<Array<{ id: string, label: string }>>
+// The 'label' property is now the resolved string
+const resolvedMenu = resolveNestedDynamicTexts(menuItems, 'label');
+```
+
+### Common Localizations
+
+The module includes a set of common localizations (Yes, No, Ok, Cancel, etc.) that you can merge into your application to avoid repetition.
+
+```typescript
+import { englishTstdlCommonLocalization, germanTstdlCommonLocalization } from '@tstdl/base/text';
+
+localizationService.registerLocalization(englishTstdlCommonLocalization, germanTstdlCommonLocalization);
+```
+
+## 📚 API
+
+### LocalizationService
+
+| Method                                   | Description                                                                 |
+| :--------------------------------------- | :-------------------------------------------------------------------------- |
+| `registerLocalization(...localizations)` | Registers one or more localization definitions. Merges if language exists.  |
+| `setLanguage(code)`                      | Sets the active language by code or `Language` object.                      |
+| `getLanguage(code)`                      | Retrieves a registered `Language` by its code.                              |
+| `hasLanguage(code)`                      | Checks if a language is registered.                                         |
+| `localize(data)`                         | Returns a `Signal<string>` for the given key/data.                          |
+| `localize$(data)`                        | Returns an `Observable<string>` for the given key/data.                     |
+| `localizeOnce(data)`                     | Returns a `string` (non-reactive) for the current language.                 |
+| `localizeEnum(enum, value)`              | Returns a `Signal<string>` for the enum value.                              |
+| `localizeEnum$(enum, value)`             | Returns an `Observable<string>` for the enum value.                         |
+| `localizeEnumOnce(enum, value)`          | Returns a `string` (non-reactive) for the enum value.                       |
+| `activeLanguage`                         | Read-only signal of the currently active `Language`.                        |
+| `availableLanguages`                     | Read-only signal of all registered `Language`s.                             |
+
+### Utilities
+
+| Function                              | Description                                                                 |
+| :------------------------------------ | :-------------------------------------------------------------------------- |
+| `getLocalizationKeys<T>()`            | Returns a proxy object for type-safe access to localization keys.           |
+| `localizationData(key, params)`       | Creates a typed object containing a key and its parameters.                 |
+| `resolveDynamicText(text)`            | Converts a `DynamicText` into a `Signal<string>`.                           |
+| `resolveDynamicText$(text)`           | Converts a `DynamicText` into an `Observable<string>`.                      |
+| `resolveDynamicTexts(texts)`          | Converts an array of `DynamicText` into a `Signal<string[]>`.               |
+| `resolveDynamicTexts$(texts)`         | Converts an array of `DynamicText` into an `Observable<string[]>`.          |
+| `resolveNestedDynamicText(obj, key)`  | Resolves a `DynamicText` property within an object (Signal).                |
+| `resolveNestedDynamicText$(obj, key)` | Resolves a `DynamicText` property within an object (Observable).            |
+| `resolveNestedDynamicTexts(arr, key)` | Resolves a `DynamicText` property within an array of objects (Signal).      |
+| `resolveNestedDynamicTexts$(arr, key)`| Resolves a `DynamicText` property within an array of objects (Observable).  |
+| `enumerationLocalization(...)`        | Helper to define enum translations in a `Localization` object.              |
+| `autoEnumerationLocalization(enum)`   | Generates default translations using enum key names as values.              |
+
+### Types
+
+| Type                   | Description                                                                        |
+| :--------------------- | :--------------------------------------------------------------------------------- |
+| `Localization`         | The structure for defining translations (language, keys, enums).                   |
+| `LocalizeItem<Params>` | A translation value: either a string or a `LocalizeFunction`.                      |
+| `LocalizeFunction<P>`  | A function returning a string, receiving parameters and `LocalizeFunctionContext`. |
+| `DynamicText`          | `ReactiveValue<LocalizableText>`. The standard input type for localizable content. |
+| `LocalizableText`      | `string | LocalizationData`.                                                       |
+| `LocalizationData`     | Key, `LocalizationDataObject`, or `EnumLocalizationKey`.                           |

package/text/localization.service.js

@@ -192,7 +192,7 @@ function buildMappedLocalization({ language, keys, enums }) {
     const mappedLocalization = {
         language,
         keys: new Map(deepObjectEntries(keys)),
-        enums: new Map(enumsEntries)
+        enums: new Map(enumsEntries),
     };
     return mappedLocalization;
 }
@@ -215,7 +215,7 @@ function mergeMappedLocalization(a, b, force = false) {
     return {
         language: b.language,
         keys: new Map([...a.keys, ...b.keys]),
-        enums: new Map([...a.enums, ...b.enums])
+        enums: new Map([...a.enums, ...b.enums]),
     };
 }
 export function isLocalizeItem(value) {