@xndrjs/i18n 0.6.1 → 0.7.0

package/src/single-builder.ts

@@ -0,0 +1,153 @@
+import { invokeNamespaceLoader, type NamespaceLoader } from "./builder-loaders.js";
+import type { I18nEngineSingleImpl } from "./engine.js";
+import type {
+  KeyDictionary,
+  LocaleFallbackMap,
+  LocaleOfSingle,
+  PartialKeyDictionary,
+} from "./types.js";
+import type { I18nScopeSingleForLocale, I18nScopeSingleImpl } from "./scope-single.js";
+
+type SingleScopeBound<
+  Schema extends KeyDictionary,
+  Params,
+  Locale extends string,
+> = I18nScopeSingleForLocale<Schema, Params & { [K in keyof Schema]: unknown }, Locale>;
+
+export type I18nBuilderSingleOptions<
+  Schema extends KeyDictionary,
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> = {
+  dictionaryLoader?: NamespaceLoader<PartialKeyDictionary<Schema, RequestLocales> | Schema>;
+};
+
+export interface I18nBuilderSingle<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> {
+  withLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): I18nBuilderSingleForLocaleImpl<Schema, Params, RequestLocales, Locale>;
+
+  withDeliveryArea<Area extends string>(
+    area: Area
+  ): I18nBuilderSingle<Schema, Params, RequestLocales>;
+
+  load(): Promise<
+    I18nScopeSingleImpl<Schema, Params, RequestLocales, LocaleFallbackMap | undefined>
+  >;
+}
+
+export interface I18nBuilderSingleForLocale<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  Locale extends string,
+> {
+  load(): Promise<SingleScopeBound<Schema, Params, Locale>>;
+}
+
+type SingleBuilderState<
+  Schema extends KeyDictionary,
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> = {
+  locale?: RequestLocales;
+  deliveryArea?: string;
+};
+
+export class I18nBuilderSingleImpl<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> implements I18nBuilderSingle<Schema, Params, RequestLocales> {
+  private state: SingleBuilderState<Schema, RequestLocales> = {};
+
+  constructor(
+    private readonly engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>,
+    private readonly options?: I18nBuilderSingleOptions<Schema, RequestLocales>,
+    state?: SingleBuilderState<Schema, RequestLocales>
+  ) {
+    if (state !== undefined) {
+      this.state = {
+        ...(state.locale !== undefined ? { locale: state.locale } : {}),
+        ...(state.deliveryArea !== undefined ? { deliveryArea: state.deliveryArea } : {}),
+      };
+    }
+  }
+
+  private clone(): SingleBuilderState<Schema, RequestLocales> {
+    return {
+      ...(this.state.locale !== undefined ? { locale: this.state.locale } : {}),
+      ...(this.state.deliveryArea !== undefined ? { deliveryArea: this.state.deliveryArea } : {}),
+    };
+  }
+
+  withLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): I18nBuilderSingleForLocaleImpl<Schema, Params, RequestLocales, Locale> {
+    const { deliveryArea: _deliveryArea, ...rest } = this.clone();
+    return new I18nBuilderSingleForLocaleImpl<Schema, Params, RequestLocales, Locale>(
+      this.engine,
+      this.options,
+      { ...rest, locale }
+    );
+  }
+
+  withDeliveryArea<Area extends string>(
+    _area: Area
+  ): I18nBuilderSingle<Schema, Params, RequestLocales> {
+    const { locale: _locale, ...rest } = this.clone();
+    return new I18nBuilderSingleImpl(this.engine, this.options, {
+      ...rest,
+      deliveryArea: _area,
+    });
+  }
+
+  async load(): Promise<
+    I18nScopeSingleImpl<Schema, Params, RequestLocales, LocaleFallbackMap | undefined>
+  > {
+    await applySingleBuilderLoad(this.engine, this.options, this.state);
+    return this.engine.toScope();
+  }
+}
+
+export class I18nBuilderSingleForLocaleImpl<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+  Locale extends RequestLocales = RequestLocales,
+> implements I18nBuilderSingleForLocale<Schema, Params, Locale> {
+  constructor(
+    private readonly engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>,
+    private readonly options: I18nBuilderSingleOptions<Schema, RequestLocales> | undefined,
+    private readonly state: SingleBuilderState<Schema, RequestLocales> & { locale: Locale }
+  ) {}
+
+  async load(): Promise<SingleScopeBound<Schema, Params, Locale>> {
+    await applySingleBuilderLoad(this.engine, this.options, this.state);
+    return this.engine.toScope({ locale: this.state.locale });
+  }
+}
+
+async function applySingleBuilderLoad<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string,
+>(
+  engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>,
+  options: I18nBuilderSingleOptions<Schema, RequestLocales> | undefined,
+  state: SingleBuilderState<Schema, RequestLocales>
+): Promise<void> {
+  const partition = state.locale ?? state.deliveryArea;
+  const loader = options?.dictionaryLoader;
+
+  if (loader !== undefined) {
+    if (engine.hasBuilderResourceLoaded(partition)) {
+      return;
+    }
+
+    const data = await invokeNamespaceLoader(loader, partition);
+    engine.applyLoadMergeSingle(data);
+    engine.markBuilderResourceLoaded(partition);
+  }
+}

package/src/types.ts

@@ -16,6 +16,22 @@ export type LocaleOfMulti<Schema extends MultiDictionary> = {
 }[keyof Schema] &
   string;
 
+/** Subset of schema keys with any subset of project locales per key — valid input for merge operations. */
+export type PartialKeyDictionary<
+  T extends KeyDictionary,
+  Locales extends string = LocaleOfSingle<T>,
+> = {
+  [K in keyof T]?: Partial<Record<Locales, string>>;
+};
+
+/** Subset of schema namespaces with partial keys/locales — valid input for multi merge operations. */
+export type PartialMultiDictionary<
+  T extends MultiDictionary,
+  Locales extends string = LocaleOfMulti<T>,
+> = {
+  [NS in keyof T]?: PartialKeyDictionary<T[NS], Locales>;
+};
+
 export type LocaleFallbackMap = Record<string, string | null>;
 
 export type MissingTranslationContext = {

package/src/validation/create-normalized-schema.ts

@@ -13,7 +13,7 @@ const parsedKeyEntrySchema = z.object({
   mergedArgs: z.record(z.string(), variableTypeSchema),
 });
 
-function createKeyDictionarySchema(
+export function createKeyDictionarySchema(
   argsByKey: Readonly<Record<string, VariableSpec>>
 ): z.ZodType<Record<string, ParsedKeyEntry>> {
   const keySchemas = Object.fromEntries(

package/src/validation/errors.ts

@@ -4,6 +4,8 @@ function issueMessage(issue: ValidationIssue): string {
   switch (issue.kind) {
     case "missing_key":
       return `Missing required key at ${issue.path.join(".")}`;
+    case "unknown_key":
+      return `Unknown key at ${issue.path.join(".")}`;
     case "invalid_input":
     case "invalid_locale_value":
     case "icu_syntax_error":

package/src/validation/index.ts

@@ -1,70 +1,178 @@
-import { normalizeDictionary } from "./normalize.js";
+import { normalizeDictionaryPartial, normalizeKeyDictionaryPartial } from "./normalize.js";
 import { toDictionary, toNamespaceDictionary } from "./to-dictionary.js";
-import type { DictionarySpec, ValidationResult } from "./types.js";
-import { validateNormalizedDictionary } from "./validate-normalized.js";
+import type {
+  DictionarySpec,
+  NormalizedKeyDictionary,
+  ValidationIssue,
+  ValidationResult,
+} from "./types.js";
+import { validateNormalizedKeyDictionaryPartial } from "./validate-normalized.js";
 
-export function validateExternalDictionary<TSchema>(
+export function validateExternalDictionaryPartial<TSchema>(
   input: unknown,
   spec: DictionarySpec
-): ValidationResult<TSchema> {
-  const step1 = normalizeDictionary(input, spec);
+): ValidationResult<Partial<TSchema>> {
+  if (spec.mode === "single") {
+    const step1 = normalizeKeyDictionaryPartial(input, spec.requiredKeys, spec.argsByKey, []);
+    if (!step1.ok) {
+      return step1;
+    }
+
+    const step2 = validateNormalizedKeyDictionaryPartial(step1.data, spec.argsByKey, spec, []);
+    if (!step2.ok) {
+      return step2;
+    }
+
+    return {
+      ok: true,
+      data: toDictionary({ mode: "single", keys: step2.data }) as Partial<TSchema>,
+    };
+  }
+
+  const step1 = normalizeDictionaryPartial(input, spec);
   if (!step1.ok) {
     return step1;
   }
 
-  const step2 = validateNormalizedDictionary(step1.data, spec);
-  if (!step2.ok) {
-    return step2;
+  if (step1.data.mode !== "multi") {
+    return {
+      ok: false,
+      issues: [
+        {
+          kind: "invalid_input",
+          message: "validateExternalDictionaryPartial requires multi-mode dictionary spec",
+        },
+      ],
+    };
+  }
+
+  const issues: ValidationIssue[] = [];
+  const namespaces: Record<string, NormalizedKeyDictionary> = {};
+
+  for (const [namespace, keys] of Object.entries(step1.data.namespaces)) {
+    const step2 = validateNormalizedKeyDictionaryPartial(
+      keys,
+      spec.argsByKey[namespace] ?? {},
+      spec,
+      [namespace]
+    );
+    if (!step2.ok) {
+      issues.push(...step2.issues);
+    } else {
+      namespaces[namespace] = step2.data;
+    }
+  }
+
+  if (issues.length > 0) {
+    return { ok: false, issues };
   }
 
-  return { ok: true, data: toDictionary(step2.data) as TSchema };
+  return {
+    ok: true,
+    data: toDictionary({ mode: "multi", namespaces }) as Partial<TSchema>,
+  };
 }
 
-export function validateExternalNamespace<TNamespaceSchema>(
+export function validateExternalNamespacePartial<TNamespaceSchema>(
   namespace: string,
   input: unknown,
   spec: DictionarySpec
-): ValidationResult<TNamespaceSchema> {
+): ValidationResult<Partial<TNamespaceSchema>> {
   if (spec.mode !== "multi") {
     return {
       ok: false,
       issues: [
         {
           kind: "invalid_input",
-          message: "validateExternalNamespace requires multi-mode dictionary spec",
+          message: "validateExternalNamespacePartial requires multi-mode dictionary spec",
         },
       ],
     };
   }
 
-  const wrapped = { [namespace]: input };
-  const namespaceSpec: DictionarySpec = {
-    mode: "multi",
-    requiredKeys: {
-      [namespace]: spec.requiredKeys[namespace] ?? [],
-    },
-    argsByKey: {
-      [namespace]: spec.argsByKey[namespace] ?? {},
-    },
-  };
+  const knownKeys = spec.requiredKeys[namespace];
+  if (!knownKeys) {
+    return {
+      ok: false,
+      issues: [{ kind: "unknown_key", path: [namespace] }],
+    };
+  }
 
-  const step1 = normalizeDictionary(wrapped, namespaceSpec);
+  const step1 = normalizeKeyDictionaryPartial(input, knownKeys, spec.argsByKey[namespace] ?? {}, [
+    namespace,
+  ]);
   if (!step1.ok) {
     return step1;
   }
 
-  const step2 = validateNormalizedDictionary(step1.data, namespaceSpec);
+  const step2 = validateNormalizedKeyDictionaryPartial(
+    step1.data,
+    spec.argsByKey[namespace] ?? {},
+    spec,
+    [namespace]
+  );
   if (!step2.ok) {
     return step2;
   }
 
   return {
     ok: true,
-    data: toNamespaceDictionary(step2.data, namespace) as TNamespaceSchema,
+    data: toNamespaceDictionary(
+      { mode: "multi", namespaces: { [namespace]: step2.data } },
+      namespace
+    ) as Partial<TNamespaceSchema>,
   };
 }
 
-export { normalizeDictionary, validateNormalizedDictionary, toDictionary, toNamespaceDictionary };
+export function validateExternalKey<TKeySlice>(
+  key: string,
+  input: unknown,
+  spec: Extract<DictionarySpec, { mode: "single" }>
+): ValidationResult<TKeySlice>;
+
+export function validateExternalKey<TKeySlice>(
+  namespace: string,
+  key: string,
+  input: unknown,
+  spec: Extract<DictionarySpec, { mode: "multi" }>
+): ValidationResult<TKeySlice>;
+
+export function validateExternalKey<TKeySlice>(
+  namespaceOrKey: string,
+  keyOrInput: string | unknown,
+  inputOrSpec?: unknown,
+  specMaybe?: DictionarySpec
+): ValidationResult<TKeySlice> {
+  if (specMaybe?.mode === "multi") {
+    const namespace = namespaceOrKey;
+    const key = keyOrInput as string;
+    const input = inputOrSpec;
+    const spec = specMaybe;
+
+    return validateExternalNamespacePartial<TKeySlice>(
+      namespace,
+      { [key]: input },
+      spec
+    ) as ValidationResult<TKeySlice>;
+  }
+
+  const key = namespaceOrKey;
+  const input = keyOrInput;
+  const spec = inputOrSpec as Extract<DictionarySpec, { mode: "single" }>;
+
+  return validateExternalDictionaryPartial<TKeySlice>(
+    { [key]: input },
+    spec
+  ) as ValidationResult<TKeySlice>;
+}
+
+export {
+  normalizeDictionaryPartial,
+  normalizeKeyDictionaryPartial,
+  toDictionary,
+  toNamespaceDictionary,
+};
+export { validateNormalizedKeyDictionaryPartial } from "./validate-normalized.js";
 export { createArgsSchema } from "./create-args-schema.js";
 export { createNormalizedDictionarySchema } from "./create-normalized-schema.js";
 export { DictionaryValidationError, assertValidDictionary, formatIssues } from "./errors.js";

package/src/validation/normalize.ts

@@ -1,5 +1,6 @@
 import { mergeVariableMetaAcrossLocales, type VariableMetaSpec } from "../icu/extract-variables.js";
 import { parseTemplate } from "../icu/parse-template.js";
+import type { VariableSpec } from "../icu/extract-variables.js";
 import type {
   DictionarySpec,
   NormalizedDictionary,
@@ -21,6 +22,68 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function normalizeSingleKey(
+  key: string,
+  keyValue: Record<string, unknown>,
+  keyPathPrefix: readonly string[]
+): { entry: ParsedKeyEntry; issues: ValidationIssue[] } {
+  const issues: ValidationIssue[] = [];
+  const locales: Record<string, ParsedKeyEntry["locales"][string]> = {};
+  const localeMetas: VariableMetaSpec[] = [];
+  let mergedArgs: ParsedKeyEntry["mergedArgs"] = {};
+  let localeArgsMismatch: ValidationIssue | undefined;
+
+  for (const [locale, template] of Object.entries(keyValue)) {
+    const localePath = [...keyPathPrefix, key, locale];
+
+    if (typeof template !== "string") {
+      issues.push({
+        kind: "invalid_locale_value",
+        path: localePath,
+        message: `expected string, got ${typeof template}`,
+      });
+      continue;
+    }
+
+    const parsed = parseTemplate(template);
+    if (!parsed.ok) {
+      issues.push({
+        kind: "icu_syntax_error",
+        path: localePath,
+        message: parsed.message,
+      });
+      continue;
+    }
+
+    locales[locale] = { template, args: parsed.args };
+    localeMetas.push(parsed.meta);
+  }
+
+  if (localeMetas.length > 0) {
+    const merged = mergeVariableMetaAcrossLocales(localeMetas);
+    if (!merged.ok) {
+      const localeArgs: Record<string, ParsedKeyEntry["mergedArgs"]> = {};
+      for (const [loc, entry] of Object.entries(locales)) {
+        localeArgs[loc] = entry.args;
+      }
+      localeArgsMismatch = {
+        kind: "locale_args_mismatch",
+        path: [...keyPathPrefix, key],
+        locales: localeArgs,
+        message: merged.message,
+      };
+    } else {
+      mergedArgs = merged.merged;
+    }
+  }
+
+  if (localeArgsMismatch) {
+    issues.push(localeArgsMismatch);
+  }
+
+  return { entry: { locales, mergedArgs }, issues };
+}
+
 function normalizeKeyDictionary(
   input: Record<string, unknown>,
   requiredKeys: readonly string[],
@@ -44,60 +107,70 @@ function normalizeKeyDictionary(
       continue;
     }
 
-    const locales: Record<string, ParsedKeyEntry["locales"][string]> = {};
-    const localeMetas: VariableMetaSpec[] = [];
-    let mergedArgs: ParsedKeyEntry["mergedArgs"] = {};
-    let localeArgsMismatch: ValidationIssue | undefined;
-
-    for (const [locale, template] of Object.entries(keyValue)) {
-      const localePath = [...keyPathPrefix, key, locale];
-
-      if (typeof template !== "string") {
-        issues.push({
-          kind: "invalid_locale_value",
-          path: localePath,
-          message: `expected string, got ${typeof template}`,
-        });
-        continue;
-      }
+    const result = normalizeSingleKey(key, keyValue, keyPathPrefix);
+    issues.push(...result.issues);
+    keys[key] = result.entry;
+  }
 
-      const parsed = parseTemplate(template);
-      if (!parsed.ok) {
-        issues.push({
-          kind: "icu_syntax_error",
-          path: localePath,
-          message: parsed.message,
-        });
-        continue;
-      }
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
 
-      locales[locale] = { template, args: parsed.args };
-      localeMetas.push(parsed.meta);
+  return { ok: true, data: keys };
+}
+
+/**
+ * Validation step 1 (partial): coerce external input into a normalized key dictionary
+ * for only the keys present in the payload.
+ */
+export function normalizeKeyDictionaryPartial(
+  input: unknown,
+  knownKeys: readonly string[],
+  _argsByKey: Readonly<Record<string, VariableSpec>>,
+  keyPathPrefix: readonly string[]
+): ValidationResult<NormalizedKeyDictionary> {
+  if (!isPlainObject(input)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          kind: "invalid_input",
+          message: `Expected object, got ${input === null ? "null" : typeof input}`,
+        },
+      ],
+    };
+  }
+
+  const knownKeysSet = new Set(knownKeys);
+  const issues: ValidationIssue[] = [];
+  const keys: Record<string, ParsedKeyEntry> = {};
+
+  for (const key of Object.keys(input)) {
+    if (!knownKeysSet.has(key)) {
+      issues.push({ kind: "unknown_key", path: [...keyPathPrefix, key] });
+      continue;
     }
 
-    if (localeMetas.length > 0) {
-      const merged = mergeVariableMetaAcrossLocales(localeMetas);
-      if (!merged.ok) {
-        const localeArgs: Record<string, ParsedKeyEntry["mergedArgs"]> = {};
-        for (const [loc, entry] of Object.entries(locales)) {
-          localeArgs[loc] = entry.args;
-        }
-        localeArgsMismatch = {
-          kind: "locale_args_mismatch",
-          path: [...keyPathPrefix, key],
-          locales: localeArgs,
-          message: merged.message,
-        };
-      } else {
-        mergedArgs = merged.merged;
-      }
+    const keyValue = input[key];
+    if (!isPlainObject(keyValue)) {
+      issues.push({
+        kind: "invalid_input",
+        message: `Expected object for key "${key}", got ${typeof keyValue}`,
+      });
+      continue;
     }
 
-    if (localeArgsMismatch) {
-      issues.push(localeArgsMismatch);
+    if (Object.keys(keyValue).length === 0) {
+      issues.push({
+        kind: "invalid_input",
+        message: `Key "${key}" must include at least one locale`,
+      });
+      continue;
     }
 
-    keys[key] = { locales, mergedArgs };
+    const result = normalizeSingleKey(key, keyValue, keyPathPrefix);
+    issues.push(...result.issues);
+    keys[key] = result.entry;
   }
 
   if (issues.length > 0) {
@@ -167,3 +240,60 @@ export function normalizeDictionary(
 
   return success({ mode: "multi", namespaces });
 }
+
+/**
+ * Validation step 1 (partial, multi): coerce external input into normalized namespace
+ * slices for only the namespaces and keys present in the payload.
+ */
+export function normalizeDictionaryPartial(
+  input: unknown,
+  spec: Extract<DictionarySpec, { mode: "multi" }>
+): ValidationResult<NormalizedDictionary> {
+  if (!isPlainObject(input)) {
+    return failure([
+      {
+        kind: "invalid_input",
+        message: `Expected object, got ${input === null ? "null" : typeof input}`,
+      },
+    ]);
+  }
+
+  const knownNamespaces = Object.keys(spec.requiredKeys);
+  const knownNamespacesSet = new Set(knownNamespaces);
+  const issues: ValidationIssue[] = [];
+  const namespaces: Record<string, NormalizedKeyDictionary> = {};
+
+  for (const namespace of Object.keys(input)) {
+    if (!knownNamespacesSet.has(namespace)) {
+      issues.push({ kind: "unknown_key", path: [namespace] });
+      continue;
+    }
+
+    const namespaceValue = input[namespace];
+    if (!isPlainObject(namespaceValue)) {
+      issues.push({
+        kind: "invalid_input",
+        message: `Expected object for namespace "${namespace}", got ${typeof namespaceValue}`,
+      });
+      continue;
+    }
+
+    const result = normalizeKeyDictionaryPartial(
+      namespaceValue,
+      spec.requiredKeys[namespace] ?? [],
+      spec.argsByKey[namespace] ?? {},
+      [namespace]
+    );
+    if (!result.ok) {
+      issues.push(...result.issues);
+    } else {
+      namespaces[namespace] = result.data;
+    }
+  }
+
+  if (issues.length > 0) {
+    return failure(issues);
+  }
+
+  return success({ mode: "multi", namespaces });
+}

package/src/validation/types.ts

@@ -41,6 +41,10 @@ export type ValidationIssue =
       readonly kind: "missing_key";
       readonly path: readonly string[];
     }
+  | {
+      readonly kind: "unknown_key";
+      readonly path: readonly string[];
+    }
   | {
       readonly kind: "invalid_locale_value";
       readonly path: readonly string[];