@contractspec/lib.contracts-spec 2.4.0 → 2.5.0

package/dist/node/translations/i18n-factory.js

@@ -0,0 +1,229 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/translations/registry.ts
+class TranslationRegistry {
+  specs = new Map;
+  latestByLocale = new Map;
+  locales = new Set;
+  domains = new Set;
+  constructor(items) {
+    if (items) {
+      for (const spec of items) {
+        this.register(spec);
+      }
+    }
+  }
+  register(spec) {
+    const fullKey = this.makeKey(spec.meta.key, spec.meta.version, spec.locale);
+    this.specs.set(fullKey, spec);
+    const localeKey = `${spec.meta.key}:${spec.locale}`;
+    const existing = this.latestByLocale.get(localeKey);
+    if (!existing || this.isNewerVersion(spec.meta.version, existing.meta.version)) {
+      this.latestByLocale.set(localeKey, spec);
+    }
+    this.locales.add(spec.locale);
+    this.domains.add(spec.meta.domain);
+  }
+  get(key, version, locale) {
+    return this.specs.get(this.makeKey(key, version, locale));
+  }
+  getLatest(key, locale) {
+    return this.latestByLocale.get(`${key}:${locale}`);
+  }
+  getMessage(specKey, messageKey, locale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (!spec)
+      return;
+    return spec.messages[messageKey];
+  }
+  getWithFallback(specKey, messageKey, locale, fallbackLocale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (spec) {
+      const message = spec.messages[messageKey];
+      if (message) {
+        return { spec, message, locale, fromFallback: false };
+      }
+      fallbackLocale = fallbackLocale ?? spec.fallback;
+    }
+    if (fallbackLocale && fallbackLocale !== locale) {
+      const fallbackSpec = version ? this.get(specKey, version, fallbackLocale) : this.getLatest(specKey, fallbackLocale);
+      if (fallbackSpec) {
+        const message = fallbackSpec.messages[messageKey];
+        if (message) {
+          return {
+            spec: fallbackSpec,
+            message,
+            locale: fallbackLocale,
+            fromFallback: true
+          };
+        }
+      }
+    }
+    return;
+  }
+  getValue(specKey, messageKey, locale, fallback) {
+    const result = this.getWithFallback(specKey, messageKey, locale);
+    return result?.message.value ?? fallback ?? messageKey;
+  }
+  listLocales(specKey) {
+    const locales = [];
+    for (const [key, spec] of this.specs.entries()) {
+      if (key.startsWith(`${specKey}:`)) {
+        if (!locales.includes(spec.locale)) {
+          locales.push(spec.locale);
+        }
+      }
+    }
+    return locales;
+  }
+  list() {
+    return [...this.specs.values()];
+  }
+  listByLocale(locale) {
+    return [...this.specs.values()].filter((s) => s.locale === locale);
+  }
+  listByDomain(domain) {
+    return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+  }
+  has(key, locale, version) {
+    if (version) {
+      return this.specs.has(this.makeKey(key, version, locale));
+    }
+    return this.latestByLocale.has(`${key}:${locale}`);
+  }
+  getLocales() {
+    return this.locales;
+  }
+  getDomains() {
+    return this.domains;
+  }
+  getStats() {
+    let totalMessages = 0;
+    for (const spec of this.specs.values()) {
+      totalMessages += Object.keys(spec.messages).length;
+    }
+    return {
+      totalSpecs: this.specs.size,
+      locales: [...this.locales],
+      domains: [...this.domains],
+      totalMessages
+    };
+  }
+  clear() {
+    this.specs.clear();
+    this.latestByLocale.clear();
+    this.locales.clear();
+    this.domains.clear();
+  }
+  makeKey(key, version, locale) {
+    return `${key}:${version}:${locale}`;
+  }
+  isNewerVersion(a, b) {
+    const parseVersion = (v) => {
+      const parts = v.split(".").map(Number);
+      return {
+        major: parts[0] ?? 0,
+        minor: parts[1] ?? 0,
+        patch: parts[2] ?? 0
+      };
+    };
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    if (va.major !== vb.major)
+      return va.major > vb.major;
+    if (va.minor !== vb.minor)
+      return va.minor > vb.minor;
+    return va.patch > vb.patch;
+  }
+}
+
+// src/translations/i18n-factory.ts
+var DEFAULT_LOCALE = "en";
+var SUPPORTED_LOCALES = ["en", "fr", "es"];
+function resolveLocale(optionsLocale, runtimeLocale) {
+  const raw = runtimeLocale ?? optionsLocale ?? DEFAULT_LOCALE;
+  if (isSupportedLocale(raw))
+    return raw;
+  const base = raw.split("-")[0];
+  if (base && isSupportedLocale(base))
+    return base;
+  return DEFAULT_LOCALE;
+}
+function isSupportedLocale(locale) {
+  return SUPPORTED_LOCALES.includes(locale);
+}
+function interpolate(template, params) {
+  if (!params)
+    return template;
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in params)
+      return String(params[key]);
+    return match;
+  });
+}
+function createI18nFactory(config) {
+  let sharedRegistry = null;
+  function getRegistry() {
+    if (!sharedRegistry) {
+      sharedRegistry = new TranslationRegistry(config.catalogs);
+    }
+    return sharedRegistry;
+  }
+  const factory = {
+    create(optionsLocale, runtimeLocale) {
+      const locale = resolveLocale(optionsLocale, runtimeLocale);
+      const registry = getRegistry();
+      return {
+        locale,
+        t(key, params) {
+          const raw = registry.getValue(config.specKey, key, locale, key);
+          return interpolate(raw, params);
+        }
+      };
+    },
+    getDefault() {
+      return factory.create(DEFAULT_LOCALE);
+    },
+    resetRegistry() {
+      sharedRegistry = null;
+    }
+  };
+  return factory;
+}
+export {
+  resolveLocale,
+  isSupportedLocale,
+  interpolate,
+  createI18nFactory,
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE
+};

package/dist/node/translations/index.js

@@ -28,9 +28,6 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
-// src/translations/spec.ts
-var defineTranslation = (spec) => spec;
-
 // src/translations/registry.ts
 class TranslationRegistry {
   specs = new Map;
@@ -168,6 +165,63 @@ class TranslationRegistry {
   }
 }
 
+// src/translations/i18n-factory.ts
+var DEFAULT_LOCALE = "en";
+var SUPPORTED_LOCALES = ["en", "fr", "es"];
+function resolveLocale(optionsLocale, runtimeLocale) {
+  const raw = runtimeLocale ?? optionsLocale ?? DEFAULT_LOCALE;
+  if (isSupportedLocale(raw))
+    return raw;
+  const base = raw.split("-")[0];
+  if (base && isSupportedLocale(base))
+    return base;
+  return DEFAULT_LOCALE;
+}
+function isSupportedLocale(locale) {
+  return SUPPORTED_LOCALES.includes(locale);
+}
+function interpolate(template, params) {
+  if (!params)
+    return template;
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in params)
+      return String(params[key]);
+    return match;
+  });
+}
+function createI18nFactory(config) {
+  let sharedRegistry = null;
+  function getRegistry() {
+    if (!sharedRegistry) {
+      sharedRegistry = new TranslationRegistry(config.catalogs);
+    }
+    return sharedRegistry;
+  }
+  const factory = {
+    create(optionsLocale, runtimeLocale) {
+      const locale = resolveLocale(optionsLocale, runtimeLocale);
+      const registry = getRegistry();
+      return {
+        locale,
+        t(key, params) {
+          const raw = registry.getValue(config.specKey, key, locale, key);
+          return interpolate(raw, params);
+        }
+      };
+    },
+    getDefault() {
+      return factory.create(DEFAULT_LOCALE);
+    },
+    resetRegistry() {
+      sharedRegistry = null;
+    }
+  };
+  return factory;
+}
+
+// src/translations/spec.ts
+var defineTranslation = (spec) => spec;
+
 // src/translations/validation.ts
 function validateTranslationSpec(spec) {
   const issues = [];
@@ -524,10 +578,16 @@ export {
   validateTranslationSpec,
   validateTranslationRegistry,
   validateICUFormat,
+  resolveLocale,
+  isSupportedLocale,
+  interpolate,
   findMissingTranslations,
   findAllMissingTranslations,
   defineTranslation,
+  createI18nFactory,
   assertTranslationSpecValid,
   TranslationValidationError,
-  TranslationRegistry
+  TranslationRegistry,
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE
 };

package/dist/translations/i18n-factory.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Generic i18n factory for ContractSpec packages.
+ *
+ * Eliminates the boilerplate duplicated across package-level
+ * i18n/messages.ts files by extracting the common interpolation,
+ * registry management, locale resolution, and t() wiring.
+ *
+ * @module translations/i18n-factory
+ */
+import type { TranslationSpec } from './spec';
+/** Default locale when none is specified. */
+export declare const DEFAULT_LOCALE = "en";
+/** Supported locales shipped with ContractSpec packages. */
+export declare const SUPPORTED_LOCALES: readonly ["en", "fr", "es"];
+/** A locale included in the default set. */
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+/**
+ * Resolve the effective locale from two optional overrides.
+ *
+ * Priority: `runtimeLocale > optionsLocale > DEFAULT_LOCALE`.
+ * Falls back to base language (e.g., `"fr-CA"` -> `"fr"`) when needed.
+ */
+export declare function resolveLocale(optionsLocale?: string, runtimeLocale?: string): string;
+/** Check whether a string is a supported locale. */
+export declare function isSupportedLocale(locale: string): locale is SupportedLocale;
+/**
+ * Simple placeholder interpolation.
+ *
+ * Replaces `{key}` tokens with values from the params map.
+ * Does NOT handle full ICU (plurals, selects) — only simple
+ * string/number substitution.
+ */
+export declare function interpolate(template: string, params?: Record<string, string | number>): string;
+/**
+ * A package-scoped i18n instance.
+ *
+ * @typeParam K - Union type of valid message keys for the package
+ */
+export interface I18nInstance<K extends string = string> {
+    /** Translate a message key with optional placeholder interpolation. */
+    t(key: K | string, params?: Record<string, string | number>): string;
+    /** The effective locale being used. */
+    readonly locale: string;
+}
+/** Configuration for `createI18nFactory`. */
+export interface I18nFactoryConfig {
+    /** The spec key used to register translations (e.g., `"ai-agent.messages"`). */
+    specKey: string;
+    /** Translation catalogs to register (typically `[en, fr, es]`). */
+    catalogs: TranslationSpec[];
+}
+/** The object returned by `createI18nFactory`. */
+export interface I18nFactory<K extends string = string> {
+    /** Create an i18n instance for a given locale. */
+    create(optionsLocale?: string, runtimeLocale?: string): I18nInstance<K>;
+    /** Create a default (English) i18n instance. */
+    getDefault(): I18nInstance<K>;
+    /** Reset the shared registry (useful for testing). */
+    resetRegistry(): void;
+}
+/**
+ * Create a package-scoped i18n factory.
+ *
+ * Replaces the ~100 lines of boilerplate previously duplicated
+ * in every package's `i18n/messages.ts`.
+ *
+ * @typeParam K - The package's message key union type
+ * @param config - Spec key and translation catalogs
+ * @returns An I18nFactory with `create()`, `getDefault()`, and `resetRegistry()`
+ *
+ * @example
+ * ```ts
+ * import { createI18nFactory } from '@contractspec/lib.contracts-spec/translations';
+ * import type { AgentMessageKey } from './keys';
+ * import { enMessages } from './catalogs/en';
+ * import { frMessages } from './catalogs/fr';
+ * import { esMessages } from './catalogs/es';
+ *
+ * const factory = createI18nFactory<AgentMessageKey>({
+ *   specKey: 'ai-agent.messages',
+ *   catalogs: [enMessages, frMessages, esMessages],
+ * });
+ *
+ * export type AgentI18n = I18nInstance<AgentMessageKey>;
+ * export const createAgentI18n = factory.create;
+ * export const getDefaultI18n = factory.getDefault;
+ * export const resetI18nRegistry = factory.resetRegistry;
+ * ```
+ */
+export declare function createI18nFactory<K extends string = string>(config: I18nFactoryConfig): I18nFactory<K>;

package/dist/translations/i18n-factory.js

@@ -0,0 +1,229 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/translations/registry.ts
+class TranslationRegistry {
+  specs = new Map;
+  latestByLocale = new Map;
+  locales = new Set;
+  domains = new Set;
+  constructor(items) {
+    if (items) {
+      for (const spec of items) {
+        this.register(spec);
+      }
+    }
+  }
+  register(spec) {
+    const fullKey = this.makeKey(spec.meta.key, spec.meta.version, spec.locale);
+    this.specs.set(fullKey, spec);
+    const localeKey = `${spec.meta.key}:${spec.locale}`;
+    const existing = this.latestByLocale.get(localeKey);
+    if (!existing || this.isNewerVersion(spec.meta.version, existing.meta.version)) {
+      this.latestByLocale.set(localeKey, spec);
+    }
+    this.locales.add(spec.locale);
+    this.domains.add(spec.meta.domain);
+  }
+  get(key, version, locale) {
+    return this.specs.get(this.makeKey(key, version, locale));
+  }
+  getLatest(key, locale) {
+    return this.latestByLocale.get(`${key}:${locale}`);
+  }
+  getMessage(specKey, messageKey, locale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (!spec)
+      return;
+    return spec.messages[messageKey];
+  }
+  getWithFallback(specKey, messageKey, locale, fallbackLocale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (spec) {
+      const message = spec.messages[messageKey];
+      if (message) {
+        return { spec, message, locale, fromFallback: false };
+      }
+      fallbackLocale = fallbackLocale ?? spec.fallback;
+    }
+    if (fallbackLocale && fallbackLocale !== locale) {
+      const fallbackSpec = version ? this.get(specKey, version, fallbackLocale) : this.getLatest(specKey, fallbackLocale);
+      if (fallbackSpec) {
+        const message = fallbackSpec.messages[messageKey];
+        if (message) {
+          return {
+            spec: fallbackSpec,
+            message,
+            locale: fallbackLocale,
+            fromFallback: true
+          };
+        }
+      }
+    }
+    return;
+  }
+  getValue(specKey, messageKey, locale, fallback) {
+    const result = this.getWithFallback(specKey, messageKey, locale);
+    return result?.message.value ?? fallback ?? messageKey;
+  }
+  listLocales(specKey) {
+    const locales = [];
+    for (const [key, spec] of this.specs.entries()) {
+      if (key.startsWith(`${specKey}:`)) {
+        if (!locales.includes(spec.locale)) {
+          locales.push(spec.locale);
+        }
+      }
+    }
+    return locales;
+  }
+  list() {
+    return [...this.specs.values()];
+  }
+  listByLocale(locale) {
+    return [...this.specs.values()].filter((s) => s.locale === locale);
+  }
+  listByDomain(domain) {
+    return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+  }
+  has(key, locale, version) {
+    if (version) {
+      return this.specs.has(this.makeKey(key, version, locale));
+    }
+    return this.latestByLocale.has(`${key}:${locale}`);
+  }
+  getLocales() {
+    return this.locales;
+  }
+  getDomains() {
+    return this.domains;
+  }
+  getStats() {
+    let totalMessages = 0;
+    for (const spec of this.specs.values()) {
+      totalMessages += Object.keys(spec.messages).length;
+    }
+    return {
+      totalSpecs: this.specs.size,
+      locales: [...this.locales],
+      domains: [...this.domains],
+      totalMessages
+    };
+  }
+  clear() {
+    this.specs.clear();
+    this.latestByLocale.clear();
+    this.locales.clear();
+    this.domains.clear();
+  }
+  makeKey(key, version, locale) {
+    return `${key}:${version}:${locale}`;
+  }
+  isNewerVersion(a, b) {
+    const parseVersion = (v) => {
+      const parts = v.split(".").map(Number);
+      return {
+        major: parts[0] ?? 0,
+        minor: parts[1] ?? 0,
+        patch: parts[2] ?? 0
+      };
+    };
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    if (va.major !== vb.major)
+      return va.major > vb.major;
+    if (va.minor !== vb.minor)
+      return va.minor > vb.minor;
+    return va.patch > vb.patch;
+  }
+}
+
+// src/translations/i18n-factory.ts
+var DEFAULT_LOCALE = "en";
+var SUPPORTED_LOCALES = ["en", "fr", "es"];
+function resolveLocale(optionsLocale, runtimeLocale) {
+  const raw = runtimeLocale ?? optionsLocale ?? DEFAULT_LOCALE;
+  if (isSupportedLocale(raw))
+    return raw;
+  const base = raw.split("-")[0];
+  if (base && isSupportedLocale(base))
+    return base;
+  return DEFAULT_LOCALE;
+}
+function isSupportedLocale(locale) {
+  return SUPPORTED_LOCALES.includes(locale);
+}
+function interpolate(template, params) {
+  if (!params)
+    return template;
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in params)
+      return String(params[key]);
+    return match;
+  });
+}
+function createI18nFactory(config) {
+  let sharedRegistry = null;
+  function getRegistry() {
+    if (!sharedRegistry) {
+      sharedRegistry = new TranslationRegistry(config.catalogs);
+    }
+    return sharedRegistry;
+  }
+  const factory = {
+    create(optionsLocale, runtimeLocale) {
+      const locale = resolveLocale(optionsLocale, runtimeLocale);
+      const registry = getRegistry();
+      return {
+        locale,
+        t(key, params) {
+          const raw = registry.getValue(config.specKey, key, locale, key);
+          return interpolate(raw, params);
+        }
+      };
+    },
+    getDefault() {
+      return factory.create(DEFAULT_LOCALE);
+    },
+    resetRegistry() {
+      sharedRegistry = null;
+    }
+  };
+  return factory;
+}
+export {
+  resolveLocale,
+  isSupportedLocale,
+  interpolate,
+  createI18nFactory,
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE
+};

package/dist/translations/index.d.ts

@@ -42,3 +42,4 @@ export * from './registry';
 export * from './validation';
 export type { TranslationEntry, TranslationCatalogMeta, PlatformTranslationCatalog, BlueprintTranslationCatalog, } from './catalog';
 export * from './tenant';
+export * from './i18n-factory';