@tstdl/base 0.93.139 → 0.93.141

package/orm/server/migration.js

@@ -0,0 +1,72 @@
+import { sql } from 'drizzle-orm';
+import { provideInitializer } from '../../application/providers.js';
+import { injectionToken, Injector } from '../../injector/index.js';
+import { inject, injectAll, runInInjectionContext } from '../../injector/inject.js';
+import { Logger } from '../../logger/index.js';
+import { isDefined } from '../../utils/type-guards.js';
+import { Database } from './database.js';
+export const DATABASE_MIGRATION = injectionToken('DatabaseMigration');
+/**
+ * Registers a database migration in the provided injector.
+ * @param name - The unique name of the migration.
+ * @param migrate - The migration function.
+ * @param options - Optional injector and dependencies.
+ */
+export function registerDatabaseMigration(name, migrate, { injector, dependencies } = {}) {
+    const targetInjector = injector ?? Injector;
+    targetInjector.register(DATABASE_MIGRATION, { useValue: { name, migrate, dependencies } }, { multi: true });
+}
+export function provideDatabaseMigrator() {
+    return provideInitializer(runDatabaseMigrations);
+}
+export async function runDatabaseMigrations() {
+    const injector = inject(Injector);
+    const database = inject(Database);
+    const logger = inject(Logger, 'DatabaseMigrationOrchestrator');
+    const migrations = injectAll(DATABASE_MIGRATION, undefined, { optional: true });
+    if (migrations.length == 0) {
+        return;
+    }
+    const lockId = 123456789; // Fixed lock ID for migrations
+    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
+    try {
+        const sortedMigrations = sortMigrations(migrations);
+        for (const migration of sortedMigrations) {
+            logger.info(`Running database migration: ${migration.name}`);
+            await runInInjectionContext(injector, async () => await migration.migrate());
+        }
+    }
+    finally {
+        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
+    }
+}
+function sortMigrations(migrations) {
+    const result = [];
+    const visited = new Set();
+    const visiting = new Set();
+    const migrationMap = new Map(migrations.map((m) => [m.name, m]));
+    function visit(name) {
+        if (visited.has(name)) {
+            return;
+        }
+        if (visiting.has(name)) {
+            throw new Error(`Circular dependency detected in database migrations: ${name}`);
+        }
+        visiting.add(name);
+        const migration = migrationMap.get(name);
+        if (isDefined(migration?.dependencies)) {
+            for (const dependency of migration.dependencies) {
+                visit(dependency);
+            }
+        }
+        visiting.delete(name);
+        visited.add(name);
+        if (isDefined(migration)) {
+            result.push(migration);
+        }
+    }
+    for (const migration of migrations) {
+        visit(migration.name);
+    }
+    return result;
+}

package/orm/server/repository.d.ts

@@ -18,7 +18,7 @@ type EntityRepositoryContext = {
     encryptionSecret: Uint8Array<ArrayBuffer> | undefined;
     transformContext: TransformContext | Promise<TransformContext> | undefined;
 };
-type InferSelect<T extends BaseEntity = BaseEntity> = PgTableFromType<EntityType<T>>['$inferSelect'];
+export type InferSelect<T extends BaseEntity = BaseEntity> = PgTableFromType<EntityType<T>>['$inferSelect'];
 export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends Transactional<EntityRepositoryContext> implements Resolvable<EntityType<T>> {
     #private;
     readonly type: EntityType<T>;

package/orm/server/transaction.d.ts

@@ -1,15 +1,18 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 import { PgTransaction as DrizzlePgTransaction, type PgQueryResultHKT, type PgTransactionConfig } from 'drizzle-orm/pg-core';
 import type { Record } from '../../types/index.js';
 import type { Database } from './database.js';
 export type PgTransaction = DrizzlePgTransaction<PgQueryResultHKT, Record, Record>;
 export { DrizzlePgTransaction };
 export type TransactionConfig = PgTransactionConfig;
-export declare abstract class Transaction implements AsyncDisposable {
+export declare class Transaction implements AsyncDisposable {
     #private;
+    readonly pgTransaction: PgTransaction;
     readonly afterCommit: import("../../utils/async-hook/index.js").AsyncHook<never, never, unknown>;
     readonly parent?: Transaction;
     manualCommit: boolean;
-    constructor(parent?: Transaction);
+    constructor(pgTransaction: PgTransaction, parent?: Transaction);
+    static create(session: Database | PgTransaction, config?: TransactionConfig, parent?: Transaction): Promise<Transaction>;
     [Symbol.asyncDispose](): Promise<void>;
     withManualCommit(): void;
     /**
@@ -19,14 +22,6 @@ export declare abstract class Transaction implements AsyncDisposable {
     use<T>(handler: () => Promise<T>): Promise<T>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
-    protected abstract _commit(): void | Promise<void>;
-    protected abstract _rollback(): void | Promise<void>;
-}
-export declare class DrizzleTransaction extends Transaction {
-    #private;
-    readonly pgTransaction: PgTransaction;
-    constructor(pgTransaction: PgTransaction, parent?: Transaction);
-    static create(session: Database | PgTransaction, config?: TransactionConfig, parent?: Transaction): Promise<DrizzleTransaction>;
     protected _commit(): Promise<void>;
     protected _rollback(): Promise<void>;
     private setTransactionResultPromise;

package/orm/server/transaction.js

@@ -1,16 +1,37 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 import { PgTransaction as DrizzlePgTransaction } from 'drizzle-orm/pg-core';
 import { DeferredPromise } from '../../promise/deferred-promise.js';
 import { asyncHook } from '../../utils/async-hook/index.js';
 export { DrizzlePgTransaction };
 export class Transaction {
+    #deferPromise = new DeferredPromise();
+    #pgTransactionResultPromise;
     #useCounter = 0;
     #done = false;
+    pgTransaction;
     afterCommit = asyncHook();
     parent;
     manualCommit = false;
-    constructor(parent) {
+    constructor(pgTransaction, parent) {
+        this.pgTransaction = pgTransaction;
         this.parent = parent;
     }
+    static async create(session, config, parent) {
+        const instancePromise = new DeferredPromise();
+        const pgTransactionResultPromise = session.transaction(async (tx) => {
+            const transaction = new Transaction(tx, parent);
+            instancePromise.resolve(transaction);
+            await transaction.#deferPromise;
+        }, config);
+        pgTransactionResultPromise.catch((error) => {
+            if (instancePromise.pending) {
+                instancePromise.reject(error);
+            }
+        });
+        const transaction = await instancePromise;
+        transaction.setTransactionResultPromise(pgTransactionResultPromise);
+        return transaction;
+    }
     async [Symbol.asyncDispose]() {
         if (!this.#done) {
             await this.rollback();
@@ -67,31 +88,6 @@ export class Transaction {
         this.#done = true;
         await this._rollback();
     }
-}
-export class DrizzleTransaction extends Transaction {
-    #deferPromise = new DeferredPromise();
-    pgTransaction;
-    #pgTransactionResultPromise;
-    constructor(pgTransaction, parent) {
-        super(parent);
-        this.pgTransaction = pgTransaction;
-    }
-    static async create(session, config, parent) {
-        const instancePromise = new DeferredPromise();
-        const pgTransactionResultPromise = session.transaction(async (tx) => {
-            const transaction = new DrizzleTransaction(tx, parent);
-            instancePromise.resolve(transaction);
-            await transaction.#deferPromise;
-        }, config);
-        pgTransactionResultPromise.catch((error) => {
-            if (instancePromise.pending) {
-                instancePromise.reject(error);
-            }
-        });
-        const transaction = await instancePromise;
-        transaction.setTransactionResultPromise(pgTransactionResultPromise);
-        return transaction;
-    }
     async _commit() {
         this.#deferPromise.resolve();
         await this.#pgTransactionResultPromise;

package/orm/server/transactional.js

@@ -4,7 +4,7 @@ import { Injector } from '../../injector/index.js';
 import { inject, injectAsync, runInInjectionContext } from '../../injector/inject.js';
 import { isDefined, isNull, isUndefined } from '../../utils/type-guards.js';
 import { Database } from './database.js';
-import { DrizzleTransaction, Transaction } from './transaction.js';
+import { Transaction } from './transaction.js';
 const transactionCache = new WeakMap();
 const { getCurrentTransactionalContext, isInTransactionalContext, runInTransactionalContext, tryGetCurrentTransactionalContext } = createContextProvider('Transactional');
 export { getCurrentTransactionalContext, isInTransactionalContext, runInTransactionalContext, tryGetCurrentTransactionalContext };
@@ -58,7 +58,7 @@ export class Transactional {
             }
         }
         const parentTransaction = tryGetTstdlTransaction(this.session);
-        const transaction = await DrizzleTransaction.create(this.session, config, parentTransaction);
+        const transaction = await Transaction.create(this.session, config, parentTransaction);
         transactionCache.set(transaction.pgTransaction, transaction);
         return transaction;
     }
@@ -77,7 +77,7 @@ export class Transactional {
             return this;
         }
         const context = {
-            session: session,
+            session,
             instances: this.#instances,
             data: this.getTransactionalContextData(),
         };

package/orm/tests/database-migration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/orm/tests/database-migration.test.js

@@ -0,0 +1,82 @@
+import { APPLICATION_INITIALIZER } from '../../application/application.js';
+import { runInInjectionContext } from '../../injector/inject.js';
+import { DATABASE_MIGRATION, provideDatabaseMigrator, runDatabaseMigrations } from '../../orm/server/migration.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { describe, expect, it } from 'vitest';
+describe('Database Migration Orchestration', () => {
+    it('should have DATABASE_MIGRATION token defined', () => {
+        expect(DATABASE_MIGRATION).toBeDefined();
+    });
+    it('should provide database migrator as application initializer', () => {
+        const provider = provideDatabaseMigrator();
+        expect(provider.provide).toBe(APPLICATION_INITIALIZER);
+        expect(provider.useValue).toBe(runDatabaseMigrations);
+        expect(provider.multi).toBe(true);
+    });
+    it('should register and resolve a migration', async () => {
+        const { injector } = await setupIntegrationTest();
+        let migrated = false;
+        const migration = {
+            name: 'test-migration',
+            migrate: async () => {
+                migrated = true;
+            },
+        };
+        injector.register(DATABASE_MIGRATION, { useValue: migration }, { multi: true });
+        const migrations = injector.resolveAll(DATABASE_MIGRATION);
+        expect(migrations).toHaveLength(1);
+        const firstMigration = migrations[0];
+        expect(firstMigration.name).toBe('test-migration');
+        await firstMigration.migrate();
+        expect(migrated).toBe(true);
+    });
+    it('should run migrations in the correct order based on dependencies', async () => {
+        const { injector } = await setupIntegrationTest();
+        const executionOrder = [];
+        const migrationA = {
+            name: 'migration-a',
+            migrate: async () => {
+                executionOrder.push('a');
+            },
+            dependencies: ['migration-b'],
+        };
+        const migrationB = {
+            name: 'migration-b',
+            migrate: async () => {
+                executionOrder.push('b');
+            },
+        };
+        const migrationC = {
+            name: 'migration-c',
+            migrate: async () => {
+                executionOrder.push('c');
+            },
+            dependencies: ['migration-a'],
+        };
+        injector.register(DATABASE_MIGRATION, { useValue: migrationA }, { multi: true });
+        injector.register(DATABASE_MIGRATION, { useValue: migrationB }, { multi: true });
+        injector.register(DATABASE_MIGRATION, { useValue: migrationC }, { multi: true });
+        await runInInjectionContext(injector, async () => {
+            await runDatabaseMigrations();
+        });
+        expect(executionOrder).toEqual(['b', 'a', 'c']);
+    });
+    it('should throw on circular dependency', async () => {
+        const { injector } = await setupIntegrationTest();
+        const migrationA = {
+            name: 'migration-a',
+            migrate: async () => { },
+            dependencies: ['migration-b'],
+        };
+        const migrationB = {
+            name: 'migration-b',
+            migrate: async () => { },
+            dependencies: ['migration-a'],
+        };
+        injector.register(DATABASE_MIGRATION, { useValue: migrationA }, { multi: true });
+        injector.register(DATABASE_MIGRATION, { useValue: migrationB }, { multi: true });
+        await runInInjectionContext(injector, async () => {
+            await expect(runDatabaseMigrations()).rejects.toThrow('Circular dependency detected');
+        });
+    });
+});

package/orm/tests/encryption.test.js

@@ -1,4 +1,3 @@
-import { DetailsError } from '../../errors/index.js';
 import { describe, expect, test } from 'vitest';
 import { decryptBytes, encryptBytes } from '../server/encryption.js';
 describe('ORM Encryption', () => {
@@ -12,15 +11,15 @@ describe('ORM Encryption', () => {
         const decrypted = await decryptBytes(encrypted, key);
         expect(new TextDecoder().decode(decrypted)).toBe('Hello, ORM Encryption!');
     });
-    test('should throw DetailsError on corrupted data', async () => {
+    test('should throw Error on corrupted data', async () => {
         const key = await generateKey();
         const data = new TextEncoder().encode('Corrupt me');
         const encrypted = await encryptBytes(data, key);
         // Corrupt the ciphertext (last byte)
         const lastIndex = encrypted.length - 1;
         encrypted[lastIndex] = encrypted[lastIndex] ^ 1;
-        await expect(decryptBytes(encrypted, key)).rejects.toThrow(DetailsError);
-        await expect(decryptBytes(encrypted, key)).rejects.toThrow('Decrypt error');
+        await expect(decryptBytes(encrypted, key)).rejects.toThrow(Error);
+        await expect(decryptBytes(encrypted, key)).rejects.toThrow('Decryption failed.');
     });
     test('should throw error on invalid version', async () => {
         const key = await generateKey();

package/orm/utils.d.ts

@@ -4,8 +4,8 @@
  */
 import { type PropertyMetadata } from '../reflection/registry.js';
 import type { AbstractConstructor } from '../types/index.js';
-import type { InheritanceMetadata } from './decorators.js';
-import type { BaseEntity, Entity } from './entity.js';
+import type { InheritanceMetadata, OrmTableReflectionData } from './decorators.js';
+import type { BaseEntity, Entity, EntityType } from './entity.js';
 /**
  * Converts an array of entities into a Map keyed by entity ID.
  * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
@@ -24,3 +24,18 @@ export declare function getEntityIds(entities: (Entity | BaseEntity)[]): string[
 export declare function isChildEntity(type: AbstractConstructor): boolean;
 export declare function getInheritanceMetadata(type: AbstractConstructor): InheritanceMetadata | undefined;
 export declare function getOwnProperties(type: AbstractConstructor): PropertyMetadata[];
+/**
+ * Gets the database schema name for a given entity type, traversing the inheritance hierarchy.
+ * @param type The entity class.
+ * @param fallback Optional fallback schema name if none is defined in metadata.
+ * @returns The resolved schema name.
+ */
+export declare function getEntitySchema(type: AbstractConstructor, fallback?: string): string;
+/**
+ * Gets the database table name for a given entity type, traversing the inheritance hierarchy.
+ * @param type The entity class.
+ * @returns The resolved table name.
+ */
+export declare function getEntityTableName(type: AbstractConstructor): string;
+export declare function getDefaultTableName(type: EntityType): string;
+export declare function getTableReflectionDatas(type: EntityType): OrmTableReflectionData[];

package/orm/utils.js

@@ -3,7 +3,8 @@
  * Provides utility functions for working with ORM entities.
  */
 import { reflectionRegistry } from '../reflection/registry.js';
-import { isDefined, isNotNullOrUndefined, isUndefined } from '../utils/type-guards.js';
+import { toSnakeCase } from '../utils/string/index.js';
+import { assertDefined, isDefined, isNotNullOrUndefined, isString, isUndefined } from '../utils/type-guards.js';
 export function getEntityMap(entities, selector = (entity) => entity.id) {
     const entries = entities.map((entity) => [selector(entity), entity]);
     return new Map(entries);
@@ -36,3 +37,50 @@ export function getOwnProperties(type) {
     }
     return [...metadata.properties.values()].filter((property) => !property.inherited || (property.key == 'id'));
 }
+/**
+ * Gets the database schema name for a given entity type, traversing the inheritance hierarchy.
+ * @param type The entity class.
+ * @param fallback Optional fallback schema name if none is defined in metadata.
+ * @returns The resolved schema name.
+ */
+export function getEntitySchema(type, fallback) {
+    for (let currentMetadata = reflectionRegistry.getMetadata(type); isNotNullOrUndefined(currentMetadata); currentMetadata = isNotNullOrUndefined(currentMetadata.parent) ? reflectionRegistry.getMetadata(currentMetadata.parent) : undefined) {
+        const schema = currentMetadata.data.tryGet('orm')?.schema;
+        if (isDefined(schema)) {
+            return schema;
+        }
+    }
+    if (isDefined(fallback)) {
+        return fallback;
+    }
+    throw new Error(`Schema not found for entity ${type.name} and no fallback provided.`);
+}
+/**
+ * Gets the database table name for a given entity type, traversing the inheritance hierarchy.
+ * @param type The entity class.
+ * @returns The resolved table name.
+ */
+export function getEntityTableName(type) {
+    for (let currentMetadata = reflectionRegistry.getMetadata(type); isNotNullOrUndefined(currentMetadata); currentMetadata = isNotNullOrUndefined(currentMetadata.parent) ? reflectionRegistry.getMetadata(currentMetadata.parent) : undefined) {
+        const name = currentMetadata.data.tryGet('orm')?.name;
+        if (isDefined(name)) {
+            return name;
+        }
+    }
+    return getDefaultTableName(type);
+}
+export function getDefaultTableName(type) {
+    return toSnakeCase(isString(type.entityName) ? type.entityName : type.name.replace(/\d+$/u, ''));
+}
+export function getTableReflectionDatas(type) {
+    const metadata = reflectionRegistry.getMetadata(type);
+    assertDefined(metadata, `Type ${type.name} does not have reflection metadata.`);
+    const tableReflectionDatas = [];
+    for (let currentMetadata = metadata; isNotNullOrUndefined(currentMetadata?.parent); currentMetadata = reflectionRegistry.getMetadata(currentMetadata.parent)) {
+        const tableReflectionData = currentMetadata.data.tryGet('orm');
+        if (isDefined(tableReflectionData)) {
+            tableReflectionDatas.push(tableReflectionData);
+        }
+    }
+    return tableReflectionDatas;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.139",
+  "version": "0.93.141",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -10,16 +10,18 @@
     "build": "tsc && tsc-alias && npm run copy:orm",
     "build:watch": "concurrently --raw --kill-others npm:tsc:watch npm:tsc-alias:watch",
     "build:production": "rm -rf dist && npm run build && npm run build:production:copy-files",
-    "build:production:copy-files": "cp package.json eslint.config.js tsconfig.server.json dist/ && cp tsconfig.base.json dist/tsconfig.json && npm run copy:orm",
+    "build:production:copy-files": "cp package.json eslint.config.js tsconfig.server.json dist/ && cp tsconfig.base.json dist/tsconfig.json && npm run copy:orm && npm run copy:readmes",
     "build:dts": "rm -rf dist && tsc -p tsconfig.dts.json && tsc-alias",
     "build:docs": "typedoc",
     "build:docs:watch": "typedoc --watch",
     "lint": "eslint --cache source/",
     "pub": "npm run build:production && npm run cleanup:dist && npm publish dist/",
     "test": "vitest run",
+    "test:coverage": "f() { vitest run --coverage --coverage.include=\"source/$1/**/*.ts\" source/$1; }; f",
     "tsc:watch": "tsc --watch",
     "tsc-alias:watch": "tsc-alias --watch",
     "cleanup:dist": "rm -vrf dist/tools/",
+    "copy:readmes": "cp README.md dist/ && cd source && find . -name \"README.md\" -exec cp --parents {} ../dist/ \\;",
     "generate:migration": "./scripts/manage-orm.sh generate && npm run copy:orm",
     "generate:readmes": "deno run --allow-run=code2prompt --allow-read --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
     "generate:readmes:new-only": "npm run generate:readmes -- --skip-existing",
@@ -150,7 +152,9 @@
     "type-fest": "^5.4"
   },
   "peerDependencies": {
-    "@genkit-ai/google-genai": "^1.28",
+    "@aws-sdk/client-s3": "^3.996",
+    "@aws-sdk/s3-request-presigner": "^3.996",
+    "@genkit-ai/google-genai": "^1.29",
     "@google-cloud/storage": "^7.19",
     "@toon-format/toon": "^2.1.0",
     "@tstdl/angular": "^0.93",
@@ -160,10 +164,8 @@
     "@zxcvbn-ts/language-en": "^3.0",
     "drizzle-orm": "^0.45",
     "file-type": "^21.3",
-    "genkit": "^1.28",
+    "genkit": "^1.29",
     "handlebars": "^4.7",
-    "@aws-sdk/client-s3": "^3.993",
-    "@aws-sdk/s3-request-presigner": "^3.993",
     "mjml": "^4.18",
     "nodemailer": "^8.0",
     "pg": "^8.18",
@@ -181,6 +183,7 @@
     }
   },
   "devDependencies": {
+    "@biomejs/biome": "2.4",
     "@stylistic/eslint-plugin": "5.9",
     "@types/koa__router": "12.0",
     "@types/luxon": "3.7",

package/password/README.md

@@ -0,0 +1,164 @@
+# @tstdl/base/password
+
+A robust password strength estimation module that combines the advanced heuristic analysis of `zxcvbn-ts` with secure checks against the "Have I Been Pwned" breach database.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Strength Analysis](#strength-analysis-zxcvbn)
+  - [Breach Check](#breach-check-hibp)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Localization](#localization)
+  - [Offline Checks](#offline-checks)
+  - [Schema Integration](#schema-integration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Advanced Heuristics:** Utilizes `zxcvbn-ts` to detect common patterns, dictionary words, names, keyboard sequences, and dates.
+- **Breach Detection:** Securely checks if a password has appeared in known data breaches via the "Have I Been Pwned" (HIBP) API.
+- **Secure by Design:** Uses k-Anonymity for HIBP checks; the full password hash is never sent over the network.
+- **Unified Scoring:** Provides a consolidated strength score from 0 (Very Weak) to 4 (Very Strong).
+- **Localized Feedback:** Returns localization keys for warnings and suggestions, supporting English and German out of the box.
+- **Schema & Validation Ready:** `PasswordCheckResult` is fully decorated with `@tstdl/base/schema`, making it ready for API contracts and data models.
+- **Performance Optimized:** Dynamically imports heavy analysis libraries only when needed to keep initial bundle sizes low.
+
+## Core Concepts
+
+### Strength Analysis (zxcvbn)
+
+The module uses `zxcvbn-ts` to calculate entropy and estimate crack time. It looks for:
+
+- **Dictionaries:** Common passwords, names, and words in multiple languages.
+- **Patterns:** L33t speak, keyboard walks (e.g., "qwerty"), and repetitions.
+- **Personal Info:** Dates and years.
+
+### Breach Check (HIBP)
+
+To protect against credential stuffing, the module checks the "Have I Been Pwned" database.
+
+1.  The password is hashed using SHA-1.
+2.  Only the first 5 characters of the hash are sent to the API (k-Anonymity).
+3.  The API returns all suffixes matching that prefix.
+4.  The module checks locally if the full hash exists in the response.
+
+If a password is found in the breach database, its strength score is automatically downgraded to **0 (Very Weak)**, regardless of its complexity.
+
+## 🚀 Basic Usage
+
+The primary entry point is the `checkPassword` function. It returns a `PasswordCheckResult` containing the score, breach count, and feedback keys.
+
+```typescript
+import { checkPassword, PasswordStrength } from '@tstdl/base/password';
+
+async function validateUserPassword(password: string) {
+  const result = await checkPassword(password);
+
+  console.log(`Score: ${result.strength} (${PasswordStrength[result.strength]})`);
+
+  if (result.pwned && result.pwned > 0) {
+    console.warn(`⚠️ This password has appeared in ${result.pwned} data breaches!`);
+  }
+
+  if (result.strength < PasswordStrength.Strong) {
+    console.log('Password is too weak.');
+  }
+}
+
+validateUserPassword('correct-horse-battery-staple');
+```
+
+## 🔧 Advanced Topics
+
+### Localization
+
+The `warnings` and `suggestions` arrays in the result contain **localization keys** (e.g., `tstdl.passwordCheck.warnings.simpleRepeat`) rather than raw text. This allows you to easily translate feedback using the `@tstdl/base/text` module.
+
+The module exports `englishPasswordCheckLocalization` and `germanPasswordCheckLocalization`.
+
+```typescript
+import { checkPassword, englishPasswordCheckLocalization } from '@tstdl/base/password';
+import { LocalizationService } from '@tstdl/base/text';
+
+// 1. Setup the localization service with the provided language pack
+const localization = new LocalizationService([englishPasswordCheckLocalization]);
+localization.setLanguage('en');
+
+async function showFeedback(password: string) {
+  const result = await checkPassword(password);
+
+  // 2. Translate the keys to human-readable text
+  const warnings = result.warnings.map((key) => localization.localize(key));
+  const suggestions = result.suggestions.map((key) => localization.localize(key));
+
+  console.log('Warnings:', warnings);
+  console.log('Suggestions:', suggestions);
+}
+```
+
+### Offline Checks
+
+If you are in an environment without internet access, or if you want to skip the HTTP request to "Have I Been Pwned" for performance reasons, you can disable it via options.
+
+```typescript
+import { checkPassword } from '@tstdl/base/password';
+
+async function checkOffline(password: string) {
+  // Disables the HIBP API call
+  const result = await checkPassword(password, { checkForPwned: false });
+
+  // result.pwned will be undefined
+  console.log(`Local Strength Score: ${result.strength}`);
+}
+```
+
+### Schema Integration
+
+The `PasswordCheckResult` is a class decorated with `@tstdl/base/schema`. This makes it easy to use as a return type in your API definitions or as a nested property in other models.
+
+```typescript
+import { PasswordCheckResult } from '@tstdl/base/password';
+import { defineApi } from '@tstdl/base/api';
+
+export const myApiDefinition = defineApi({
+  endpoints: {
+    checkStrength: {
+      method: 'GET',
+      parameters: { password: String },
+      result: PasswordCheckResult,
+    },
+  },
+});
+```
+
+### Authentication Integration
+
+This module is used by the `@tstdl/base/authentication` framework to enforce password requirements during registration or password changes. See `AuthenticationSecretRequirementsValidator` for more details on how to customize these checks in your application.
+
+## 📚 API
+
+### Functions
+
+| Function         | Signature                                                                            | Description                                                                     |
+| :--------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
+| `checkPassword`  | `(password: string, options?: CheckPasswordOptions) => Promise<PasswordCheckResult>` | Analyzes password strength and checks for breaches.                             |
+| `haveIBeenPwned` | `(password: string) => Promise<number>`                                              | Checks the password against the HIBP database and returns the occurrence count. |
+
+### Classes & Interfaces
+
+| Name                        | Type    | Description                                                                                |
+| :-------------------------- | :------ | :----------------------------------------------------------------------------------------- |
+| `PasswordCheckResult`       | `class` | The result object containing `strength`, `pwned` count, `warnings`, and `suggestions`.     |
+| `CheckPasswordOptions`      | `type`  | Options object. Property `checkForPwned` (boolean, default `true`) controls the API check. |
+| `PasswordCheckLocalization` | `type`  | Type definition for the localization structure used by this module.                        |
+
+### Enums & Constants
+
+| Name                               | Type    | Description                                                               |
+| :--------------------------------- | :------ | :------------------------------------------------------------------------ |
+| `PasswordStrength`                 | `enum`  | `VeryWeak` (0), `Weak` (1), `Medium` (2), `Strong` (3), `VeryStrong` (4). |
+| `englishPasswordCheckLocalization` | `const` | English localization definitions for warnings and suggestions.            |
+| `germanPasswordCheckLocalization`  | `const` | German localization definitions for warnings and suggestions.             |
+| `passwordCheckLocalizationKeys`    | `const` | Helper object containing the localization key paths.                      |