@harpy-js/core 0.4.7

package/src/i18n/i18n.service.ts

@@ -0,0 +1,95 @@
+import { Injectable, Scope, Inject } from "@nestjs/common";
+import { REQUEST } from "@nestjs/core";
+import { I18N_MODULE_OPTIONS } from "./i18n-module.options";
+import type { I18nModuleOptions } from "./i18n-module.options";
+
+/**
+ * I18n Service - Request-scoped service for translations
+ *
+ * NOTE: This service uses a generic dictionary type. In your application,
+ * you should import your specific Dictionary type from get-dictionary.ts
+ *
+ * @example
+ * ```typescript
+ * import { I18nService } from '@harpy-js/core';
+ *
+ * @Controller()
+ * export class MyController {
+ *   constructor(private i18n: I18nService) {}
+ *
+ *   @Get()
+ *   async getPage() {
+ *     const dict = await this.i18n.getDict();
+ *     const locale = this.i18n.getLocale();
+ *     return { dict, locale };
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ scope: Scope.REQUEST })
+export class I18nService {
+  private dict: Record<string, any> | null = null;
+  private getDictionaryFn: ((locale: string) => Promise<any>) | null = null;
+
+  constructor(
+    @Inject(REQUEST) private request: any,
+    @Inject(I18N_MODULE_OPTIONS) private options: I18nModuleOptions,
+  ) {}
+
+  /**
+   * Register a custom dictionary loader function
+   * This should be called in your application's getDictionary.ts
+   */
+  registerDictionaryLoader(fn: (locale: string) => Promise<any>): void {
+    this.getDictionaryFn = fn;
+  }
+
+  /**
+   * Get the current dictionary
+   * Returns empty object if no dictionary loader is registered
+   */
+  async getDict(): Promise<Record<string, any>> {
+    if (!this.dict) {
+      const locale = this.request.locale || this.options.defaultLocale;
+
+      if (this.getDictionaryFn) {
+        this.dict = await this.getDictionaryFn(locale);
+      } else {
+        // Return empty object if no loader registered
+        console.warn(
+          "No dictionary loader registered. Call registerDictionaryLoader() in your app.",
+        );
+        this.dict = {};
+      }
+    }
+    return this.dict ?? {};
+  }
+
+  /**
+   * Get the current locale
+   */
+  getLocale(): string {
+    return this.request.locale || this.options.defaultLocale;
+  }
+
+  /**
+   * Translate a key with optional variables
+   * This is a helper method - for type-safe translations, use the t() function directly
+   */
+  async translate(
+    key: string,
+    vars?: Record<string, string | number>,
+  ): Promise<string> {
+    const dict = await this.getDict();
+
+    // Simple nested key resolution
+    const value = key.split(".").reduce((acc, k) => acc?.[k], dict as any);
+
+    if (typeof value !== "string") return "";
+
+    // Variable interpolation
+    return value.replace(/\{\{(.*?)\}\}/g, (_match: string, k: string) =>
+      String(vars?.[k.trim()] ?? ""),
+    );
+  }
+}

package/src/i18n/index.ts

@@ -0,0 +1,37 @@
+/**
+ * I18n Module - Internationalization for Harpy Framework
+ *
+ * @example
+ * ```typescript
+ * // In app.module.ts
+ * import { I18nModule } from '@harpy-js/core';
+ *
+ * @Module({
+ *   imports: [
+ *     I18nModule.forRoot({
+ *       defaultLocale: 'en',
+ *       locales: ['en', 'fr', 'es'],
+ *       urlPattern: 'query', // or 'header'
+ *       translationsPath: '../dictionaries',
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+
+export { I18nModule } from "./i18n.module";
+export { I18nService } from "./i18n.service";
+export { I18nInterceptor } from "./i18n.interceptor";
+export { I18nHelper } from "./i18n.helper";
+export { I18nSwitcherController } from "./i18n-switcher.controller";
+export { CurrentLocale } from "./locale.decorator";
+export { t, tUnsafe } from "./t";
+export { I18N_MODULE_OPTIONS } from "./i18n-module.options";
+export type { I18nModuleOptions, I18nUrlPattern } from "./i18n-module.options";
+export type {
+  NestedKeyOf,
+  DeepValue,
+  ExtractVariables,
+  RequiresVariables,
+} from "./i18n-types";

package/src/i18n/locale.decorator.ts

@@ -0,0 +1,10 @@
+import { createParamDecorator, ExecutionContext } from "@nestjs/common";
+
+export const CurrentLocale = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): string => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const request = ctx.switchToHttp().getRequest();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access
+    return request.locale;
+  },
+);

package/src/i18n/t.ts

@@ -0,0 +1,62 @@
+import type { NestedKeyOf, DeepValue, ExtractVariables } from "./i18n-types";
+
+/**
+ * Type-safe translation function - extracts translated values from dictionary
+ * Provides full type safety including:
+ * - Key autocomplete from dictionary structure
+ * - Required variables detection and type checking
+ * - Return type inference
+ *
+ * @param dict - The dictionary object containing translations
+ * @param key - The key to lookup (supports nested keys with dot notation)
+ * @param vars - Optional variables for interpolation using {{variable}} syntax
+ *
+ * @example
+ * ```typescript
+ * // Simple translation
+ * t(dict, 'welcome') // Type-safe key, returns string
+ *
+ * // Nested key
+ * t(dict, 'nav.home') // Autocomplete for nested keys
+ *
+ * // With variables
+ * t(dict, 'greeting', { name: 'John' }) // Variables are type-checked
+ * ```
+ */
+export function t<
+  TDict extends Record<string, any>,
+  TKey extends NestedKeyOf<TDict>,
+>(
+  dict: TDict,
+  key: TKey,
+  vars?: DeepValue<TDict, TKey> extends string
+    ? ExtractVariables<DeepValue<TDict, TKey>>
+    : Record<string, string | number>,
+): string {
+  // Resolve nested keys
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access
+  const value = key.split(".").reduce((acc, k) => acc?.[k], dict as any);
+
+  if (typeof value !== "string") return "";
+  return value.replace(/\{\{(.*?)\}\}/g, (_match: string, k: string) =>
+    String(vars?.[k.trim()] ?? ""),
+  );
+}
+
+/**
+ * Unsafe version of t() for dynamic keys or when types are not available
+ * Use this only when you need to bypass type checking
+ */
+export function tUnsafe(
+  dict: Record<string, any>,
+  key: string,
+  vars?: Record<string, string | number>,
+): string {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access
+  const value = key.split(".").reduce((acc, k) => acc?.[k], dict as any);
+
+  if (typeof value !== "string") return "";
+  return value.replace(/\{\{(.*?)\}\}/g, (_match: string, k: string) =>
+    String(vars?.[k.trim()] ?? ""),
+  );
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Core exports
+export { autoWrapClientComponent } from "./core/client-component-wrapper";
+export { hydrationContext, initializeHydrationContext } from "./core/hydration";
+export { getChunkPath, getHydrationManifest } from "./core/hydration-manifest";
+export { withJsxEngine } from "./core/jsx.engine";
+export { LiveReloadController } from "./core/live-reload.controller";
+export { StaticAssetsController } from "./core/static-assets.controller";
+
+// Decorators
+export { JsxRender } from "./decorators/jsx.decorator";
+export { WithLayout } from "./decorators/layout.decorator";
+export type { MetaOptions, RenderOptions } from "./decorators/jsx.decorator";
+
+// I18n is provided in a separate package: @harpy-js/i18n
+// Consumers should import i18n types and modules from that package.
+
+// Types
+export type { JsxLayout, JsxLayoutProps } from "./core/jsx.engine";
+export { RouterModule } from "./core/router.module";
+export { NavigationService } from "./core/navigation.service";
+export { AutoRegisterModule } from "./core/auto-register.module";
+export type { NavItem, NavSection } from "./core/types/nav.types";
+export type { NavigationRegistry } from "./core/types/nav.types";
+export { configureHarpyApp, HarpyAppOptions } from "./core/app-setup";
+export { setupHarpyApp } from "./core/app-setup";
+export { default as Link } from "./client/Link";
+export {
+  buildHrefIndex,
+  getActiveItemIdFromIndex,
+  getActiveItemIdFromManifest,
+} from "./client/getActiveItemId";