@nestjs-dash/translation 0.2.0

package/README.md

@@ -0,0 +1,131 @@
+# @nestjs-dash/translation
+
+Database-aware translatable JSON columns for NestJS and TypeORM, inspired by Laravel Translatable.
+Stores every locale of a field in a single JSON/JSONB column (`{ "en": "...", "nl": "...", "fr": "..." }`)
+instead of duplicating columns (`name_en`, `name_nl`) or maintaining separate translation tables, and
+automatically resolves the right locale per request.
+
+Ported from the standalone [`nestjs-translatable`](https://github.com/M0D1xD/nestjs-translatable)
+package. This package has no dependency on the admin panel — pairing it with `@nestjs-dash/core`'s
+`translatableInput()`/`translatableColumn()` form/table helpers (see
+[Admin panel integration](#admin-panel-integration)) is optional.
+
+## Install
+
+```bash
+pnpm add @nestjs-dash/translation
+```
+
+Requires `@nestjs/common`, `@nestjs/core`, `reflect-metadata`, `rxjs`, and `typeorm` as peers.
+
+## Module setup
+
+```ts
+import { Module } from '@nestjs/common';
+import { TranslatableModule } from '@nestjs-dash/translation';
+
+@Module({
+  imports: [
+    TranslatableModule.forRoot({
+      defaultLocale: 'en',
+      fallbackLocale: 'en',
+      supportedLocales: ['en', 'nl', 'fr'],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot()`/`forRootAsync()` register globally: a middleware resolves the request's locale
+(`?lang=`, `x-language` header, `Accept-Language`, or a custom `localeResolvers` entry) and a global
+interceptor localizes responses. Only call it once, in your root module.
+
+## Entities
+
+```ts
+import { TranslatableColumn, TranslationMap } from '@nestjs-dash/translation';
+
+@Entity('products')
+export class ProductEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @TranslatableColumn('jsonb') // 'json' for MySQL/MariaDB, omit the type for MongoDB
+  details: TranslationMap;
+}
+```
+
+A `GET` request with `?lang=nl` turns `{ "en": "...", "nl": "..." }` into the plain string `"..."`
+in the response automatically. Use `@RawTranslations()` on a route to get the untouched map instead,
+`@TranslationsWithRaw()` for both, or `@SkipTranslation()` to disable localization for that route.
+
+## Writing translations
+
+```ts
+constructor(private readonly translations: TranslationService) {}
+
+async setDutch(id: string, value: string) {
+  const product = await this.products.findOneByOrFail({ id });
+  this.translations.set(product, 'details', 'nl', value);
+  return this.products.save(product);
+}
+```
+
+`TranslationService.set`/`setMany`/`remove` write one locale at a time without clobbering the
+others, validate the locale against `supportedLocales`, and reject `.`/`$` (unsafe for MongoDB
+embedded-document paths).
+
+## Sorting and filtering by translated value in SQL
+
+```ts
+const query = this.products.createQueryBuilder('product');
+this.translationQuery.orderBy(query, { alias: 'product', property: 'details' });
+```
+
+`TranslationQueryService` picks the right adapter (Postgres `->>`/`COALESCE`, MySQL
+`JSON_EXTRACT`/`COALESCE`) based on the query builder's connection, parameterizes locale values, and
+validates `alias`/`property` as safe SQL identifiers before building the expression.
+
+## Migrating existing scalar columns
+
+```bash
+npx nestjs-dash-translation migration:generate \
+  --data-source ./dist/data-source.js \
+  --locales en,nl,fr \
+  --default-locale en \
+  --output ./migrations
+```
+
+Backfills each existing scalar value into the JSON column under one locale key before converting
+the column type — see `generateTranslatableMigrations`/`planTranslatableMigrations` for the
+programmatic API.
+
+## Admin panel integration
+
+`@nestjs-dash/core` ships two generic helpers for building resource forms/tables around any
+locale-keyed JSON column (`translatable-field.ts`) — not specific to this package, but exactly what
+a `@TranslatableColumn()` value needs:
+
+```ts
+import { translatableColumn, translatableInput } from '@nestjs-dash/core';
+
+static override form(form: Schema) {
+  return form.components([
+    translatableInput('details', ['en', 'nl', 'fr']),
+  ]);
+}
+
+static override table(table: Table) {
+  return table.columns([
+    translatableColumn('details', 'en'), // shows the fixed 'en' value in the list view
+  ]);
+}
+```
+
+`translatableInput` renders one tab per locale (each a `TextInput.make(name).json(locale)` under
+the hood — see `.json(property)` on `TextInput`/`Textarea`), so editing any subset of locales and
+saving never clobbers the others. `translatableColumn` projects one fixed, author-chosen locale
+into a list column — there's no per-request "current admin locale" concept, so pick the locale a
+list view should always display.
+
+See `examples/translation` for a runnable end-to-end demo against both Postgres and MySQL.

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const TRANSLATABLE_MODULE_OPTIONS: unique symbol;
+export declare const TRANSLATABLE_COLUMNS_METADATA: unique symbol;
+export declare const TRANSLATION_ROUTE_OPTIONS: unique symbol;

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const TRANSLATABLE_MODULE_OPTIONS = Symbol('TRANSLATABLE_MODULE_OPTIONS');
+export const TRANSLATABLE_COLUMNS_METADATA = Symbol('TRANSLATABLE_COLUMNS_METADATA');
+export const TRANSLATION_ROUTE_OPTIONS = Symbol('TRANSLATION_ROUTE_OPTIONS');

package/dist/context/translation-context.middleware.d.ts

@@ -0,0 +1,12 @@
+import { type NestMiddleware } from '@nestjs/common';
+import type { NextFunction, Request, Response } from 'express';
+import type { TranslatableModuleOptions } from '../types.js';
+import { TranslationContextService } from './translation-context.service.js';
+export declare class TranslationContextMiddleware implements NestMiddleware {
+    private readonly options;
+    private readonly context;
+    constructor(options: TranslatableModuleOptions, context: TranslationContextService);
+    use(request: Request, _response: Response, next: NextFunction): void;
+    private resolveLocale;
+    private normalize;
+}

package/dist/context/translation-context.middleware.js

@@ -0,0 +1,66 @@
+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 './translation-context.service.js';
+let TranslationContextMiddleware = class TranslationContextMiddleware {
+    constructor(options, context) {
+        this.options = options;
+        this.context = context;
+    }
+    use(request, _response, next) {
+        const locale = this.resolveLocale(request);
+        Object.assign(request, { translationContext: this.context });
+        this.context.run({
+            locale,
+            fallbackLocale: this.options.fallbackLocale ?? this.options.defaultLocale,
+            responseMode: this.options.responseMode ?? 'localized',
+        }, next);
+    }
+    resolveLocale(request) {
+        const custom = this.options.localeResolvers
+            ?.map((resolver) => resolver.resolve({
+            query: request.query,
+            headers: request.headers,
+        }))
+            .find(Boolean);
+        const queryName = this.options.queryParameter ?? 'lang';
+        const headerName = (this.options.headerName ?? 'x-language').toLowerCase();
+        const queryLocale = typeof request.query[queryName] === 'string' ? request.query[queryName] : undefined;
+        const headerValue = request.headers[headerName];
+        const headerLocale = typeof headerValue === 'string' ? headerValue : undefined;
+        const accepted = request.acceptsLanguages()?.[0];
+        const acceptedLocale = accepted && accepted !== '*' ? accepted : undefined;
+        const candidate = custom ?? queryLocale ?? headerLocale ?? acceptedLocale;
+        return this.normalize(candidate);
+    }
+    normalize(candidate) {
+        if (!candidate)
+            return this.options.defaultLocale;
+        const exact = this.options.supportedLocales.find((locale) => locale.toLowerCase() === candidate.toLowerCase());
+        if (exact)
+            return exact;
+        const base = candidate.split('-')[0];
+        const baseMatch = this.options.supportedLocales.find((locale) => locale.toLowerCase() === base?.toLowerCase());
+        if (baseMatch)
+            return baseMatch;
+        return this.options.strictLocales === false ? candidate : this.options.defaultLocale;
+    }
+};
+TranslationContextMiddleware = __decorate([
+    Injectable(),
+    __param(0, Inject(TRANSLATABLE_MODULE_OPTIONS)),
+    __param(1, Inject(TranslationContextService)),
+    __metadata("design:paramtypes", [Object, TranslationContextService])
+], TranslationContextMiddleware);
+export { TranslationContextMiddleware };

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

@@ -0,0 +1,17 @@
+import type { TranslatableModuleOptions, TranslationRequestContext, TranslationResponseMode } from '../types.js';
+/**
+ * Fallback for code paths that need a default locale before any
+ * TranslationContextService instance is reachable (e.g. a request that
+ * never passed through TranslationContextMiddleware). Reflects the
+ * defaultLocale of the most recently bootstrapped TranslatableModule.
+ */
+export declare function getConfiguredDefaultLocale(): string;
+export declare class TranslationContextService {
+    private readonly options;
+    private readonly storage;
+    constructor(options: TranslatableModuleOptions);
+    run<T>(context: TranslationRequestContext, callback: () => T): T;
+    get locale(): string;
+    get fallbackLocale(): string;
+    get responseMode(): TranslationResponseMode;
+}

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

@@ -0,0 +1,52 @@
+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 { AsyncLocalStorage } from 'node:async_hooks';
+import { TRANSLATABLE_MODULE_OPTIONS } from '../constants.js';
+let lastConfiguredDefaultLocale;
+/**
+ * Fallback for code paths that need a default locale before any
+ * TranslationContextService instance is reachable (e.g. a request that
+ * never passed through TranslationContextMiddleware). Reflects the
+ * defaultLocale of the most recently bootstrapped TranslatableModule.
+ */
+export function getConfiguredDefaultLocale() {
+    return lastConfiguredDefaultLocale ?? 'en';
+}
+let TranslationContextService = class TranslationContextService {
+    constructor(options) {
+        this.options = options;
+        this.storage = new AsyncLocalStorage();
+        lastConfiguredDefaultLocale = options.defaultLocale;
+    }
+    run(context, callback) {
+        return this.storage.run(context, callback);
+    }
+    get locale() {
+        return this.storage.getStore()?.locale ?? this.options.defaultLocale;
+    }
+    get fallbackLocale() {
+        return (this.storage.getStore()?.fallbackLocale ??
+            this.options.fallbackLocale ??
+            this.options.defaultLocale);
+    }
+    get responseMode() {
+        return this.storage.getStore()?.responseMode ?? this.options.responseMode ?? 'localized';
+    }
+};
+TranslationContextService = __decorate([
+    Injectable(),
+    __param(0, Inject(TRANSLATABLE_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], TranslationContextService);
+export { TranslationContextService };

package/dist/decorators/locale.decorator.d.ts

@@ -0,0 +1 @@
+export declare const Locale: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/locale.decorator.js

@@ -0,0 +1,6 @@
+import { createParamDecorator } from '@nestjs/common';
+import { getConfiguredDefaultLocale, } from '../context/translation-context.service.js';
+export const Locale = createParamDecorator((_data, context) => {
+    const request = context.switchToHttp().getRequest();
+    return request.translationContext?.locale ?? getConfiguredDefaultLocale();
+});

package/dist/decorators/response.decorator.d.ts

@@ -0,0 +1,7 @@
+import { TRANSLATION_ROUTE_OPTIONS } from '../constants.js';
+import type { TranslationRouteOptions } from '../types.js';
+export declare const TranslationResponse: (options: TranslationRouteOptions) => import("@nestjs/common").CustomDecorator<typeof TRANSLATION_ROUTE_OPTIONS>;
+export declare const SkipTranslation: () => import("@nestjs/common").CustomDecorator<typeof TRANSLATION_ROUTE_OPTIONS>;
+export declare const RawTranslations: () => import("@nestjs/common").CustomDecorator<typeof TRANSLATION_ROUTE_OPTIONS>;
+export declare const LocalizedTranslations: () => import("@nestjs/common").CustomDecorator<typeof TRANSLATION_ROUTE_OPTIONS>;
+export declare const TranslationsWithRaw: () => import("@nestjs/common").CustomDecorator<typeof TRANSLATION_ROUTE_OPTIONS>;

package/dist/decorators/response.decorator.js

@@ -0,0 +1,7 @@
+import { SetMetadata } from '@nestjs/common';
+import { TRANSLATION_ROUTE_OPTIONS } from '../constants.js';
+export const TranslationResponse = (options) => SetMetadata(TRANSLATION_ROUTE_OPTIONS, options);
+export const SkipTranslation = () => TranslationResponse({ skip: true });
+export const RawTranslations = () => TranslationResponse({ mode: 'raw' });
+export const LocalizedTranslations = () => TranslationResponse({ mode: 'localized' });
+export const TranslationsWithRaw = () => TranslationResponse({ mode: 'both' });

package/dist/decorators/translatable-column.decorator.d.ts

@@ -0,0 +1,3 @@
+import type { TranslatableColumnOptions, TranslatableStorageType } from '../types.js';
+export declare function TranslatableColumn(type: TranslatableStorageType): PropertyDecorator;
+export declare function TranslatableColumn(options?: TranslatableColumnOptions): PropertyDecorator;

package/dist/decorators/translatable-column.decorator.js

@@ -0,0 +1,13 @@
+import { Column } from 'typeorm';
+import { registerTranslatableColumn } from '../metadata/translation-metadata.storage.js';
+export function TranslatableColumn(input = {}) {
+    const options = typeof input === 'string' ? { column: { type: input } } : input;
+    return (target, propertyKey) => {
+        const columnDecorator = options.column ? Column(options.column) : Column();
+        columnDecorator(target, propertyKey);
+        registerTranslatableColumn(target.constructor, {
+            propertyKey,
+            ...options.translation,
+        });
+    };
+}

package/dist/decorators/translatable-property.decorator.d.ts

@@ -0,0 +1,13 @@
+import type { TranslationBehaviorOptions } from '../types.js';
+/**
+ * Marks a property as translatable without composing TypeORM's `@Column()`.
+ *
+ * `@TranslatableColumn()` is for entity classes backed by a real database
+ * column. Use `@TranslatableProperty()` on plain DTO/response classes —
+ * e.g. a `nestjs-paginate` Swagger response type, or anything produced by
+ * `class-transformer`'s `plainToInstance()` — that carry a `TranslationMap`
+ * value but aren't the original entity, so `TranslationResponseTransformer`
+ * still recognizes and localizes them even though the entity's own
+ * `@TranslatableColumn()` metadata doesn't apply to that class.
+ */
+export declare function TranslatableProperty(options?: TranslationBehaviorOptions): PropertyDecorator;

package/dist/decorators/translatable-property.decorator.js

@@ -0,0 +1,20 @@
+import { registerTranslatableColumn } from '../metadata/translation-metadata.storage.js';
+/**
+ * Marks a property as translatable without composing TypeORM's `@Column()`.
+ *
+ * `@TranslatableColumn()` is for entity classes backed by a real database
+ * column. Use `@TranslatableProperty()` on plain DTO/response classes —
+ * e.g. a `nestjs-paginate` Swagger response type, or anything produced by
+ * `class-transformer`'s `plainToInstance()` — that carry a `TranslationMap`
+ * value but aren't the original entity, so `TranslationResponseTransformer`
+ * still recognizes and localizes them even though the entity's own
+ * `@TranslatableColumn()` metadata doesn't apply to that class.
+ */
+export function TranslatableProperty(options = {}) {
+    return (target, propertyKey) => {
+        registerTranslatableColumn(target.constructor, {
+            propertyKey,
+            ...options,
+        });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export * from './constants.js';
+export * from './context/translation-context.service.js';
+export * from './decorators/locale.decorator.js';
+export * from './decorators/response.decorator.js';
+export * from './decorators/translatable-column.decorator.js';
+export * from './decorators/translatable-property.decorator.js';
+export * from './interceptors/translation.interceptor.js';
+export * from './metadata/translation-metadata.storage.js';
+export * from './migration/cli-args.js';
+export * from './migration/migration-dialect.adapter.js';
+export * from './migration/migration-template.js';
+export * from './migration/mysql-migration.adapter.js';
+export * from './migration/postgres-migration.adapter.js';
+export * from './migration/translatable-migration.generator.js';
+export * from './query/mysql-query.adapter.js';
+export * from './query/postgres-query.adapter.js';
+export * from './query/translation-query.adapter.js';
+export * from './query/translation-query.service.js';
+export * from './services/translation.service.js';
+export * from './transformers/translation-response.transformer.js';
+export * from './translatable.module.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+export * from './constants.js';
+export * from './context/translation-context.service.js';
+export * from './decorators/locale.decorator.js';
+export * from './decorators/response.decorator.js';
+export * from './decorators/translatable-column.decorator.js';
+export * from './decorators/translatable-property.decorator.js';
+export * from './interceptors/translation.interceptor.js';
+export * from './metadata/translation-metadata.storage.js';
+export * from './migration/cli-args.js';
+export * from './migration/migration-dialect.adapter.js';
+export * from './migration/migration-template.js';
+export * from './migration/mysql-migration.adapter.js';
+export * from './migration/postgres-migration.adapter.js';
+export * from './migration/translatable-migration.generator.js';
+export * from './query/mysql-query.adapter.js';
+export * from './query/postgres-query.adapter.js';
+export * from './query/translation-query.adapter.js';
+export * from './query/translation-query.service.js';
+export * from './services/translation.service.js';
+export * from './transformers/translation-response.transformer.js';
+export * from './translatable.module.js';
+export * from './types.js';

package/dist/interceptors/translation.interceptor.d.ts

@@ -0,0 +1,12 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { type Observable } from 'rxjs';
+import { TranslationContextService } from '../context/translation-context.service.js';
+import { TranslationResponseTransformer } from '../transformers/translation-response.transformer.js';
+export declare class TranslationInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly transformer;
+    private readonly context;
+    constructor(reflector: Reflector, transformer: TranslationResponseTransformer, context: TranslationContextService);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}

package/dist/interceptors/translation.interceptor.js

@@ -0,0 +1,43 @@
+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 { Reflector } from '@nestjs/core';
+import { map } from 'rxjs';
+import { TRANSLATION_ROUTE_OPTIONS } from '../constants.js';
+import { TranslationContextService } from '../context/translation-context.service.js';
+import { TranslationResponseTransformer } from '../transformers/translation-response.transformer.js';
+let TranslationInterceptor = class TranslationInterceptor {
+    constructor(reflector, transformer, context) {
+        this.reflector = reflector;
+        this.transformer = transformer;
+        this.context = context;
+    }
+    intercept(context, next) {
+        const route = this.reflector.getAllAndOverride(TRANSLATION_ROUTE_OPTIONS, [context.getHandler(), context.getClass()]);
+        if (route?.skip)
+            return next.handle();
+        return next
+            .handle()
+            .pipe(map((value) => this.transformer.transform(value, route?.mode ?? this.context.responseMode, route?.locale ?? this.context.locale)));
+    }
+};
+TranslationInterceptor = __decorate([
+    Injectable(),
+    __param(0, Inject(Reflector)),
+    __param(1, Inject(TranslationResponseTransformer)),
+    __param(2, Inject(TranslationContextService)),
+    __metadata("design:paramtypes", [Reflector,
+        TranslationResponseTransformer,
+        TranslationContextService])
+], TranslationInterceptor);
+export { TranslationInterceptor };

package/dist/metadata/translation-metadata.storage.d.ts

@@ -0,0 +1,4 @@
+import type { TranslatableColumnMetadata } from '../types.js';
+export declare function registerTranslatableColumn(target: object, metadata: TranslatableColumnMetadata): void;
+export declare function getTranslatableColumns(target: object): TranslatableColumnMetadata[];
+export declare function isTranslatableEntity(target: object): boolean;

package/dist/metadata/translation-metadata.storage.js

@@ -0,0 +1,22 @@
+const storage = new WeakMap();
+export function registerTranslatableColumn(target, metadata) {
+    const fields = storage.get(target) ?? new Map();
+    fields.set(metadata.propertyKey, metadata);
+    storage.set(target, fields);
+}
+export function getTranslatableColumns(target) {
+    const merged = new Map();
+    let current = target;
+    while (current && current !== Function.prototype) {
+        const fields = storage.get(current);
+        fields?.forEach((value, key) => {
+            if (!merged.has(key))
+                merged.set(key, value);
+        });
+        current = Object.getPrototypeOf(current);
+    }
+    return [...merged.values()];
+}
+export function isTranslatableEntity(target) {
+    return getTranslatableColumns(target).length > 0;
+}

package/dist/migration/cli-args.d.ts

@@ -0,0 +1,12 @@
+export declare class CliUsageError extends Error {
+}
+export interface ParsedCliArgs {
+    command: string;
+    dataSourcePath: string;
+    supportedLocales: string[];
+    defaultLocale: string;
+    outputDir: string;
+    name: string;
+    dryRun: boolean;
+}
+export declare function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/migration/cli-args.js

@@ -0,0 +1,38 @@
+import { parseArgs } from 'node:util';
+export class CliUsageError extends Error {
+}
+export function parseCliArgs(argv) {
+    const [command, ...rest] = argv;
+    if (command !== 'migration:generate') {
+        throw new CliUsageError(`Unknown command "${command ?? ''}". Expected "migration:generate".`);
+    }
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            'data-source': { type: 'string', short: 'd' },
+            locales: { type: 'string', short: 'l' },
+            'default-locale': { type: 'string' },
+            output: { type: 'string', short: 'o', default: './migrations' },
+            name: { type: 'string', short: 'n', default: 'TranslatableColumns' },
+            'dry-run': { type: 'boolean', default: false },
+        },
+    });
+    if (!values['data-source'])
+        throw new CliUsageError('--data-source is required.');
+    if (!values.locales)
+        throw new CliUsageError('--locales is required.');
+    if (!values['default-locale'])
+        throw new CliUsageError('--default-locale is required.');
+    return {
+        command,
+        dataSourcePath: values['data-source'],
+        supportedLocales: values.locales
+            .split(',')
+            .map((locale) => locale.trim())
+            .filter(Boolean),
+        defaultLocale: values['default-locale'],
+        outputDir: values.output,
+        name: values.name,
+        dryRun: Boolean(values['dry-run']),
+    };
+}

package/dist/migration/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/migration/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DataSource } from 'typeorm';
+import { CliUsageError, parseCliArgs } from './cli-args.js';
+import { generateTranslatableMigrations } from './translatable-migration.generator.js';
+const USAGE = `
+Usage: nestjs-dash-translation migration:generate --data-source <path> --locales <csv> --default-locale <locale> [options]
+
+Options:
+  -d, --data-source <path>     Path to a compiled module exporting a TypeORM DataSource (required)
+  -l, --locales <csv>          Comma-separated list of supported locales (required)
+      --default-locale <code>  Default locale used to backfill existing scalar values (required)
+  -o, --output <dir>           Output directory for the migration file (default: ./migrations)
+  -n, --name <name>            Base name for the migration class/file (default: TranslatableColumns)
+      --dry-run                Compute the plan without writing a file
+`;
+async function main() {
+    const args = parseCliArgs(process.argv.slice(2));
+    const dataSource = await loadDataSource(args.dataSourcePath);
+    const plan = await generateTranslatableMigrations({
+        dataSource,
+        supportedLocales: args.supportedLocales,
+        defaultLocale: args.defaultLocale,
+        outputDir: args.outputDir,
+        name: args.name,
+        dryRun: args.dryRun,
+    });
+    for (const column of plan.columns) {
+        const detail = column.reason
+            ? ` (${column.reason})`
+            : column.sourceLocale
+                ? ` (source locale: ${column.sourceLocale})`
+                : '';
+        console.log(`  ${column.action.padEnd(7)} ${column.table}.${column.column}${detail}`);
+    }
+    if (plan.upStatements.length === 0) {
+        console.log('Nothing to migrate.');
+        return;
+    }
+    console.log(plan.written
+        ? `Migration written to ${plan.filePath}`
+        : `Dry run: would write ${plan.fileName}`);
+}
+async function loadDataSource(modulePath) {
+    const resolved = path.resolve(process.cwd(), modulePath);
+    const loaded = (await import(pathToFileURL(resolved).href));
+    const candidate = loaded.default ??
+        loaded.dataSource ??
+        Object.values(loaded).find((value) => value instanceof DataSource);
+    if (!(candidate instanceof DataSource)) {
+        throw new Error(`Could not find a DataSource export in "${modulePath}". Export it as ` +
+            '`export default dataSource` or `export const dataSource = ...`.');
+    }
+    return candidate;
+}
+main().catch((error) => {
+    if (error instanceof CliUsageError) {
+        console.error(error.message);
+        console.error(USAGE);
+    }
+    else {
+        console.error(error instanceof Error ? error.message : error);
+    }
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,12 @@
+export interface MigrationDialectAdapter {
+    readonly driver: string;
+    buildJsonExpression(columnRef: string, locale: string): string;
+    extractJsonExpression(columnRef: string, locale: string): string;
+    /**
+     * Statement that enforces NOT NULL on an already-populated column. Must be
+     * safe to run after the column has been backfilled — the two dialects use
+     * incompatible syntax (Postgres: `ALTER COLUMN ... SET NOT NULL`, MySQL:
+     * `MODIFY COLUMN ... <type> NOT NULL`).
+     */
+    setNotNullExpression(qualifiedTable: string, columnRef: string, columnType: string): string;
+}

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

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