@xndrjs/i18n 0.6.0 → 0.7.0-alpha.0

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[];

package/src/validation/validate-normalized.ts

@@ -1,9 +1,13 @@
 import type { ZodError } from "zod";
 import { mapArgsSchemaError } from "./create-args-schema.js";
-import { createNormalizedDictionarySchema } from "./create-normalized-schema.js";
+import {
+  createKeyDictionarySchema,
+  createNormalizedDictionarySchema,
+} from "./create-normalized-schema.js";
 import type {
   DictionarySpec,
   NormalizedDictionary,
+  NormalizedKeyDictionary,
   ValidationIssue,
   ValidationResult,
   VariableSpec,
@@ -73,6 +77,44 @@ function mapZodError(
   });
 }
 
+export function validateNormalizedKeyDictionaryPartial(
+  keys: NormalizedKeyDictionary,
+  argsByKey: Readonly<Record<string, VariableSpec>>,
+  spec: DictionarySpec,
+  keyPathPrefix: readonly string[]
+): ValidationResult<NormalizedKeyDictionary> {
+  const presentKeys = Object.keys(keys);
+  const subsetArgsByKey = Object.fromEntries(
+    presentKeys.filter((key) => key in argsByKey).map((key) => [key, argsByKey[key]!])
+  );
+
+  if (presentKeys.length === 0) {
+    return { ok: true, data: keys };
+  }
+
+  const schema = createKeyDictionarySchema(subsetArgsByKey);
+  const result = schema.safeParse(keys);
+
+  if (result.success) {
+    return { ok: true, data: result.data };
+  }
+
+  const normalized: NormalizedDictionary =
+    spec.mode === "single"
+      ? { mode: "single", keys }
+      : {
+          mode: "multi",
+          namespaces: {
+            [keyPathPrefix[0] ?? ""]: keys,
+          },
+        };
+
+  return {
+    ok: false,
+    issues: mapZodError(result.error, spec, normalized),
+  };
+}
+
 export function validateNormalizedDictionary(
   normalized: NormalizedDictionary,
   spec: DictionarySpec