@noy-db/hub 0.2.0-pre.18 → 0.2.0-pre.19

package/dist/periods/index.d.cts

@@ -1,12 +1,12 @@
-import { aj as PeriodsStrategy } from '../types-BpLPqyaO.cjs';
-export { ak as CarryForwardContext, al as ClosePeriodOptions, am as OpenPeriodOptions, an as PERIODS_COLLECTION, ao as PeriodRecord, ap as ReadOnlyCollection, aq as appendPeriodLedgerEntry, ar as assertTsWritable, as as chainAnchor, at as loadPeriods, au as validatePeriodName } from '../types-BpLPqyaO.cjs';
+import { a4 as PeriodsStrategy } from '../types-D-gr5t0G.cjs';
+export { a5 as CarryForwardContext, a6 as ClosePeriodOptions, a7 as OpenPeriodOptions, a8 as PERIODS_COLLECTION, a9 as PeriodRecord, aa as ReadOnlyCollection, ab as appendPeriodLedgerEntry, ac as assertTsWritable, ad as chainAnchor, ae as loadPeriods, af as validatePeriodName } from '../types-D-gr5t0G.cjs';
 import '../lazy-builder-eYZzLEL1.cjs';
 import '../predicate-BmhBSPCH.cjs';
-import '../strategy-nuyN8K5N.cjs';
-import '../errors-DUTlAt3Y.cjs';
+import '../strategy-C5ol6NdV.cjs';
+import '../errors-DL-zTrrF.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-C-SSRIxP.cjs';
-import '../index-C6lgoUhK.cjs';
+import '../index-BMmajblo.cjs';
+import '../index-BM7O48Ur.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/periods/index.d.ts

@@ -1,12 +1,12 @@
-import { aj as PeriodsStrategy } from '../types-Diqc2caK.js';
-export { ak as CarryForwardContext, al as ClosePeriodOptions, am as OpenPeriodOptions, an as PERIODS_COLLECTION, ao as PeriodRecord, ap as ReadOnlyCollection, aq as appendPeriodLedgerEntry, ar as assertTsWritable, as as chainAnchor, at as loadPeriods, au as validatePeriodName } from '../types-Diqc2caK.js';
+import { a4 as PeriodsStrategy } from '../types-CraiZOyO.js';
+export { a5 as CarryForwardContext, a6 as ClosePeriodOptions, a7 as OpenPeriodOptions, a8 as PERIODS_COLLECTION, a9 as PeriodRecord, aa as ReadOnlyCollection, ab as appendPeriodLedgerEntry, ac as assertTsWritable, ad as chainAnchor, ae as loadPeriods, af as validatePeriodName } from '../types-CraiZOyO.js';
 import '../lazy-builder-ChSqcF5t.js';
 import '../predicate-BmhBSPCH.js';
-import '../strategy-Diwh5lzS.js';
-import '../errors-DUTlAt3Y.js';
+import '../strategy-BDxQnnTX.js';
+import '../errors-DL-zTrrF.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-C-SSRIxP.js';
-import '../index-DP1JTWHZ.js';
+import '../index-BMmajblo.js';
+import '../index-BelbyUwz.js';
 import '@noy-db/attestation';
 
 /**

package/dist/periods/index.js

@@ -6,13 +6,13 @@ import {
   loadPeriods,
   validatePeriodName,
   withPeriods
-} from "../chunk-4UI5T3K7.js";
+} from "../chunk-YZE6C3TQ.js";
 import "../chunk-UF3BUNQZ.js";
-import "../chunk-MGB67HKX.js";
+import "../chunk-YX333DPS.js";
 import "../chunk-PDVP3C2I.js";
-import "../chunk-LGPSCKWZ.js";
-import "../chunk-QJKZ5WUP.js";
-import "../chunk-HMFC6M2G.js";
+import "../chunk-SHIUFIPW.js";
+import "../chunk-OKOKPYWH.js";
+import "../chunk-DJF3FXW5.js";
 export {
   PERIODS_COLLECTION,
   appendPeriodLedgerEntry,

package/dist/{public-envelope-HXOFHY4N.js → public-envelope-AGU6SS4Z.js}

@@ -12,9 +12,9 @@ import {
   resolveLocale,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-PGVEL5IZ.js";
-import "./chunk-LGPSCKWZ.js";
-import "./chunk-HMFC6M2G.js";
+} from "./chunk-E66DSTJP.js";
+import "./chunk-SHIUFIPW.js";
+import "./chunk-DJF3FXW5.js";
 export {
   DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
   PUBLIC_ENVELOPE_FIELDS,
@@ -28,4 +28,4 @@ export {
   savePublicEnvelope,
   validatePublicEnvelopeInput
 };
-//# sourceMappingURL=public-envelope-HXOFHY4N.js.map
+//# sourceMappingURL=public-envelope-AGU6SS4Z.js.map

package/dist/query/index.cjs

@@ -275,6 +275,18 @@ var IndexWriteFailureError = class extends NoydbError {
     this.cause = args.cause;
   }
 };
+var LocaleNotSpecifiedError = class extends NoydbError {
+  /** The field name that required a locale. */
+  field;
+  constructor(field, message) {
+    super(
+      "LOCALE_NOT_SPECIFIED",
+      message ?? `Cannot read i18nText field "${field}" without a locale. Pass { locale } to get()/list()/query() or set a default via openVault(name, { locale }).`
+    );
+    this.name = "LocaleNotSpecifiedError";
+    this.field = field;
+  }
+};
 var JoinTooLargeError = class extends NoydbError {
   leftRows;
   rightRows;
@@ -568,6 +580,198 @@ function hasFnClause(clauses) {
   return false;
 }
 
+// src/i18n/policy.ts
+function resolvePolicy(onMissing, layer) {
+  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
+  const scalar = typeof onMissing === "string" ? onMissing : void 0;
+  const layerDefault = layer === "guard" ? "substitute" : void 0;
+  return explicit ?? layerDefault ?? scalar ?? "throw";
+}
+
+// src/i18n/script.ts
+var LATIN_BASE = /* @__PURE__ */ new Set([
+  "en",
+  "fr",
+  "de",
+  "es",
+  "it",
+  "pt",
+  "nl",
+  "sv",
+  "no",
+  "da",
+  "fi",
+  "is",
+  "pl",
+  "cs",
+  "sk",
+  "hu",
+  "ro",
+  "hr",
+  "sl",
+  "et",
+  "lv",
+  "lt",
+  "tr",
+  "vi",
+  "id",
+  "ms",
+  "tl",
+  "sw",
+  "af",
+  "ca",
+  "gl",
+  "eu",
+  "cy",
+  "ga"
+]);
+var SCRIPT_TABLE = {
+  th: ["Thai"],
+  ko: ["Hangul", "Han"],
+  ja: ["Han", "Hiragana", "Katakana"],
+  zh: ["Han"],
+  ar: ["Arabic"],
+  fa: ["Arabic"],
+  ur: ["Arabic"],
+  ru: ["Cyrillic"],
+  uk: ["Cyrillic"],
+  bg: ["Cyrillic"],
+  sr: ["Cyrillic"],
+  he: ["Hebrew"],
+  el: ["Greek"],
+  hi: ["Devanagari"],
+  ta: ["Tamil"],
+  km: ["Khmer"],
+  lo: ["Lao"],
+  my: ["Myanmar"]
+};
+var SUBTAG_SCRIPTS = {
+  Latn: ["Latin"],
+  Cyrl: ["Cyrillic", "Latin"],
+  Hans: ["Han", "Latin"],
+  Hant: ["Han", "Latin"],
+  Thai: ["Thai", "Latin"],
+  Arab: ["Arabic", "Latin"]
+};
+function inferScripts(locale) {
+  const parts = locale.split("-");
+  const subtag = parts.find((t) => /^[A-Z][a-z]{3}$/.test(t));
+  if (subtag && SUBTAG_SCRIPTS[subtag]) return SUBTAG_SCRIPTS[subtag];
+  const base = (parts[0] ?? "").toLowerCase();
+  if (LATIN_BASE.has(base)) return ["Latin"];
+  const primary = SCRIPT_TABLE[base];
+  if (primary) return [...primary, "Latin"];
+  return ["Latin"];
+}
+var BASELINE = String.raw`\p{White_Space}\p{Script=Common}\p{Script=Inherited}\p{Mark}`;
+
+// src/i18n/core.ts
+function toChain(fallback) {
+  return Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+}
+function pickFromChain(value, chain) {
+  for (const fb of chain) {
+    if (fb === "any") {
+      const any = Object.values(value).find((v) => v !== "");
+      if (any !== void 0) return any;
+    } else if (value[fb] !== void 0 && value[fb] !== "") {
+      return value[fb];
+    }
+  }
+  return void 0;
+}
+function resolveI18nText(value, locale, fallback, field, opts) {
+  if (locale === "raw") {
+    return value;
+  }
+  if (!locale) {
+    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
+  }
+  if (value[locale] !== void 0 && value[locale] !== "") {
+    return value[locale];
+  }
+  const policy = opts?.policy ?? "throw";
+  const callerChain = toChain(fallback);
+  const callerHit = pickFromChain(value, callerChain);
+  if (callerHit !== void 0) return callerHit;
+  if (policy === "substitute") {
+    const subHit = pickFromChain(value, toChain(opts?.substitute));
+    if (subHit !== void 0) return subHit;
+    if (opts?.smartSubstitute) {
+      const smartHit = pickNearestScript(value, locale);
+      if (smartHit !== void 0) return smartHit;
+    }
+  }
+  if (policy === "throw") {
+    throw new LocaleNotSpecifiedError(
+      field ?? "<unknown>",
+      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
+    );
+  }
+  return null;
+}
+function pickNearestScript(value, target) {
+  const targetScript = inferScripts(target)[0] ?? "Latin";
+  let best;
+  for (const [loc, v] of Object.entries(value)) {
+    if (typeof v !== "string" || v === "") continue;
+    const s = inferScripts(loc)[0] ?? "Latin";
+    const score = s === targetScript ? 0 : s === "Latin" ? 1 : 2;
+    if (best === void 0 || score < best.score) best = { score, v };
+    if (score === 0) break;
+  }
+  return best?.v;
+}
+function applyAtPath(obj, path, locale, fallback, opts) {
+  const arrayIdx = path.indexOf("[].");
+  if (arrayIdx !== -1) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return obj;
+    return {
+      ...obj,
+      [arrayKey]: arr.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+        return applyAtPath(item, restPath, locale, fallback, opts);
+      })
+    };
+  }
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
+    return {
+      ...obj,
+      [head]: applyAtPath(nested, rest, locale, fallback, opts)
+    };
+  }
+  const raw = obj[path];
+  if (raw === void 0 || raw === null) return obj;
+  if (typeof raw !== "object" || Array.isArray(raw)) return obj;
+  return {
+    ...obj,
+    [path]: resolveI18nText(raw, locale, fallback, path, opts)
+  };
+}
+function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
+  const fieldNames = Object.keys(i18nFields);
+  if (fieldNames.length === 0) return record;
+  let result = record;
+  for (const [field, descriptor] of Object.entries(i18nFields)) {
+    const { onMissing, substitute, smartSubstitute } = descriptor.options;
+    const opts = {
+      policy: resolvePolicy(onMissing, layer),
+      ...substitute !== void 0 ? { substitute } : {},
+      ...smartSubstitute ? { smartSubstitute } : {}
+    };
+    result = applyAtPath(result, field, locale, fallback, opts);
+  }
+  return result;
+}
+
 // src/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
@@ -596,15 +800,15 @@ function warnCeilingApproaching(target, side, rows, maxRows) {
     `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
   );
 }
-function applyJoins(rows, joins, context) {
+function applyJoins(rows, joins, context, locale) {
   if (joins.length === 0) return [...rows];
   let result = [...rows];
   for (const leg of joins) {
-    result = applyOneJoin(result, leg, context);
+    result = applyOneJoin(result, leg, context, locale);
   }
   return result;
 }
-function applyOneJoin(leftRows, leg, context) {
+function applyOneJoin(leftRows, leg, context, locale) {
   if (leg.isDictJoin) {
     const dictSource = context.resolveDictSource?.(leg.field);
     if (!dictSource) {
@@ -659,24 +863,27 @@ function applyOneJoin(leftRows, leg, context) {
   if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
     warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
   }
+  const effLocale = locale ?? context.defaultLocale;
+  const i18nResolve = effLocale !== void 0 && source.i18nFields !== void 0 ? (right) => right !== null && typeof right === "object" ? applyI18nLocale(right, source.i18nFields, effLocale, void 0, "join") : right : void 0;
   const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
   if (strategy === "nested" && source.lookupById) {
     const lookup = (id) => source.lookupById?.(id);
-    return nestedLoopJoin(leftRows, leg, lookup);
+    return nestedLoopJoin(leftRows, leg, lookup, i18nResolve);
   }
-  return hashJoin(leftRows, leg, rightSnapshot);
+  return hashJoin(leftRows, leg, rightSnapshot, i18nResolve);
 }
-function nestedLoopJoin(leftRows, leg, lookupById) {
+function nestedLoopJoin(leftRows, leg, lookupById, i18nResolve) {
   const out = [];
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : lookupById(key);
+    let right = key === null ? void 0 : lookupById(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
 }
-function hashJoin(leftRows, leg, rightSnapshot) {
+function hashJoin(leftRows, leg, rightSnapshot, i18nResolve) {
   const rightMap = /* @__PURE__ */ new Map();
   for (const record of rightSnapshot) {
     const rawId = readPath(record, "id");
@@ -689,7 +896,8 @@ function hashJoin(leftRows, leg, rightSnapshot) {
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : rightMap.get(key);
+    let right = key === null ? void 0 : rightMap.get(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
@@ -1362,11 +1570,16 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Sort by a field. Subsequent calls are tie-breakers. */
-  orderBy(field, direction = "asc") {
+  /**
+   * Sort by a field. Subsequent calls are tie-breakers. Pass
+   * `{ by: 'label' }` to sort a `dictKey`/`staticDict` field by its resolved
+   * label at the query locale instead of the stored code (#285).
+   */
+  orderBy(field, direction = "asc", opts) {
+    const entry = opts?.by === "label" ? { field, direction, by: "label" } : { field, direction };
     return new _Query(
       this.source,
-      { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+      { ...this.plan, orderBy: [...this.plan.orderBy, entry] },
       this.joinContext,
       this.aggregateStrategy,
       this.predicates
@@ -1569,16 +1782,21 @@ var Query = class _Query {
    * carries any join legs, they are applied after `where` / `orderBy`
    * / `limit` / `offset` narrow the left set. See the `.join()` doc
    * for the ordering rationale.
+   *
+   * `opts.locale` (#285 §3) resolves JOINED right-side i18n fields at the
+   * `join` layer to that locale; without it, the owning collection's default
+   * locale applies, and a locale-less query leaves joined i18n fields raw.
+   * (Left/base i18n fields are resolved by `get`/`list`, not here.)
    */
-  toArray() {
-    const base = this.decodeMoney(executePlanWithSource(this.source, this.plan, this.joinContext));
+  toArray(opts) {
+    const base = this.decodeMoney(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
     if (this.plan.joins.length === 0) return base;
     if (!this.joinContext) {
       throw new Error(
         `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
       );
     }
-    return applyJoins(base, this.plan.joins, this.joinContext);
+    return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
   }
   /**
    * Decode this source's money fields on read (stored scaled-int → canonical
@@ -1597,9 +1815,9 @@ var Query = class _Query {
     if (!moneyFields || Object.keys(moneyFields).length === 0) return records;
     return records.map((r) => decodeMoneyFields(r, moneyFields, "raw"));
   }
-  /** Return the first matching record, or null. Joins are applied. */
-  first() {
-    const arr = this.limit(1).toArray();
+  /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields (#285 §3). */
+  first(opts) {
+    const arr = this.limit(1).toArray(opts);
     return arr[0] ?? null;
   }
   /**
@@ -1842,7 +2060,7 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan, joinContext) {
+function executePlanWithSource(source, plan, joinContext, locale) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
   let result;
   if (hasCrossJoins) {
@@ -1857,7 +2075,8 @@ function executePlanWithSource(source, plan, joinContext) {
     result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
   if (plan.orderBy.length > 0) {
-    result = sortRecords(result, plan.orderBy, source.moneyFields);
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale);
+    result = sortRecords(result, plan.orderBy, source.moneyFields, labelMaps);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -2014,11 +2233,19 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy, moneyFields) {
+function sortRecords(records, orderBy, moneyFields, labelMaps) {
   return [...records].sort((a, b) => {
-    for (const { field, direction } of orderBy) {
-      const av = readField(a, field);
-      const bv = readField(b, field);
+    for (const { field, direction, by } of orderBy) {
+      let av = readField(a, field);
+      let bv = readField(b, field);
+      const labelMap = by === "label" ? labelMaps?.get(field) : void 0;
+      if (labelMap) {
+        av = (typeof av === "string" ? labelMap.get(av) : void 0) ?? av;
+        bv = (typeof bv === "string" ? labelMap.get(bv) : void 0) ?? bv;
+        const cmp2 = compareValues(av, bv);
+        if (cmp2 !== 0) return direction === "asc" ? cmp2 : -cmp2;
+        continue;
+      }
       const desc = moneyFields?.[field];
       const cmp = desc ? compareMoney(av, bv, desc) : compareValues(av, bv);
       if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
@@ -2026,6 +2253,28 @@ function sortRecords(records, orderBy, moneyFields) {
     return 0;
   });
 }
+function buildOrderLabelMaps(orderBy, joinContext, locale) {
+  if (!joinContext?.resolveDictSource) return void 0;
+  const resolveDict = joinContext.resolveDictSource.bind(joinContext);
+  let maps;
+  for (const { field, by } of orderBy) {
+    if (by !== "label") continue;
+    const dictSource = resolveDict(field);
+    if (!dictSource) continue;
+    const loc = locale ?? dictSource.displayLocale;
+    if (loc === void 0) continue;
+    const codeToLabel = /* @__PURE__ */ new Map();
+    for (const entry of dictSource.snapshot()) {
+      const k = entry["key"];
+      const labels = entry["labels"];
+      const label = labels?.[loc];
+      if (typeof k === "string" && typeof label === "string") codeToLabel.set(k, label);
+    }
+    ;
+    (maps ??= /* @__PURE__ */ new Map()).set(field, codeToLabel);
+  }
+  return maps;
+}
 function compareMoney(a, b, desc) {
   const av = moneyScaledValue(a, desc);
   const bv = moneyScaledValue(b, desc);
@@ -2654,9 +2903,29 @@ var GroupedAggregation = class {
   upstreams;
   dictLabelResolver;
   fields;
-  /** Execute the query, group, reduce, and return an array of rows. */
-  run() {
-    return groupAndReduce(this.executeRecords(), this.fields, this.spec);
+  /**
+   * Execute the query, group, reduce, and return an array of rows.
+   *
+   * `opts` (#285 query-form MV grouping): when a `locale` + `i18nFields` are
+   * given, the declared group-key `i18nText` fields are resolved to that locale
+   * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+   * instead of a raw `{locale}` map. The MV executor passes the MV's
+   * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+   * unaffected.
+   */
+  run(opts) {
+    let records = this.executeRecords();
+    if (opts?.locale !== void 0 && opts.i18nFields !== void 0) {
+      const groupI18n = {};
+      for (const f of this.fields) {
+        const d = opts.i18nFields[f];
+        if (d !== void 0) groupI18n[f] = d;
+      }
+      if (Object.keys(groupI18n).length > 0) {
+        records = records.map((r) => applyI18nLocale(r, groupI18n, opts.locale, void 0, "mv"));
+      }
+    }
+    return groupAndReduce(records, this.fields, this.spec);
   }
   /**
    * Execute the query, group, reduce, and resolve `<field>Label` for