@harpy-js/core 0.4.7

package/src/i18n/__tests__/i18n.service.test.ts

@@ -0,0 +1,129 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { I18nService } from "../i18n.service";
+import { I18N_MODULE_OPTIONS } from "../i18n-module.options";
+import type { I18nModuleOptions } from "../i18n-module.options";
+import { REQUEST } from "@nestjs/core";
+
+describe("I18nService", () => {
+  let service: I18nService;
+  const mockOptions: I18nModuleOptions = {
+    defaultLocale: "en",
+    locales: ["en", "fr"],
+    urlPattern: "query",
+    translationsPath: "./dictionaries",
+    cookieName: "locale",
+    queryParam: "lang",
+  };
+
+  const mockRequest = {
+    locale: "en",
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        I18nService,
+        {
+          provide: I18N_MODULE_OPTIONS,
+          useValue: mockOptions,
+        },
+        {
+          provide: REQUEST,
+          useValue: mockRequest,
+        },
+      ],
+    }).compile();
+
+    service = await module.resolve<I18nService>(I18nService);
+  });
+
+  describe("getLocale", () => {
+    it("should return locale from request", () => {
+      expect(service.getLocale()).toBe("en");
+    });
+
+    it("should return default locale when request locale is not set", async () => {
+      const requestWithoutLocale = {};
+      const module = await Test.createTestingModule({
+        providers: [
+          I18nService,
+          {
+            provide: I18N_MODULE_OPTIONS,
+            useValue: mockOptions,
+          },
+          {
+            provide: REQUEST,
+            useValue: requestWithoutLocale,
+          },
+        ],
+      }).compile();
+
+      const serviceInstance = await module.resolve<I18nService>(I18nService);
+      expect(serviceInstance.getLocale()).toBe("en");
+    });
+  });
+
+  describe("getDict", () => {
+    it("should return empty object when no dictionary loader registered", async () => {
+      const dict = await service.getDict();
+      expect(dict).toEqual({});
+    });
+
+    it("should call registered dictionary loader", async () => {
+      const mockDict = { hello: "Hello", goodbye: "Goodbye" };
+      const mockLoader = jest.fn().mockResolvedValue(mockDict);
+
+      service.registerDictionaryLoader(mockLoader);
+
+      const dict = await service.getDict();
+
+      expect(mockLoader).toHaveBeenCalledWith("en");
+      expect(dict).toEqual(mockDict);
+    });
+
+    it("should cache dictionary after first load", async () => {
+      const mockDict = { hello: "Hello" };
+      const mockLoader = jest.fn().mockResolvedValue(mockDict);
+
+      service.registerDictionaryLoader(mockLoader);
+
+      await service.getDict();
+      await service.getDict();
+
+      expect(mockLoader).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("translate", () => {
+    beforeEach(() => {
+      const mockDict = {
+        welcome: "Welcome",
+        greeting: "Hello {{name}}!",
+        nested: {
+          key: "Nested value",
+        },
+      };
+      service.registerDictionaryLoader(jest.fn().mockResolvedValue(mockDict));
+    });
+
+    it("should translate simple key", async () => {
+      const result = await service.translate("welcome");
+      expect(result).toBe("Welcome");
+    });
+
+    it("should translate with variables", async () => {
+      const result = await service.translate("greeting", { name: "John" });
+      expect(result).toBe("Hello John!");
+    });
+
+    it("should translate nested key", async () => {
+      const result = await service.translate("nested.key");
+      expect(result).toBe("Nested value");
+    });
+
+    it("should return empty string for non-existent key", async () => {
+      const result = await service.translate("nonexistent");
+      expect(result).toBe("");
+    });
+  });
+});

package/src/i18n/__tests__/t.test.ts

@@ -0,0 +1,88 @@
+import { t, tUnsafe } from "../t";
+
+describe("Translation Function (t)", () => {
+  const mockDict = {
+    simple: "Hello",
+    nested: {
+      key: "Nested value",
+      deep: {
+        value: "Deep nested value",
+      },
+    },
+    withVar: "Hello {{name}}!",
+    withMultipleVars: "Hello {{name}}, you have {{count}} messages",
+  };
+
+  describe("Simple translations", () => {
+    it("should translate simple key", () => {
+      expect(t(mockDict, "simple")).toBe("Hello");
+    });
+
+    it("should translate nested key", () => {
+      expect(t(mockDict, "nested.key")).toBe("Nested value");
+    });
+
+    it("should translate deeply nested key", () => {
+      expect(t(mockDict, "nested.deep.value")).toBe("Deep nested value");
+    });
+  });
+
+  describe("Variable interpolation", () => {
+    it("should interpolate single variable", () => {
+      expect(t(mockDict as any, "withVar", { name: "John" })).toBe(
+        "Hello John!",
+      );
+    });
+
+    it("should interpolate multiple variables", () => {
+      expect(
+        t(mockDict as any, "withMultipleVars", { name: "John", count: 5 }),
+      ).toBe("Hello John, you have 5 messages");
+    });
+
+    it("should handle missing variables gracefully", () => {
+      expect(t(mockDict as any, "withVar", {} as any)).toBe("Hello !");
+    });
+
+    it("should handle numeric variables", () => {
+      expect(
+        t(mockDict as any, "withMultipleVars", { name: "John", count: 0 }),
+      ).toBe("Hello John, you have 0 messages");
+    });
+  });
+
+  describe("Edge cases", () => {
+    it("should return empty string for non-existent key", () => {
+      expect(t(mockDict, "nonexistent" as any)).toBe("");
+    });
+
+    it("should return empty string for non-string value", () => {
+      expect(t(mockDict, "nested" as any)).toBe("");
+    });
+
+    it("should handle empty dictionary", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect(t({} as any, "any")).toBe("");
+    });
+  });
+
+  describe("tUnsafe function", () => {
+    it("should work with dynamic keys", () => {
+      expect(tUnsafe(mockDict, "simple")).toBe("Hello");
+    });
+
+    it("should work with nested keys", () => {
+      expect(tUnsafe(mockDict, "nested.key")).toBe("Nested value");
+    });
+
+    it("should interpolate variables", () => {
+      expect(tUnsafe(mockDict, "withVar", { name: "Jane" })).toBe(
+        "Hello Jane!",
+      );
+    });
+
+    it("should handle non-existent keys", () => {
+      expect(tUnsafe(mockDict, "invalid.key")).toBe("");
+    });
+  });
+});

package/src/i18n/i18n-module.options.ts

@@ -0,0 +1,53 @@
+/**
+ * URL pattern for language detection
+ * - 'query': /path?lang=en
+ * - 'header': Uses headers only (x-lang, accept-language)
+ */
+export type I18nUrlPattern = "query" | "header";
+
+/**
+ * Configuration options for I18nModule
+ */
+export interface I18nModuleOptions {
+  /**
+   * Default locale to use when no locale is detected
+   * @default 'en'
+   */
+  defaultLocale: string;
+
+  /**
+   * List of supported locales
+   * @default ['en']
+   */
+  locales: string[];
+
+  /**
+   * URL pattern for language detection
+   * @default 'query'
+   */
+  urlPattern?: I18nUrlPattern;
+
+  /**
+   * Path to the directory containing translation files
+   * Files should be named {locale}.json
+   * @default './dictionaries'
+   */
+  translationsPath?: string;
+
+  /**
+   * Cookie name for storing locale preference
+   * @default 'locale'
+   */
+  cookieName?: string;
+
+  /**
+   * Query parameter name for locale (when urlPattern is 'query')
+   * @default 'lang'
+   */
+  queryParam?: string;
+}
+
+/**
+ * Token for injecting I18n module options
+ */
+export const I18N_MODULE_OPTIONS = "I18N_MODULE_OPTIONS";

package/src/i18n/i18n-switcher.controller.ts

@@ -0,0 +1,99 @@
+import {
+  Controller,
+  Post,
+  Body,
+  Req,
+  Res,
+  Get,
+  HttpStatus,
+} from "@nestjs/common";
+import { I18nHelper } from "./i18n.helper";
+
+/**
+ * API Controller for handling locale switching
+ *
+ * Provides a proper API endpoint for changing locales
+ */
+@Controller("api/i18n")
+export class I18nSwitcherController {
+  constructor(private readonly i18nHelper: I18nHelper) {}
+
+  /**
+   * API endpoint to switch locale
+   *
+   * @example
+   * ```typescript
+   * fetch('/api/i18n/switch-locale', {
+   *   method: 'POST',
+   *   headers: { 'Content-Type': 'application/json' },
+   *   body: JSON.stringify({ locale: 'fr' })
+   * });
+   * ```
+   */
+  @Post("switch-locale")
+  switchLocale(
+    @Body("locale") locale: string,
+    @Req() req: any,
+    @Res() res: any,
+  ) {
+    // Validate locale
+    if (!locale) {
+      return res
+        .status(HttpStatus.BAD_REQUEST)
+        .send({ error: "Locale is required" });
+    }
+
+    // Validate and normalize locale
+    const validatedLocale = this.i18nHelper.validateLocale(locale);
+
+    // Set cookie
+    this.i18nHelper.setLocaleCookie(res, validatedLocale);
+
+    // Get the referer (where the user came from) or default to homepage
+    const referer = req.headers.referer || req.headers.origin || "/";
+    let currentPath = "/";
+    let query: Record<string, string> = {};
+
+    try {
+      const refererUrl = new URL(referer);
+      // Security check: validate it's from the same origin to prevent open redirect
+      const requestOrigin = `${req.protocol}://${req.hostname}${req.hostname === "localhost" && req.port ? ":" + req.port : ""}`;
+
+      if (refererUrl.origin !== requestOrigin) {
+        // External origin - use root path for security
+        currentPath = "/";
+      } else {
+        currentPath = refererUrl.pathname;
+        // Parse query params from referer
+        refererUrl.searchParams.forEach((value, key) => {
+          query[key] = value;
+        });
+      }
+    } catch {
+      // If referer is not a valid URL, use root path
+      currentPath = "/";
+    }
+
+    // Build redirect URL based on the page the user was on
+    const redirectUrl = this.i18nHelper.buildLocaleUrl(
+      validatedLocale,
+      currentPath,
+      query,
+    );
+
+    // Return the URL for client-side navigation
+    return res.send({
+      success: true,
+      locale: validatedLocale,
+      redirectUrl,
+    });
+  }
+
+  /**
+   * Get i18n configuration for client-side usage
+   */
+  @Get("config")
+  getConfig() {
+    return this.i18nHelper.getClientConfig();
+  }
+}

package/src/i18n/i18n-types.ts

@@ -0,0 +1,56 @@
+/**
+ * Type utilities for type-safe translations
+ */
+
+/**
+ * Extract nested keys from an object type with dot notation
+ * @example
+ * type Dict = { user: { name: string; age: number }; welcome: string };
+ * type Keys = NestedKeyOf<Dict>; // 'user.name' | 'user.age' | 'welcome'
+ */
+export type NestedKeyOf<ObjectType extends object> = {
+  [Key in keyof ObjectType & string]: ObjectType[Key] extends object
+    ? ObjectType[Key] extends Array<any>
+      ? Key
+      : `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}`
+    : Key;
+}[keyof ObjectType & string];
+
+/**
+ * Extract the value type at a given key path
+ * @example
+ * type Dict = { user: { name: string }; count: number };
+ * type Value = DeepValue<Dict, 'user.name'>; // string
+ */
+export type DeepValue<
+  T,
+  K extends string,
+> = K extends `${infer First}.${infer Rest}`
+  ? First extends keyof T
+    ? Rest extends string
+      ? DeepValue<T[First], Rest>
+      : never
+    : never
+  : K extends keyof T
+    ? T[K]
+    : never;
+
+/**
+ * Extract variable names from a translation string
+ * @example
+ * type Vars = ExtractVariables<"Hello {{name}}, you have {{count}} messages">;
+ * // { name: string | number; count: string | number }
+ */
+export type ExtractVariables<T extends string> =
+  T extends `${string}{{${infer Var}}}${infer Rest}`
+    ? { [K in Var | keyof ExtractVariables<Rest>]: string | number }
+    : Record<string, never>;
+
+/**
+ * Check if a translation string requires variables
+ */
+export type RequiresVariables<T> = T extends string
+  ? T extends `${string}{{${string}}}${string}`
+    ? true
+    : false
+  : false;

package/src/i18n/i18n.helper.ts

@@ -0,0 +1,75 @@
+import { Inject, Injectable } from "@nestjs/common";
+import type { I18nModuleOptions } from "./i18n-module.options";
+import { I18N_MODULE_OPTIONS } from "./i18n-module.options";
+
+@Injectable()
+export class I18nHelper {
+  constructor(
+    @Inject(I18N_MODULE_OPTIONS) private readonly options: I18nModuleOptions,
+  ) {}
+
+  /**
+   * Build the URL for switching locale based on the configured URL pattern
+   */
+  buildLocaleUrl(
+    locale: string,
+    currentPath: string,
+    query?: Record<string, string>,
+  ): string {
+    const { urlPattern, queryParam = "lang" } = this.options;
+
+    switch (urlPattern) {
+      case "query": {
+        const params = new URLSearchParams(query || {});
+        params.set(queryParam, locale);
+        return `${currentPath}?${params.toString()}`;
+      }
+
+      case "header":
+      default: {
+        // For header-based, just redirect to same URL
+        // Cookie will be set and header will be checked on next request
+        if (query && Object.keys(query).length > 0) {
+          const params = new URLSearchParams(query);
+          return `${currentPath}?${params.toString()}`;
+        }
+        return currentPath;
+      }
+    }
+  }
+
+  /**
+   * Set the locale cookie in the response (Fastify)
+   */
+  setLocaleCookie(res: any, locale: string): void {
+    const { cookieName = "locale" } = this.options;
+    res.setCookie(cookieName, locale, {
+      path: "/",
+      maxAge: 365 * 24 * 60 * 60, // 1 year in seconds for Fastify
+      httpOnly: false, // Allow client-side reading if needed
+      sameSite: "lax",
+    });
+  }
+
+  /**
+   * Validate locale
+   */
+  validateLocale(locale: string): string {
+    if (!this.options.locales?.includes(locale)) {
+      return this.options.defaultLocale || "en";
+    }
+    return locale;
+  }
+
+  /**
+   * Get configuration for client-side usage
+   */
+  getClientConfig() {
+    return {
+      locales: this.options.locales || ["en"],
+      defaultLocale: this.options.defaultLocale || "en",
+      urlPattern: this.options.urlPattern || "query",
+      queryParam: this.options.queryParam || "lang",
+    };
+  }
+}

package/src/i18n/i18n.interceptor.ts

@@ -0,0 +1,114 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Inject,
+} from "@nestjs/common";
+import { Observable } from "rxjs";
+import { I18N_MODULE_OPTIONS } from "./i18n-module.options";
+import type { I18nModuleOptions } from "./i18n-module.options";
+
+@Injectable()
+export class I18nInterceptor implements NestInterceptor {
+  constructor(
+    @Inject(I18N_MODULE_OPTIONS) private options: I18nModuleOptions,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const response = context.switchToHttp().getResponse();
+    const locales = this.options.locales;
+    const defaultLocale = this.options.defaultLocale;
+
+    let locale: string | undefined = undefined;
+    let shouldSetCookie = false;
+
+    // Extract locale based on URL pattern
+    switch (this.options.urlPattern) {
+      case "query":
+        // Extract from query parameter
+        const queryLang = request.query?.[this.options.queryParam || "lang"];
+        if (queryLang && locales.includes(queryLang)) {
+          locale = queryLang;
+          shouldSetCookie = true; // Set cookie when lang is in URL
+        }
+        break;
+
+      case "header":
+        // Extract from x-lang header
+        const xLang = request.headers["x-lang"];
+        if (xLang && locales.includes(xLang)) {
+          locale = xLang;
+          shouldSetCookie = true; // Set cookie when header is present
+        }
+        break;
+    }
+
+    // Fallback to cookie if not found in URL/header
+    const cookieLang = this.parseCookie(
+      request.headers.cookie,
+      this.options.cookieName || "locale",
+    );
+    if (!locale) {
+      if (cookieLang && locales.includes(cookieLang)) {
+        locale = cookieLang;
+      }
+    }
+
+    // Fallback to accept-language header
+    if (!locale) {
+      const acceptLanguage = request.headers["accept-language"];
+      if (acceptLanguage) {
+        const preferredLocale = acceptLanguage
+          .split(",")[0]
+          .split("-")[0]
+          .toLowerCase();
+
+        if (locales.includes(preferredLocale)) {
+          locale = preferredLocale;
+        }
+      }
+    }
+
+    // Use default locale if nothing matched
+    if (!locale) {
+      locale = defaultLocale;
+    }
+
+    // Store locale in request object for later use
+    request.locale = locale;
+
+    // Automatically set cookie if locale was found in URL or header
+    if (shouldSetCookie && cookieLang !== locale) {
+      const cookieName = this.options.cookieName || "locale";
+      const maxAge = 365 * 24 * 60 * 60; // 1 year in seconds
+      response.header(
+        "Set-Cookie",
+        `${cookieName}=${locale}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax`,
+      );
+    }
+
+    return next.handle();
+  }
+
+  private parseCookie(
+    cookieHeader: string | undefined,
+    name: string,
+  ): string | undefined {
+    if (!cookieHeader) return undefined;
+
+    const cookies = cookieHeader.split(";").map((c) => c.trim());
+    const cookie = cookies.find((c) => c.startsWith(`${name}=`));
+
+    if (!cookie) return undefined;
+    const eqIndex = cookie.indexOf("=");
+    if (eqIndex === -1) return undefined;
+    const value = cookie.slice(eqIndex + 1);
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value; // Return as-is if decoding fails
+    }
+  }
+}

package/src/i18n/i18n.module.ts

@@ -0,0 +1,45 @@
+import { Module, Global, DynamicModule } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { I18nService } from "./i18n.service";
+import { I18nInterceptor } from "./i18n.interceptor";
+import { I18nHelper } from "./i18n.helper";
+import { I18nSwitcherController } from "./i18n-switcher.controller";
+import { I18nModuleOptions, I18N_MODULE_OPTIONS } from "./i18n-module.options";
+
+@Global()
+@Module({})
+export class I18nModule {
+  /**
+   * Register I18n module with configuration
+   * @param options Configuration options for i18n
+   */
+  static forRoot(options: I18nModuleOptions): DynamicModule {
+    // Set defaults
+    const moduleOptions: Required<I18nModuleOptions> = {
+      defaultLocale: options.defaultLocale || "en",
+      locales: options.locales || ["en"],
+      urlPattern: options.urlPattern || "query",
+      translationsPath: options.translationsPath || "./dictionaries",
+      cookieName: options.cookieName || "locale",
+      queryParam: options.queryParam || "lang",
+    };
+
+    return {
+      module: I18nModule,
+      controllers: [I18nSwitcherController],
+      providers: [
+        {
+          provide: I18N_MODULE_OPTIONS,
+          useValue: moduleOptions,
+        },
+        I18nService,
+        I18nHelper,
+        {
+          provide: APP_INTERCEPTOR,
+          useClass: I18nInterceptor,
+        },
+      ],
+      exports: [I18nService, I18nHelper, I18N_MODULE_OPTIONS],
+    };
+  }
+}