@nestjs-dash/translation 0.2.0

package/dist/transformers/translation-response.transformer.js

@@ -0,0 +1,75 @@
+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';
+import { TranslationService } from '../services/translation.service.js';
+let TranslationResponseTransformer = class TranslationResponseTransformer {
+    constructor(options, context, translations) {
+        this.options = options;
+        this.context = context;
+        this.translations = translations;
+    }
+    transform(value, mode = this.context.responseMode, locale = this.context.locale) {
+        return this.visit(value, mode, locale, new WeakMap());
+    }
+    visit(value, mode, locale, seen) {
+        if (value == null || typeof value !== 'object')
+            return value;
+        if (value instanceof Date || Buffer.isBuffer(value) || value instanceof Promise) {
+            return value;
+        }
+        if (seen.has(value))
+            return seen.get(value);
+        if (Array.isArray(value)) {
+            const output = [];
+            seen.set(value, output);
+            value.forEach((item) => output.push(this.visit(item, mode, locale, seen)));
+            return output;
+        }
+        const source = value;
+        const output = this.options.mutateResponses ? source : {};
+        seen.set(value, output);
+        const columns = getTranslatableColumns(value.constructor);
+        const columnKeys = new Set(columns.map((column) => String(column.propertyKey)));
+        for (const [key, item] of Object.entries(source)) {
+            if (columnKeys.has(key))
+                continue;
+            output[key] = this.visit(item, mode, locale, seen);
+        }
+        for (const column of columns) {
+            const key = String(column.propertyKey);
+            const raw = source[key];
+            if (mode === 'raw') {
+                output[key] = this.visit(raw, mode, locale, seen);
+                continue;
+            }
+            const localized = this.translations.resolve(raw, locale, column.fallbackLocale ?? this.context.fallbackLocale, column.fallbackStrategy ?? this.options.fallbackStrategy);
+            if (mode === 'both') {
+                output[`${key}Translations`] = this.visit(raw, mode, locale, seen);
+            }
+            output[key] = localized;
+        }
+        return output;
+    }
+};
+TranslationResponseTransformer = __decorate([
+    Injectable(),
+    __param(0, Inject(TRANSLATABLE_MODULE_OPTIONS)),
+    __param(1, Inject(TranslationContextService)),
+    __param(2, Inject(TranslationService)),
+    __metadata("design:paramtypes", [Object, TranslationContextService,
+        TranslationService])
+], TranslationResponseTransformer);
+export { TranslationResponseTransformer };

package/dist/translatable.module.d.ts

@@ -0,0 +1,10 @@
+import { type DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
+import type { TranslatableModuleAsyncOptions, TranslatableModuleOptions } from './types.js';
+export declare class TranslatableModule implements NestModule {
+    private readonly _options;
+    constructor(_options: TranslatableModuleOptions);
+    static forRoot(options: TranslatableModuleOptions): DynamicModule;
+    static forRootAsync(options: TranslatableModuleAsyncOptions): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+    private static validate;
+}

package/dist/translatable.module.js

@@ -0,0 +1,108 @@
+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); }
+};
+var TranslatableModule_1;
+import { Inject, Module, } from '@nestjs/common';
+import { APP_INTERCEPTOR, Reflector } from '@nestjs/core';
+import { TRANSLATABLE_MODULE_OPTIONS } from './constants.js';
+import { TranslationContextMiddleware } from './context/translation-context.middleware.js';
+import { TranslationContextService } from './context/translation-context.service.js';
+import { TranslationInterceptor } from './interceptors/translation.interceptor.js';
+import { TranslationQueryService } from './query/translation-query.service.js';
+import { TranslationService } from './services/translation.service.js';
+import { TranslationResponseTransformer } from './transformers/translation-response.transformer.js';
+const interceptorProvider = {
+    provide: APP_INTERCEPTOR,
+    inject: [TRANSLATABLE_MODULE_OPTIONS, TranslationInterceptor],
+    useFactory: (options, interceptor) => options.registerInterceptor === false
+        ? {
+            intercept: (_ctx, next) => next.handle(),
+        }
+        : interceptor,
+};
+const coreProviders = [
+    Reflector,
+    TranslationContextService,
+    TranslationContextMiddleware,
+    TranslationService,
+    TranslationInterceptor,
+    TranslationResponseTransformer,
+    TranslationQueryService,
+    interceptorProvider,
+];
+let TranslatableModule = TranslatableModule_1 = class TranslatableModule {
+    constructor(_options) {
+        this._options = _options;
+    }
+    static forRoot(options) {
+        TranslatableModule_1.validate(options);
+        return {
+            global: true,
+            module: TranslatableModule_1,
+            providers: [{ provide: TRANSLATABLE_MODULE_OPTIONS, useValue: options }, ...coreProviders],
+            exports: [
+                TRANSLATABLE_MODULE_OPTIONS,
+                TranslationContextService,
+                TranslationService,
+                TranslationInterceptor,
+                TranslationResponseTransformer,
+                TranslationQueryService,
+            ],
+        };
+    }
+    static forRootAsync(options) {
+        return {
+            global: true,
+            module: TranslatableModule_1,
+            imports: options.imports ?? [],
+            providers: [
+                {
+                    provide: TRANSLATABLE_MODULE_OPTIONS,
+                    inject: options.inject ?? [],
+                    useFactory: async (...args) => {
+                        const value = await options.useFactory(...args);
+                        TranslatableModule_1.validate(value);
+                        return value;
+                    },
+                },
+                ...coreProviders,
+            ],
+            exports: [
+                TRANSLATABLE_MODULE_OPTIONS,
+                TranslationContextService,
+                TranslationService,
+                TranslationInterceptor,
+                TranslationResponseTransformer,
+                TranslationQueryService,
+            ],
+        };
+    }
+    configure(consumer) {
+        consumer.apply(TranslationContextMiddleware).forRoutes('*');
+    }
+    static validate(options) {
+        if (!options.defaultLocale)
+            throw new Error('defaultLocale is required.');
+        if (!options.supportedLocales.includes(options.defaultLocale)) {
+            throw new Error('supportedLocales must contain defaultLocale.');
+        }
+        if (options.fallbackLocale && !options.supportedLocales.includes(options.fallbackLocale)) {
+            throw new Error('supportedLocales must contain fallbackLocale.');
+        }
+    }
+};
+TranslatableModule = TranslatableModule_1 = __decorate([
+    Module({}),
+    __param(0, Inject(TRANSLATABLE_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], TranslatableModule);
+export { TranslatableModule };

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+import type { Type } from '@nestjs/common';
+import type { ColumnOptions, DataSource } from 'typeorm';
+export type TranslationMap<T = string> = Record<string, T | null | undefined>;
+export type TranslationFallbackStrategy = 'default-locale' | 'first-available' | 'null' | 'throw';
+export type TranslationResponseMode = 'localized' | 'raw' | 'both';
+export interface TranslationBehaviorOptions {
+    fallbackLocale?: string;
+    fallbackStrategy?: TranslationFallbackStrategy;
+    /**
+     * Locale that a pre-existing, not-yet-translatable scalar column's value
+     * should be backfilled under when the migration generator converts it to
+     * JSON. Defaults to the module's `defaultLocale` when omitted.
+     */
+    sourceLocale?: string;
+}
+export interface TranslatableColumnOptions {
+    column?: ColumnOptions;
+    translation?: TranslationBehaviorOptions;
+}
+export type TranslatableStorageType = 'jsonb' | 'json' | 'simple-json';
+export interface TranslatableColumnMetadata extends TranslationBehaviorOptions {
+    propertyKey: string | symbol;
+}
+export interface TranslationRequestContext {
+    locale: string;
+    fallbackLocale: string;
+    responseMode: TranslationResponseMode;
+}
+export interface TranslationRouteOptions {
+    skip?: boolean;
+    locale?: string;
+    mode?: TranslationResponseMode;
+}
+export interface LocaleResolverContext {
+    query?: Record<string, unknown>;
+    headers?: Record<string, string | string[] | undefined>;
+}
+export interface LocaleResolver {
+    resolve(context: LocaleResolverContext): string | undefined;
+}
+export interface TranslatableModuleOptions {
+    defaultLocale: string;
+    fallbackLocale?: string;
+    supportedLocales: string[];
+    responseMode?: TranslationResponseMode;
+    fallbackStrategy?: TranslationFallbackStrategy;
+    queryParameter?: string;
+    headerName?: string;
+    strictLocales?: boolean;
+    mutateResponses?: boolean;
+    localeResolvers?: LocaleResolver[];
+    /**
+     * Whether to automatically register `TranslationInterceptor` as a global
+     * `APP_INTERCEPTOR`. Defaults to true. Set to false to attach it yourself
+     * (e.g. `app.useGlobalInterceptors(app.get(TranslationInterceptor))` in
+     * `main.ts`) instead of having it wired up implicitly by this module.
+     */
+    registerInterceptor?: boolean;
+}
+export interface TranslatableModuleAsyncOptions {
+    imports?: any[];
+    inject?: Array<string | symbol | Type<unknown>>;
+    useFactory: (...args: unknown[]) => Promise<TranslatableModuleOptions> | TranslatableModuleOptions;
+}
+export interface LocalizedExpressionOptions {
+    alias: string;
+    property: string;
+    locale?: string;
+    fallbackLocale?: string;
+}
+export interface TranslatableMigrationOptions {
+    dataSource: DataSource;
+    supportedLocales: string[];
+    defaultLocale: string;
+    /** Restrict generation to these entity classes. Defaults to every entity registered on the DataSource. */
+    entities?: Type<unknown>[];
+    /** Directory the migration file is written to. Defaults to './migrations'. */
+    outputDir?: string;
+    /** Base name used to build the migration class/file name. Defaults to 'TranslatableColumns'. */
+    name?: string;
+    /** Compute the plan without writing a migration file. Defaults to false. */
+    dryRun?: boolean;
+}
+export type TranslatableMigrationAction = 'create' | 'convert' | 'skip';
+export interface TranslatableMigrationColumnPlan {
+    table: string;
+    column: string;
+    action: TranslatableMigrationAction;
+    sourceLocale?: string;
+    reason?: string;
+}
+export interface TranslatableMigrationPlan {
+    className: string;
+    fileName: string;
+    filePath?: string;
+    upStatements: string[];
+    downStatements: string[];
+    columns: TranslatableMigrationColumnPlan[];
+    written: boolean;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nestjs-dash/translation",
+  "version": "0.2.0",
+  "description": "Database-aware translatable JSON columns for NestJS and TypeORM",
+  "license": "MIT",
+  "bin": {
+    "nestjs-dash-translation": "./dist/migration/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@nestjs-dash/typescript-config": "0.1.0",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.20.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typeorm": "^1.1.1",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^12.0.0",
+    "@nestjs/core": "^12.0.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0",
+    "typeorm": ">=0.2.41 <0.3.0-0 || ^0.3.20 || ^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/migration/cli.js",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "format": "oxfmt",
+    "lint": "oxlint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}