@nestjs-dash/translation 0.2.0

package/dist/migration/migration-template.d.ts

@@ -0,0 +1 @@
+export declare function renderMigrationFile(className: string, upStatements: string[], downStatements: string[], driver?: string): string;

package/dist/migration/migration-template.js

@@ -0,0 +1,29 @@
+export function renderMigrationFile(className, upStatements, downStatements, driver) {
+    const mysqlWarning = driver === 'mysql'
+        ? '// Note: MySQL DDL statements are not transactional. If this migration fails partway through, verify the table/column state manually before re-running.\n'
+        : '';
+    return `import { MigrationInterface, QueryRunner } from 'typeorm';
+
+${mysqlWarning}export class ${className} implements MigrationInterface {
+  name = '${className}';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+${renderStatements(upStatements)}
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+${renderStatements(downStatements)}
+  }
+}
+`;
+}
+function renderStatements(statements) {
+    if (statements.length === 0)
+        return '';
+    return statements
+        .map((statement) => `    await queryRunner.query(\`${escapeForTemplateLiteral(statement)}\`);`)
+        .join('\n');
+}
+function escapeForTemplateLiteral(sql) {
+    return sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}

package/dist/migration/mysql-migration.adapter.d.ts

@@ -0,0 +1,7 @@
+import type { MigrationDialectAdapter } from './migration-dialect.adapter.js';
+export declare class MysqlMigrationDialectAdapter implements MigrationDialectAdapter {
+    readonly driver = "mysql";
+    buildJsonExpression(columnRef: string, locale: string): string;
+    extractJsonExpression(columnRef: string, locale: string): string;
+    setNotNullExpression(qualifiedTable: string, columnRef: string, columnType: string): string;
+}

package/dist/migration/mysql-migration.adapter.js

@@ -0,0 +1,17 @@
+export class MysqlMigrationDialectAdapter {
+    constructor() {
+        this.driver = 'mysql';
+    }
+    buildJsonExpression(columnRef, locale) {
+        return `JSON_OBJECT('${escapeLiteral(locale)}', ${columnRef})`;
+    }
+    extractJsonExpression(columnRef, locale) {
+        return `JSON_UNQUOTE(JSON_EXTRACT(${columnRef}, '$.${escapeLiteral(locale)}'))`;
+    }
+    setNotNullExpression(qualifiedTable, columnRef, columnType) {
+        return `ALTER TABLE ${qualifiedTable} MODIFY COLUMN ${columnRef} ${columnType} NOT NULL`;
+    }
+}
+function escapeLiteral(value) {
+    return value.replace(/'/g, "''");
+}

package/dist/migration/postgres-migration.adapter.d.ts

@@ -0,0 +1,7 @@
+import type { MigrationDialectAdapter } from './migration-dialect.adapter.js';
+export declare class PostgresMigrationDialectAdapter implements MigrationDialectAdapter {
+    readonly driver = "postgres";
+    buildJsonExpression(columnRef: string, locale: string): string;
+    extractJsonExpression(columnRef: string, locale: string): string;
+    setNotNullExpression(qualifiedTable: string, columnRef: string): string;
+}

package/dist/migration/postgres-migration.adapter.js

@@ -0,0 +1,17 @@
+export class PostgresMigrationDialectAdapter {
+    constructor() {
+        this.driver = 'postgres';
+    }
+    buildJsonExpression(columnRef, locale) {
+        return `jsonb_build_object('${escapeLiteral(locale)}', ${columnRef})`;
+    }
+    extractJsonExpression(columnRef, locale) {
+        return `${columnRef} ->> '${escapeLiteral(locale)}'`;
+    }
+    setNotNullExpression(qualifiedTable, columnRef) {
+        return `ALTER TABLE ${qualifiedTable} ALTER COLUMN ${columnRef} SET NOT NULL`;
+    }
+}
+function escapeLiteral(value) {
+    return value.replace(/'/g, "''");
+}

package/dist/migration/translatable-migration.generator.d.ts

@@ -0,0 +1,14 @@
+import type { TranslatableMigrationOptions, TranslatableMigrationPlan } from '../types.js';
+/**
+ * Diffs entities decorated with `@TranslatableColumn()` against the real
+ * database schema and computes the migration needed to bring the two in
+ * sync without losing data. Read-only: performs no writes to the database
+ * or the filesystem.
+ */
+export declare function planTranslatableMigrations(options: TranslatableMigrationOptions): Promise<TranslatableMigrationPlan>;
+/**
+ * Plans the migration (see {@link planTranslatableMigrations}) and, unless
+ * `dryRun` is set or there is nothing to migrate, writes it to a TypeORM
+ * migration file under `outputDir`.
+ */
+export declare function generateTranslatableMigrations(options: TranslatableMigrationOptions): Promise<TranslatableMigrationPlan>;

package/dist/migration/translatable-migration.generator.js

@@ -0,0 +1,173 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getTranslatableColumns } from '../metadata/translation-metadata.storage.js';
+import { MysqlMigrationDialectAdapter } from './mysql-migration.adapter.js';
+import { PostgresMigrationDialectAdapter } from './postgres-migration.adapter.js';
+import { renderMigrationFile } from './migration-template.js';
+const adapters = [
+    new PostgresMigrationDialectAdapter(),
+    new MysqlMigrationDialectAdapter(),
+];
+/**
+ * Diffs entities decorated with `@TranslatableColumn()` against the real
+ * database schema and computes the migration needed to bring the two in
+ * sync without losing data. Read-only: performs no writes to the database
+ * or the filesystem.
+ */
+export async function planTranslatableMigrations(options) {
+    const { dataSource } = options;
+    const adapter = getAdapter(normalizeDriverType(dataSource.options.type));
+    const initializedByUs = !dataSource.isInitialized;
+    if (initializedByUs)
+        await dataSource.initialize();
+    const queryRunner = dataSource.createQueryRunner();
+    await queryRunner.connect();
+    try {
+        const entityMetadatas = resolveEntityMetadatas(dataSource, options.entities);
+        const columns = [];
+        const upStatements = [];
+        const downStatements = [];
+        for (const entityMetadata of sortByTableName(entityMetadatas)) {
+            if (typeof entityMetadata.target === 'string')
+                continue;
+            const translatableColumns = sortByPropertyKey(getTranslatableColumns(entityMetadata.target));
+            if (translatableColumns.length === 0)
+                continue;
+            const table = await queryRunner.getTable(entityMetadata.tableName);
+            if (!table) {
+                for (const columnMeta of translatableColumns) {
+                    columns.push({
+                        table: entityMetadata.tableName,
+                        column: String(columnMeta.propertyKey),
+                        action: 'skip',
+                        reason: 'table does not exist yet',
+                    });
+                }
+                continue;
+            }
+            const qualifiedTable = dataSource.driver.escape(entityMetadata.tableName);
+            for (const columnMeta of translatableColumns) {
+                const propertyName = String(columnMeta.propertyKey);
+                const entityColumn = entityMetadata.findColumnWithPropertyName(propertyName);
+                if (!entityColumn)
+                    continue;
+                const dbColumnName = entityColumn.databaseName;
+                const columnRef = dataSource.driver.escape(dbColumnName);
+                const declaredType = dataSource.driver.normalizeType(entityColumn);
+                const existingColumn = table.findColumnByName(dbColumnName);
+                if (!existingColumn) {
+                    // Adding a NOT NULL column outright fails on Postgres/MySQL when the
+                    // table already has rows, unless a DEFAULT lets existing rows be
+                    // backfilled automatically. So the column is always added nullable
+                    // first, and NOT NULL is only enforced afterwards when a default
+                    // guarantees every row already has a value.
+                    const defaultExpr = dataSource.driver.normalizeDefault(entityColumn);
+                    const defaultClause = defaultExpr !== undefined ? ` DEFAULT ${defaultExpr}` : '';
+                    const canEnforceNotNull = !entityColumn.isNullable && defaultExpr !== undefined;
+                    upStatements.push(`ALTER TABLE ${qualifiedTable} ADD ${columnRef} ${declaredType}${defaultClause}`);
+                    if (canEnforceNotNull) {
+                        upStatements.push(adapter.setNotNullExpression(qualifiedTable, columnRef, declaredType));
+                    }
+                    downStatements.push(`ALTER TABLE ${qualifiedTable} DROP COLUMN ${columnRef}`);
+                    columns.push({
+                        table: entityMetadata.tableName,
+                        column: dbColumnName,
+                        action: 'create',
+                        ...(!entityColumn.isNullable && !canEnforceNotNull
+                            ? {
+                                reason: 'added as nullable: declaring NOT NULL without a column default cannot be enforced safely on a table that may already have rows',
+                            }
+                            : {}),
+                    });
+                    continue;
+                }
+                if (existingColumn.type.toLowerCase() === declaredType.toLowerCase()) {
+                    columns.push({
+                        table: entityMetadata.tableName,
+                        column: dbColumnName,
+                        action: 'skip',
+                        reason: 'already the declared JSON type',
+                    });
+                    continue;
+                }
+                const sourceLocale = columnMeta.sourceLocale ?? options.defaultLocale;
+                const tmpColumnRef = dataSource.driver.escape(`${dbColumnName}__translatable_tmp`);
+                const originalFullType = dataSource.driver.createFullType(existingColumn);
+                // The temp column is always added nullable, backfilled, then (if the
+                // declared/original column is NOT NULL) locked down afterwards -- an
+                // ALTER ... ADD COLUMN ... NOT NULL fails outright on a non-empty
+                // table without a default.
+                upStatements.push(`ALTER TABLE ${qualifiedTable} ADD ${tmpColumnRef} ${declaredType}`, `UPDATE ${qualifiedTable} SET ${tmpColumnRef} = ${adapter.buildJsonExpression(columnRef, sourceLocale)}`);
+                if (!entityColumn.isNullable) {
+                    upStatements.push(adapter.setNotNullExpression(qualifiedTable, tmpColumnRef, declaredType));
+                }
+                upStatements.push(`ALTER TABLE ${qualifiedTable} DROP COLUMN ${columnRef}`, `ALTER TABLE ${qualifiedTable} RENAME COLUMN ${tmpColumnRef} TO ${columnRef}`);
+                downStatements.push(`ALTER TABLE ${qualifiedTable} ADD ${tmpColumnRef} ${originalFullType}`, `UPDATE ${qualifiedTable} SET ${tmpColumnRef} = ${adapter.extractJsonExpression(columnRef, sourceLocale)}`);
+                if (!existingColumn.isNullable) {
+                    downStatements.push(adapter.setNotNullExpression(qualifiedTable, tmpColumnRef, originalFullType));
+                }
+                downStatements.push(`ALTER TABLE ${qualifiedTable} DROP COLUMN ${columnRef}`, `ALTER TABLE ${qualifiedTable} RENAME COLUMN ${tmpColumnRef} TO ${columnRef}`);
+                columns.push({
+                    table: entityMetadata.tableName,
+                    column: dbColumnName,
+                    action: 'convert',
+                    sourceLocale,
+                });
+            }
+        }
+        const timestamp = Date.now();
+        const baseName = options.name ?? 'TranslatableColumns';
+        return {
+            className: `${baseName}${timestamp}`,
+            fileName: `${timestamp}-${baseName}.ts`,
+            upStatements,
+            downStatements,
+            columns,
+            written: false,
+        };
+    }
+    finally {
+        await queryRunner.release();
+        if (initializedByUs)
+            await dataSource.destroy();
+    }
+}
+/**
+ * Plans the migration (see {@link planTranslatableMigrations}) and, unless
+ * `dryRun` is set or there is nothing to migrate, writes it to a TypeORM
+ * migration file under `outputDir`.
+ */
+export async function generateTranslatableMigrations(options) {
+    const plan = await planTranslatableMigrations(options);
+    if (options.dryRun || plan.upStatements.length === 0)
+        return plan;
+    const driverType = normalizeDriverType(options.dataSource.options.type);
+    const outputDir = options.outputDir ?? './migrations';
+    const filePath = path.join(outputDir, plan.fileName);
+    const contents = renderMigrationFile(plan.className, plan.upStatements, plan.downStatements, driverType);
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.writeFile(filePath, contents, 'utf8');
+    return { ...plan, filePath, written: true };
+}
+function resolveEntityMetadatas(dataSource, entities) {
+    if (!entities)
+        return dataSource.entityMetadatas;
+    const targets = new Set(entities);
+    return dataSource.entityMetadatas.filter((metadata) => targets.has(metadata.target));
+}
+function sortByTableName(entityMetadatas) {
+    return [...entityMetadatas].sort((a, b) => a.tableName.localeCompare(b.tableName));
+}
+function sortByPropertyKey(columns) {
+    return [...columns].sort((a, b) => String(a.propertyKey).localeCompare(String(b.propertyKey)));
+}
+function normalizeDriverType(type) {
+    return type === 'mariadb' ? 'mysql' : type;
+}
+function getAdapter(driver) {
+    const adapter = adapters.find((candidate) => candidate.driver === driver);
+    if (!adapter) {
+        throw new Error(`Translatable migration generation is not supported for driver "${driver}".`);
+    }
+    return adapter;
+}

package/dist/query/mysql-query.adapter.d.ts

@@ -0,0 +1,6 @@
+import type { LocalizedExpressionOptions } from '../types.js';
+import type { TranslationQueryAdapter } from './translation-query.adapter.js';
+export declare class MysqlTranslationQueryAdapter implements TranslationQueryAdapter {
+    readonly driver = "mysql";
+    localizedExpression(options: Required<LocalizedExpressionOptions>, parameters: Record<string, unknown>, paramPrefix: string): string;
+}

package/dist/query/mysql-query.adapter.js

@@ -0,0 +1,12 @@
+export class MysqlTranslationQueryAdapter {
+    constructor() {
+        this.driver = 'mysql';
+    }
+    localizedExpression(options, parameters, paramPrefix) {
+        const localeParam = `${paramPrefix}LocalePath`;
+        const fallbackParam = `${paramPrefix}FallbackLocalePath`;
+        parameters[localeParam] = `$.${options.locale}`;
+        parameters[fallbackParam] = `$.${options.fallbackLocale}`;
+        return `COALESCE(JSON_UNQUOTE(JSON_EXTRACT(${options.alias}.${options.property}, :${localeParam})), JSON_UNQUOTE(JSON_EXTRACT(${options.alias}.${options.property}, :${fallbackParam})))`;
+    }
+}

package/dist/query/postgres-query.adapter.d.ts

@@ -0,0 +1,6 @@
+import type { LocalizedExpressionOptions } from '../types.js';
+import type { TranslationQueryAdapter } from './translation-query.adapter.js';
+export declare class PostgresTranslationQueryAdapter implements TranslationQueryAdapter {
+    readonly driver = "postgres";
+    localizedExpression(options: Required<LocalizedExpressionOptions>, parameters: Record<string, unknown>, paramPrefix: string): string;
+}

package/dist/query/postgres-query.adapter.js

@@ -0,0 +1,12 @@
+export class PostgresTranslationQueryAdapter {
+    constructor() {
+        this.driver = 'postgres';
+    }
+    localizedExpression(options, parameters, paramPrefix) {
+        const localeParam = `${paramPrefix}Locale`;
+        const fallbackParam = `${paramPrefix}FallbackLocale`;
+        parameters[localeParam] = options.locale;
+        parameters[fallbackParam] = options.fallbackLocale;
+        return `COALESCE(${options.alias}.${options.property} ->> :${localeParam}, ${options.alias}.${options.property} ->> :${fallbackParam})`;
+    }
+}

package/dist/query/translation-query.adapter.d.ts

@@ -0,0 +1,5 @@
+import type { LocalizedExpressionOptions } from '../types.js';
+export interface TranslationQueryAdapter {
+    readonly driver: string;
+    localizedExpression(options: Required<LocalizedExpressionOptions>, parameters: Record<string, unknown>, paramPrefix: string): string;
+}

package/dist/query/translation-query.adapter.js

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

package/dist/query/translation-query.service.d.ts

@@ -0,0 +1,15 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { TranslationContextService } from '../context/translation-context.service.js';
+import type { LocalizedExpressionOptions } from '../types.js';
+export declare class TranslationQueryService {
+    private readonly context;
+    private readonly adapters;
+    private paramCounter;
+    constructor(context: TranslationContextService);
+    addSelect<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, options: LocalizedExpressionOptions, outputAlias: string): SelectQueryBuilder<Entity>;
+    orderBy<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, options: LocalizedExpressionOptions, direction?: 'ASC' | 'DESC'): SelectQueryBuilder<Entity>;
+    private nextParamPrefix;
+    private withDefaults;
+    private getAdapter;
+    private assertIdentifier;
+}

package/dist/query/translation-query.service.js

@@ -0,0 +1,69 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { TranslationContextService } from '../context/translation-context.service.js';
+import { MysqlTranslationQueryAdapter } from './mysql-query.adapter.js';
+import { PostgresTranslationQueryAdapter } from './postgres-query.adapter.js';
+let TranslationQueryService = class TranslationQueryService {
+    constructor(context) {
+        this.context = context;
+        this.adapters = [
+            new PostgresTranslationQueryAdapter(),
+            new MysqlTranslationQueryAdapter(),
+        ];
+        this.paramCounter = 0;
+    }
+    addSelect(builder, options, outputAlias) {
+        const parameters = {};
+        const adapter = this.getAdapter(builder.connection.options.type);
+        const expression = adapter.localizedExpression(this.withDefaults(options), parameters, this.nextParamPrefix(options));
+        return builder.addSelect(expression, outputAlias).setParameters(parameters);
+    }
+    orderBy(builder, options, direction = 'ASC') {
+        const parameters = {};
+        const adapter = this.getAdapter(builder.connection.options.type);
+        const expression = adapter.localizedExpression(this.withDefaults(options), parameters, this.nextParamPrefix(options));
+        return builder.addOrderBy(expression, direction).setParameters(parameters);
+    }
+    nextParamPrefix(options) {
+        return `translation_${options.alias}_${options.property}_${this.paramCounter++}`;
+    }
+    withDefaults(options) {
+        this.assertIdentifier(options.alias);
+        this.assertIdentifier(options.property);
+        return {
+            ...options,
+            locale: options.locale ?? this.context.locale,
+            fallbackLocale: options.fallbackLocale ?? this.context.fallbackLocale,
+        };
+    }
+    getAdapter(driver) {
+        const normalized = driver === 'mariadb' ? 'mysql' : driver;
+        const adapter = this.adapters.find((candidate) => candidate.driver === normalized);
+        if (!adapter) {
+            throw new Error(`Translation SQL expressions are not supported for driver "${driver}".`);
+        }
+        return adapter;
+    }
+    assertIdentifier(identifier) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+            throw new Error(`Unsafe SQL identifier "${identifier}".`);
+        }
+    }
+};
+TranslationQueryService = __decorate([
+    Injectable(),
+    __param(0, Inject(TranslationContextService)),
+    __metadata("design:paramtypes", [TranslationContextService])
+], TranslationQueryService);
+export { TranslationQueryService };

package/dist/services/translation.service.d.ts

@@ -0,0 +1,15 @@
+import { TranslationContextService } from '../context/translation-context.service.js';
+import type { TranslatableModuleOptions, TranslationFallbackStrategy, TranslationMap } from '../types.js';
+export declare class TranslationService {
+    private readonly options;
+    private readonly context;
+    constructor(options: TranslatableModuleOptions, context: TranslationContextService);
+    resolve<T>(value: TranslationMap<T> | T | null | undefined, locale?: string, fallbackLocale?: string, strategy?: TranslationFallbackStrategy): T | null;
+    set<T extends object, V>(entity: T, property: keyof T, locale: string, value: V | null): T;
+    setMany<T extends object, V>(entity: T, property: keyof T, values: TranslationMap<V>): T;
+    remove<T extends object>(entity: T, property: keyof T, locale: string): T;
+    private handleMissing;
+    private assertSupportedLocale;
+    private assertTranslatable;
+    private assertTranslationMap;
+}

package/dist/services/translation.service.js

@@ -0,0 +1,109 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { TRANSLATABLE_MODULE_OPTIONS } from '../constants.js';
+import { TranslationContextService } from '../context/translation-context.service.js';
+import { getTranslatableColumns } from '../metadata/translation-metadata.storage.js';
+let TranslationService = class TranslationService {
+    constructor(options, context) {
+        this.options = options;
+        this.context = context;
+    }
+    resolve(value, locale = this.context.locale, fallbackLocale = this.context.fallbackLocale, strategy = this.options.fallbackStrategy ?? 'default-locale') {
+        if (value == null)
+            return null;
+        if (typeof value !== 'object' || Array.isArray(value))
+            return value;
+        const translations = value;
+        const baseLocale = locale.split('-')[0];
+        const candidates = [
+            locale,
+            baseLocale !== locale ? baseLocale : undefined,
+            fallbackLocale,
+            this.options.defaultLocale,
+        ].filter((item) => Boolean(item));
+        for (const candidate of candidates) {
+            const translated = translations[candidate];
+            if (translated != null)
+                return translated;
+        }
+        return this.handleMissing(translations, strategy, locale);
+    }
+    set(entity, property, locale, value) {
+        this.assertSupportedLocale(locale);
+        this.assertTranslatable(entity, property);
+        const existing = this.assertTranslationMap(entity, property);
+        const translations = existing ? { ...existing } : {};
+        Object.assign(translations, { [locale]: value });
+        entity[property] = translations;
+        return entity;
+    }
+    setMany(entity, property, values) {
+        for (const [locale, value] of Object.entries(values)) {
+            this.set(entity, property, locale, value);
+        }
+        return entity;
+    }
+    remove(entity, property, locale) {
+        this.assertTranslatable(entity, property);
+        const current = this.assertTranslationMap(entity, property);
+        if (current) {
+            const copy = { ...current };
+            delete copy[locale];
+            entity[property] = copy;
+        }
+        return entity;
+    }
+    handleMissing(translations, strategy, locale) {
+        if (strategy === 'first-available') {
+            return Object.values(translations).find((item) => item != null) ?? null;
+        }
+        if (strategy === 'throw') {
+            throw new Error(`No translation is available for locale "${locale}".`);
+        }
+        return null;
+    }
+    assertSupportedLocale(locale) {
+        if (this.options.strictLocales !== false && !this.options.supportedLocales.includes(locale)) {
+            throw new Error(`Unsupported locale "${locale}".`);
+        }
+        if (locale.includes('.') || locale.includes('$')) {
+            throw new Error(`Locale "${locale}" contains unsafe database path characters.`);
+        }
+    }
+    assertTranslatable(entity, property) {
+        const fields = getTranslatableColumns(entity.constructor);
+        if (!fields.some((field) => field.propertyKey === property)) {
+            throw new Error(`Property "${String(property)}" is not translatable.`);
+        }
+    }
+    assertTranslationMap(entity, property) {
+        const existing = entity[property];
+        if (existing == null)
+            return undefined;
+        if (typeof existing === 'object' && !Array.isArray(existing)) {
+            return existing;
+        }
+        throw new Error(`Property "${String(property)}" no longer holds a translation map (found a ` +
+            `${typeof existing}). This usually means the entity was already localized ` +
+            '(for example by TranslationResponseTransformer with mutateResponses enabled) ' +
+            'before being reused; re-fetch the entity before calling set/remove.');
+    }
+};
+TranslationService = __decorate([
+    Injectable(),
+    __param(0, Inject(TRANSLATABLE_MODULE_OPTIONS)),
+    __param(1, Inject(TranslationContextService)),
+    __metadata("design:paramtypes", [Object, TranslationContextService])
+], TranslationService);
+export { TranslationService };

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,21 @@
+import { type TranslationMap } from '../index.js';
+export declare class BaseFixture {
+    name: TranslationMap;
+}
+export declare class ProductFixture extends BaseFixture {
+    details: TranslationMap;
+    price: number;
+}
+export declare class LegacyFixture {
+    name: TranslationMap;
+    description: TranslationMap;
+}
+export declare class ProductResponseDto {
+    id: string;
+    name: unknown;
+    price: string;
+}
+export declare class PaginatedDto {
+    data: ProductResponseDto[];
+    meta: unknown;
+}

package/dist/testing/fixtures.js

@@ -0,0 +1,53 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { TranslatableColumn, TranslatableProperty } from '../index.js';
+export class BaseFixture {
+}
+__decorate([
+    TranslatableColumn({ column: { type: 'jsonb', nullable: true } }),
+    __metadata("design:type", Object)
+], BaseFixture.prototype, "name", void 0);
+export class ProductFixture extends BaseFixture {
+    constructor() {
+        super(...arguments);
+        this.price = 10;
+    }
+}
+__decorate([
+    TranslatableColumn({
+        column: { type: 'jsonb', nullable: true },
+        translation: { fallbackLocale: 'fr' },
+    }),
+    __metadata("design:type", Object)
+], ProductFixture.prototype, "details", void 0);
+export class LegacyFixture {
+}
+__decorate([
+    TranslatableColumn({ column: { type: 'jsonb', nullable: false } }),
+    __metadata("design:type", Object)
+], LegacyFixture.prototype, "name", void 0);
+__decorate([
+    TranslatableColumn({
+        column: { type: 'jsonb', nullable: true },
+        translation: { sourceLocale: 'de' },
+    }),
+    __metadata("design:type", Object)
+], LegacyFixture.prototype, "description", void 0);
+// Stands in for a nestjs-paginate / Swagger response DTO: a class distinct
+// from the TypeORM entity, constructed by a mapper or class-transformer
+// rather than hydrated by TypeORM.
+export class ProductResponseDto {
+}
+__decorate([
+    TranslatableProperty({ fallbackLocale: 'fr' }),
+    __metadata("design:type", Object)
+], ProductResponseDto.prototype, "name", void 0);
+export class PaginatedDto {
+}

package/dist/transformers/translation-response.transformer.d.ts

@@ -0,0 +1,11 @@
+import { TranslationContextService } from '../context/translation-context.service.js';
+import { TranslationService } from '../services/translation.service.js';
+import type { TranslatableModuleOptions, TranslationResponseMode } from '../types.js';
+export declare class TranslationResponseTransformer {
+    private readonly options;
+    private readonly context;
+    private readonly translations;
+    constructor(options: TranslatableModuleOptions, context: TranslationContextService, translations: TranslationService);
+    transform<T>(value: T, mode?: TranslationResponseMode, locale?: string): T;
+    private visit;
+}