@objectstack/core 3.2.5 → 3.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/core",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "license": "Apache-2.0",
   "description": "Microkernel Core for ObjectStack",
   "type": "module",
@@ -22,7 +22,7 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "zod": "^4.3.6",
-    "@objectstack/spec": "3.2.5"
+    "@objectstack/spec": "3.2.7"
   },
   "peerDependencies": {
     "pino": "^8.0.0"

package/src/contracts/http-server.ts

@@ -135,6 +135,13 @@ export interface IHttpServer {
      * @returns Promise that resolves when server is ready
      */
     listen(port: number): Promise<void>;
+
+    /**
+     * Get the port the server is listening on.
+     * Returns the actual bound port after `listen()` resolves, or the
+     * configured port before that.
+     */
+    getPort?(): number;
     
     /**
      * Stop the HTTP server

package/src/fallbacks/fallbacks.test.ts

@@ -2,11 +2,12 @@ import { describe, it, expect } from 'vitest';
 import { createMemoryCache } from './memory-cache';
 import { createMemoryQueue } from './memory-queue';
 import { createMemoryJob } from './memory-job';
+import { createMemoryI18n, resolveLocale } from './memory-i18n';
 import { CORE_FALLBACK_FACTORIES } from './index';
 
 describe('CORE_FALLBACK_FACTORIES', () => {
-    it('should have exactly 3 entries: cache, queue, job', () => {
-        expect(Object.keys(CORE_FALLBACK_FACTORIES)).toEqual(['cache', 'queue', 'job']);
+    it('should have exactly 4 entries: cache, queue, job, i18n', () => {
+        expect(Object.keys(CORE_FALLBACK_FACTORIES)).toEqual(['cache', 'queue', 'job', 'i18n']);
     });
 
     it('should map to factory functions', () => {
@@ -156,3 +157,125 @@ describe('createMemoryJob', () => {
         expect(await job.getExecutions()).toEqual([]);
     });
 });
+
+describe('createMemoryI18n', () => {
+    it('should return an object with _fallback: true', () => {
+        const i18n = createMemoryI18n();
+        expect(i18n._fallback).toBe(true);
+        expect(i18n._serviceName).toBe('i18n');
+    });
+
+    it('should return the key when no translations are loaded', () => {
+        const i18n = createMemoryI18n();
+        expect(i18n.t('objects.account.label', 'en')).toBe('objects.account.label');
+    });
+
+    it('should translate after loading translations', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { objects: { account: { label: 'Account' } } });
+        expect(i18n.t('objects.account.label', 'en')).toBe('Account');
+    });
+
+    it('should interpolate parameters', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { greeting: 'Hello, {{name}}!' });
+        expect(i18n.t('greeting', 'en', { name: 'World' })).toBe('Hello, World!');
+    });
+
+    it('should fall back to default locale', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { hello: 'Hello' });
+        // 'fr' has no translations, should fall back to default 'en'
+        expect(i18n.t('hello', 'fr')).toBe('Hello');
+    });
+
+    it('should get and set default locale', () => {
+        const i18n = createMemoryI18n();
+        expect(i18n.getDefaultLocale()).toBe('en');
+        i18n.setDefaultLocale('zh-CN');
+        expect(i18n.getDefaultLocale()).toBe('zh-CN');
+    });
+
+    it('should list loaded locales', () => {
+        const i18n = createMemoryI18n();
+        expect(i18n.getLocales()).toEqual([]);
+        i18n.loadTranslations('en', { hello: 'Hello' });
+        i18n.loadTranslations('zh-CN', { hello: '你好' });
+        expect(i18n.getLocales()).toEqual(['en', 'zh-CN']);
+    });
+
+    it('should get all translations for a locale', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { hello: 'Hello', bye: 'Goodbye' });
+        expect(i18n.getTranslations('en')).toEqual({ hello: 'Hello', bye: 'Goodbye' });
+    });
+
+    it('should return empty object for unknown locale', () => {
+        const i18n = createMemoryI18n();
+        expect(i18n.getTranslations('unknown')).toEqual({});
+    });
+
+    it('should merge translations on subsequent loads', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { hello: 'Hello' });
+        i18n.loadTranslations('en', { bye: 'Goodbye' });
+        expect(i18n.getTranslations('en')).toEqual({ hello: 'Hello', bye: 'Goodbye' });
+    });
+});
+
+describe('resolveLocale', () => {
+    it('should return exact match', () => {
+        expect(resolveLocale('zh-CN', ['en', 'zh-CN', 'ja'])).toBe('zh-CN');
+    });
+
+    it('should return case-insensitive match', () => {
+        expect(resolveLocale('zh-cn', ['en', 'zh-CN'])).toBe('zh-CN');
+        expect(resolveLocale('EN-US', ['en-US', 'zh-CN'])).toBe('en-US');
+    });
+
+    it('should return base language match', () => {
+        expect(resolveLocale('zh-TW', ['en', 'zh'])).toBe('zh');
+    });
+
+    it('should return variant expansion (zh → zh-CN)', () => {
+        expect(resolveLocale('zh', ['en', 'zh-CN', 'zh-TW'])).toBe('zh-CN');
+    });
+
+    it('should return undefined for no match', () => {
+        expect(resolveLocale('fr', ['en', 'zh-CN'])).toBeUndefined();
+    });
+
+    it('should return undefined for empty available locales', () => {
+        expect(resolveLocale('en', [])).toBeUndefined();
+    });
+
+    it('should handle es → es-ES expansion', () => {
+        expect(resolveLocale('es', ['en', 'es-ES', 'fr'])).toBe('es-ES');
+    });
+});
+
+describe('createMemoryI18n locale fallback', () => {
+    it('should resolve translations via locale fallback (zh → zh-CN)', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('zh-CN', { hello: '你好' });
+        expect(i18n.getTranslations('zh')).toEqual({ hello: '你好' });
+    });
+
+    it('should resolve translations via case-insensitive fallback (zh-cn → zh-CN)', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('zh-CN', { hello: '你好' });
+        expect(i18n.getTranslations('zh-cn')).toEqual({ hello: '你好' });
+    });
+
+    it('should translate via locale fallback (zh → zh-CN)', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('zh-CN', { greeting: '你好世界' });
+        expect(i18n.t('greeting', 'zh')).toBe('你好世界');
+    });
+
+    it('should still fall back to default locale when no locale match at all', () => {
+        const i18n = createMemoryI18n();
+        i18n.loadTranslations('en', { hello: 'Hello' });
+        expect(i18n.t('hello', 'ja')).toBe('Hello');
+    });
+});

package/src/fallbacks/index.ts

@@ -3,10 +3,12 @@
 import { createMemoryCache } from './memory-cache.js';
 import { createMemoryQueue } from './memory-queue.js';
 import { createMemoryJob } from './memory-job.js';
+import { createMemoryI18n } from './memory-i18n.js';
 
 export { createMemoryCache } from './memory-cache.js';
 export { createMemoryQueue } from './memory-queue.js';
 export { createMemoryJob } from './memory-job.js';
+export { createMemoryI18n, resolveLocale } from './memory-i18n.js';
 
 /**
  * Map of core-criticality service names to their in-memory fallback factories.
@@ -17,4 +19,5 @@ export const CORE_FALLBACK_FACTORIES: Record<string, () => Record<string, any>>
   cache: createMemoryCache,
   queue: createMemoryQueue,
   job:   createMemoryJob,
+  i18n:  createMemoryI18n,
 };

package/src/fallbacks/memory-i18n.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Resolve a locale code against available locales with fallback.
+ *
+ * Fallback chain:
+ *   1. Exact match (e.g. `zh-CN` → `zh-CN`)
+ *   2. Case-insensitive match (e.g. `zh-cn` → `zh-CN`)
+ *   3. Base language match (e.g. `zh-CN` → `zh`)
+ *   4. Variant expansion (e.g. `zh` → `zh-CN`)
+ *
+ * Returns the matched locale code, or `undefined` when no match is found.
+ */
+export function resolveLocale(requestedLocale: string, availableLocales: string[]): string | undefined {
+  if (availableLocales.length === 0) return undefined;
+
+  // 1. Exact match
+  if (availableLocales.includes(requestedLocale)) return requestedLocale;
+
+  // 2. Case-insensitive match
+  const lower = requestedLocale.toLowerCase();
+  const caseMatch = availableLocales.find(l => l.toLowerCase() === lower);
+  if (caseMatch) return caseMatch;
+
+  // 3. Base language match (zh-CN → zh)
+  const baseLang = requestedLocale.split('-')[0].toLowerCase();
+  const baseMatch = availableLocales.find(l => l.toLowerCase() === baseLang);
+  if (baseMatch) return baseMatch;
+
+  // 4. Variant expansion (zh → zh-CN, zh-TW, etc. — first match wins)
+  const variantMatch = availableLocales.find(l => l.split('-')[0].toLowerCase() === baseLang);
+  if (variantMatch) return variantMatch;
+
+  return undefined;
+}
+
+/**
+ * In-memory i18n service fallback.
+ *
+ * Implements the II18nService contract with basic translate/load/getLocales
+ * operations.  Used by ObjectKernel as an automatic fallback when no real
+ * i18n plugin (e.g. I18nServicePlugin) is registered.
+ *
+ * Supports runtime translation loading, locale management, and
+ * locale code fallback (e.g. `zh` → `zh-CN`).
+ * Does not load files from disk — operates purely in-memory.
+ */
+export function createMemoryI18n() {
+  const translations = new Map<string, Record<string, unknown>>();
+  let defaultLocale = 'en';
+
+  /**
+   * Resolve a dot-notation key from a nested object.
+   */
+  function resolveKey(data: Record<string, unknown>, key: string): string | undefined {
+    const parts = key.split('.');
+    let current: unknown = data;
+    for (const part of parts) {
+      if (current == null || typeof current !== 'object') return undefined;
+      current = (current as Record<string, unknown>)[part];
+    }
+    return typeof current === 'string' ? current : undefined;
+  }
+
+  /**
+   * Find translation data for a locale, with fallback resolution.
+   */
+  function resolveTranslations(locale: string): Record<string, unknown> | undefined {
+    // Exact match
+    if (translations.has(locale)) return translations.get(locale);
+
+    // Locale fallback (zh → zh-CN, en-us → en-US, etc.)
+    const resolved = resolveLocale(locale, [...translations.keys()]);
+    if (resolved) return translations.get(resolved);
+
+    return undefined;
+  }
+
+  return {
+    _fallback: true, _serviceName: 'i18n',
+
+    t(key: string, locale: string, params?: Record<string, unknown>): string {
+      const data = resolveTranslations(locale) ?? translations.get(defaultLocale);
+      const value = data ? resolveKey(data, key) : undefined;
+      if (value == null) return key;
+      if (!params) return value;
+      // Interpolation format: {{paramName}} — matches FileI18nAdapter convention
+      return value.replace(/\{\{(\w+)\}\}/g, (_, name) => String(params[name] ?? `{{${name}}}`));
+    },
+
+    getTranslations(locale: string): Record<string, unknown> {
+      return resolveTranslations(locale) ?? {};
+    },
+
+    loadTranslations(locale: string, data: Record<string, unknown>): void {
+      const existing = translations.get(locale) ?? {};
+      translations.set(locale, { ...existing, ...data });
+    },
+
+    getLocales(): string[] {
+      return [...translations.keys()];
+    },
+
+    getDefaultLocale(): string {
+      return defaultLocale;
+    },
+
+    setDefaultLocale(locale: string): void {
+      defaultLocale = locale;
+    },
+  };
+}