《互联网产品的客户端架构·规模化与架构演进》9.1 文案、时区与货币

item.one   = "{count} 件商品"
item.other = "{count} 件商品"

// file: src/i18n/locale-format.ts
// tier: L1
// verify: node --test test/i18n/locale-format.test.ts

export type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";

export type PluralForms = Partial<Record<PluralCategory, string>> & { other: string };

export type MessageBundle = Record<string, PluralForms | string>;

export type FormatParams = Record<string, string | number>;

export type ZonedParts = {
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
  second: number;
};

export type CurrencySpec = {
  code: string;
  minorUnits: number;
  cashIncrement: number;
};

export const CURRENCIES: Record<string, CurrencySpec> = {
  USD: { code: "USD", minorUnits: 2, cashIncrement: 1 },
  EUR: { code: "EUR", minorUnits: 2, cashIncrement: 1 },
  CNY: { code: "CNY", minorUnits: 2, cashIncrement: 1 },
  JPY: { code: "JPY", minorUnits: 0, cashIncrement: 1 },
  KWD: { code: "KWD", minorUnits: 3, cashIncrement: 1 },
  CHF: { code: "CHF", minorUnits: 2, cashIncrement: 5 },
  SEK: { code: "SEK", minorUnits: 2, cashIncrement: 100 },
  CLP: { code: "CLP", minorUnits: 0, cashIncrement: 1 },
};

export function currencySpec(code: string): CurrencySpec {
  const spec = CURRENCIES[code.toUpperCase()];
  if (!spec) throw new Error(`unknown currency: ${code}`);
  return spec;
}

export function selectPluralCategory(locale: string, count: number): PluralCategory {
  try {
    return new Intl.PluralRules(locale).select(count) as PluralCategory;
  } catch {
    return count === 1 ? "one" : "other";
  }
}

export function formatMessage(template: string, params: FormatParams): string {
  return template.replace(/\{([A-Za-z0-9_]+)\}/g, (match: string, key: string): string => {
    const value = params[key];
    return value === undefined ? match : String(value);
  });
}

export function missingPlaceholders(template: string, params: FormatParams): string[] {
  const found: string[] = [];
  for (const match of template.matchAll(/\{([A-Za-z0-9_]+)\}/g)) {
    const key = match[1];
    if (params[key] === undefined && !found.includes(key)) found.push(key);
  }
  return found;
}

export function formatPluralMessage(
  locale: string,
  bundle: MessageBundle,
  key: string,
  count: number,
  params: FormatParams = {},
): string {
  const entry = bundle[key];
  if (entry === undefined) throw new Error(`missing message: ${key}`);
  const forms: PluralForms = typeof entry === "string" ? { other: entry } : entry;
  const category = selectPluralCategory(locale, count);
  const template = forms[category] ?? forms.other;
  return formatMessage(template, { ...params, count });
}

function toDate(instant: string | number | Date): Date {
  const date = instant instanceof Date ? new Date(instant.getTime()) : new Date(instant);
  if (Number.isNaN(date.getTime())) throw new Error("invalid instant");
  return date;
}

export function toUtcIso(instant: string | number | Date): string {
  return toDate(instant).toISOString();
}

export function zonedParts(instant: string | number | Date, timeZone: string): ZonedParts {
  const date = toDate(instant);
  const parts = new Intl.DateTimeFormat("en-US", {
    timeZone,
    year: "numeric",
    month: "2-digit",
    day: "2-digit",
    hour: "2-digit",
    minute: "2-digit",
    second: "2-digit",
    hourCycle: "h23",
  }).formatToParts(date);
  const pick = (type: string): number => {
    const part = parts.find((item) => item.type === type);
    return Number(part?.value ?? "0");
  };
  return {
    year: pick("year"),
    month: pick("month"),
    day: pick("day"),
    hour: pick("hour"),
    minute: pick("minute"),
    second: pick("second"),
  };
}

export function zoneOffsetMinutes(instant: string | number | Date, timeZone: string): number {
  const date = toDate(instant);
  const parts = zonedParts(date, timeZone);
  const wall = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
  const epochSeconds = Math.floor(date.getTime() / 1000) * 1000;
  return Math.round((wall - epochSeconds) / 60000);
}

export function zonedIsoLike(instant: string | number | Date, timeZone: string): string {
  const parts = zonedParts(instant, timeZone);
  const pad = (value: number, width = 2): string => String(value).padStart(width, "0");
  return `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)} ${pad(parts.hour)}:${pad(parts.minute)}:${pad(parts.second)}`;
}

export function formatZoned(
  instant: string | number | Date,
  timeZone: string,
  locale: string,
): string {
  const date = toDate(instant);
  return new Intl.DateTimeFormat(locale, {
    timeZone,
    dateStyle: "medium",
    timeStyle: "short",
  }).format(date);
}

export function parseMajorToMinor(input: string | number, code: string): number {
  const spec = currencySpec(code);
  const text = typeof input === "number" ? input.toString() : input.trim();
  if (!/^-?\d+(?:\.\d+)?$/.test(text)) throw new Error(`invalid amount: ${text}`);
  const negative = text.startsWith("-");
  const digitsOnly = negative ? text.slice(1) : text;
  const [whole, fraction = ""] = digitsOnly.split(".");
  const scale = 10 ** spec.minorUnits;
  let minor = Number(whole) * scale;
  if (fraction.length <= spec.minorUnits) {
    const padded = fraction.padEnd(spec.minorUnits, "0");
    minor += Number(padded || "0");
  } else {
    minor += Number(fraction.slice(0, spec.minorUnits) || "0");
    const next = Number(fraction.charAt(spec.minorUnits));
    if (next >= 5) minor += 1;
  }
  return negative && minor !== 0 ? -minor : minor;
}

export function formatMinorAsDecimal(minor: number, code: string): string {
  const spec = currencySpec(code);
  const sign = minor < 0 ? "-" : "";
  const abs = Math.abs(Math.trunc(minor));
  if (spec.minorUnits === 0) return `${sign}${abs}`;
  const padded = String(abs).padStart(spec.minorUnits + 1, "0");
  return `${sign}${padded.slice(0, -spec.minorUnits)}.${padded.slice(-spec.minorUnits)}`;
}

export function roundCash(minor: number, code: string): number {
  const spec = currencySpec(code);
  const increment = spec.cashIncrement;
  if (increment <= 1) return minor;
  const sign = minor < 0 ? -1 : 1;
  const abs = Math.abs(Math.trunc(minor));
  const remainder = abs % increment;
  const down = abs - remainder;
  const rounded = remainder * 2 >= increment ? down + increment : down;
  return sign * rounded;
}

export function formatCurrency(minor: number, code: string, locale = "en-US"): string {
  const spec = currencySpec(code);
  const value = minor / 10 ** spec.minorUnits;
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency: spec.code,
    minimumFractionDigits: spec.minorUnits,
    maximumFractionDigits: spec.minorUnits,
  }).format(value);
}

export function allocateProportionally(totalMinor: number, weights: number[]): number[] {
  if (!Number.isInteger(totalMinor) || totalMinor < 0) {
    throw new Error("totalMinor must be a non-negative integer");
  }
  if (weights.length === 0) throw new Error("weights must not be empty");
  if (weights.some((weight) => !(weight >= 0)) || weights.every((weight) => weight === 0)) {
    throw new Error("weights must be non-negative and not all zero");
  }
  const sum = weights.reduce((acc, weight) => acc + weight, 0);
  const exact = weights.map((weight) => (totalMinor * weight) / sum);
  const base = exact.map((value) => Math.floor(value));
  const remaining = totalMinor - base.reduce((acc, value) => acc + value, 0);
  const order = exact
    .map((value, index) => ({ index, fraction: value - Math.floor(value) }))
    .sort((a, b) => b.fraction - a.fraction || a.index - b.index);
  const out = base.slice();
  for (let step = 0; step < remaining; step += 1) {
    out[order[step % order.length].index] += 1;
  }
  return out;
}