@noy-db/hub 0.2.0-pre.13 → 0.2.0-pre.15

package/dist/query/index.cjs

@@ -57,88 +57,156 @@ __export(query_exports, {
 });
 module.exports = __toCommonJS(query_exports);
 
-// src/query/predicate.ts
-function readPath(record, path) {
-  if (record === null || record === void 0) return void 0;
-  if (!path.includes(".")) {
-    return record[path];
+// src/money/fixed-point.ts
+function expandExponent(s) {
+  const m = /^([+-]?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
+  if (!m) return s;
+  const sign = m[1] === "-" ? "-" : "";
+  const intp = m[2];
+  const frac = m[3] ?? "";
+  const exp = Number(m[4]);
+  const digits = intp + frac;
+  const pointPos = intp.length + exp;
+  let body;
+  if (pointPos <= 0) {
+    body = "0." + "0".repeat(-pointPos) + digits;
+  } else if (pointPos >= digits.length) {
+    body = digits + "0".repeat(pointPos - digits.length);
+  } else {
+    body = digits.slice(0, pointPos) + "." + digits.slice(pointPos);
   }
-  const segments = path.split(".");
-  let cursor = record;
-  for (const segment of segments) {
-    if (cursor === null || cursor === void 0) return void 0;
-    cursor = cursor[segment];
+  return sign + body;
+}
+function toCanonicalDecimalString(input) {
+  let s;
+  if (typeof input === "number") {
+    if (!Number.isFinite(input)) return null;
+    s = String(input);
+  } else {
+    s = input.trim();
   }
-  return cursor;
+  s = expandExponent(s);
+  if (s.startsWith("+")) s = s.slice(1);
+  if (!/^-?(\d+(\.\d*)?|\.\d+)$/.test(s)) return null;
+  return s;
 }
-function evaluateFieldClause(record, clause) {
-  const actual = readPath(record, clause.field);
-  const { op, value } = clause;
-  switch (op) {
-    case "==":
-      return actual === value;
-    case "!=":
-      return actual !== value;
-    case "<":
-      return isComparable(actual, value) && actual < value;
-    case "<=":
-      return isComparable(actual, value) && actual <= value;
-    case ">":
-      return isComparable(actual, value) && actual > value;
-    case ">=":
-      return isComparable(actual, value) && actual >= value;
-    case "in":
-      return Array.isArray(value) && value.includes(actual);
-    case "contains":
-      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
-      if (Array.isArray(actual)) return actual.includes(value);
-      return false;
-    case "startsWith":
-      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
-    case "between": {
-      if (!Array.isArray(value) || value.length !== 2) return false;
-      const [lo, hi] = value;
-      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
-      return actual >= lo && actual <= hi;
-    }
-    default: {
-      const _exhaustive = op;
-      void _exhaustive;
+function shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAfterFirst, mode) {
+  switch (mode) {
+    case "up":
+      return true;
+    case "down":
       return false;
-    }
+    case "ceil":
+      return !negative;
+    case "floor":
+      return negative;
+    case "half-up":
+      return firstDiscarded >= 5;
+    case "half-down":
+      return firstDiscarded > 5 || firstDiscarded === 5 && hasMoreNonZeroAfterFirst;
+    case "half-even":
+      if (firstDiscarded > 5) return true;
+      if (firstDiscarded < 5) return false;
+      return hasMoreNonZeroAfterFirst || lastKeptDigit % 2 === 1;
   }
 }
-function isComparable(a, b) {
-  if (typeof a === "number" && typeof b === "number") return true;
-  if (typeof a === "string" && typeof b === "string") return true;
-  if (a instanceof Date && b instanceof Date) return true;
-  return false;
+function parseToScaledInt(input, scale, rounding) {
+  const canonical = toCanonicalDecimalString(input);
+  if (canonical === null) return { ok: false, reason: "nonfinite" };
+  const negative = canonical.startsWith("-");
+  const unsigned = negative ? canonical.slice(1) : canonical;
+  const dot = unsigned.indexOf(".");
+  const intPart = dot === -1 ? unsigned : unsigned.slice(0, dot);
+  const fracPart = dot === -1 ? "" : unsigned.slice(dot + 1);
+  const intDigits = intPart === "" ? "0" : intPart;
+  if (fracPart.length <= scale) {
+    const keep2 = fracPart.padEnd(scale, "0");
+    const magnitude2 = BigInt(intDigits + keep2);
+    return { ok: true, value: negative && magnitude2 !== 0n ? -magnitude2 : magnitude2 };
+  }
+  const keep = fracPart.slice(0, scale);
+  const tail = fracPart.slice(scale);
+  const magnitudeDigits = intDigits + keep;
+  let magnitude = BigInt(magnitudeDigits);
+  if (/^0+$/.test(tail)) {
+    return { ok: true, value: negative && magnitude !== 0n ? -magnitude : magnitude };
+  }
+  if (rounding === void 0) return { ok: false, reason: "precision" };
+  const lastKeptDigit = Number(magnitudeDigits[magnitudeDigits.length - 1]);
+  const firstDiscarded = Number(tail[0]);
+  const hasMoreNonZeroAfterFirst = /[1-9]/.test(tail.slice(1));
+  if (shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAfterFirst, rounding)) {
+    magnitude += 1n;
+  }
+  return { ok: true, value: negative && magnitude !== 0n ? -magnitude : magnitude };
 }
-function evaluateClause(record, clause) {
-  switch (clause.type) {
-    case "field":
-      return evaluateFieldClause(record, clause);
-    case "filter":
-      return clause.fn(record);
-    case "wherePredicate":
-      return clause.fn(record, clause.ctx);
-    case "crossJoin":
-      throw new Error(
-        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
-      );
-    case "group":
-      if (clause.op === "and") {
-        for (const child of clause.clauses) {
-          if (!evaluateClause(record, child)) return false;
-        }
-        return true;
-      } else {
-        for (const child of clause.clauses) {
-          if (evaluateClause(record, child)) return true;
-        }
-        return false;
-      }
-  }
+function formatScaledInt(value, scale) {
+  const negative = value < 0n;
+  const abs = (negative ? -value : value).toString();
+  if (scale === 0) return (negative ? "-" : "") + abs;
+  const padded = abs.padStart(scale + 1, "0");
+  const cut = padded.length - scale;
+  const intPart = padded.slice(0, cut);
+  const fracPart = padded.slice(cut);
+  return (negative ? "-" : "") + intPart + "." + fracPart;
+}
+
+// src/money/iso4217.ts
+var MINOR_UNITS = {
+  // 2-decimal majors
+  EUR: 2,
+  USD: 2,
+  GBP: 2,
+  CHF: 2,
+  CAD: 2,
+  AUD: 2,
+  NZD: 2,
+  SGD: 2,
+  HKD: 2,
+  CNY: 2,
+  INR: 2,
+  BRL: 2,
+  MXN: 2,
+  ZAR: 2,
+  RUB: 2,
+  TRY: 2,
+  PLN: 2,
+  SEK: 2,
+  NOK: 2,
+  DKK: 2,
+  CZK: 2,
+  HUF: 2,
+  RON: 2,
+  ILS: 2,
+  THB: 2,
+  PHP: 2,
+  MYR: 2,
+  IDR: 2,
+  AED: 2,
+  SAR: 2,
+  QAR: 2,
+  EGP: 2,
+  // 0-decimal
+  JPY: 0,
+  KRW: 0,
+  ISK: 0,
+  CLP: 0,
+  VND: 0,
+  XOF: 0,
+  XAF: 0,
+  PYG: 0,
+  // 3-decimal
+  BHD: 3,
+  KWD: 3,
+  OMR: 3,
+  TND: 3,
+  JOD: 3,
+  IQD: 3,
+  LYD: 3
+};
+function scaleForCurrency(code) {
+  const v = MINOR_UNITS[code];
+  return v === void 0 ? null : v;
 }
 
 // src/errors.ts
@@ -151,6 +219,12 @@ var NoydbError = class extends Error {
     this.code = code;
   }
 };
+var ValidationError = class extends NoydbError {
+  constructor(message = "Validation error") {
+    super("VALIDATION_ERROR", message);
+    this.name = "ValidationError";
+  }
+};
 var GroupCardinalityError = class extends NoydbError {
   /** The field being grouped on. */
   field;
@@ -256,6 +330,244 @@ var DanglingReferenceError = class extends NoydbError {
   }
 };
 
+// src/money/descriptor.ts
+var MoneyUnsupportedError = class extends NoydbError {
+  constructor(field, message) {
+    super(
+      "MONEY_UNSUPPORTED",
+      message ?? `money: operation is not supported on field "${field}" \u2014 use sum() and count() and divide at the boundary`
+    );
+    this.field = field;
+    this.name = "MoneyUnsupportedError";
+  }
+  field;
+};
+
+// src/money/where.ts
+function isMoneyValueObject(v) {
+  return typeof v === "object" && v !== null && "currency" in v;
+}
+function parseOperand(field, raw, desc) {
+  let amount;
+  let currency;
+  if (desc.mode === "fixed") {
+    currency = desc.fixedCurrency;
+    amount = raw;
+  } else if (isMoneyValueObject(raw)) {
+    currency = String(raw.currency);
+    amount = raw.amount;
+  } else {
+    const sole = desc.soleCurrency();
+    if (sole === void 0) {
+      throw new MoneyUnsupportedError(
+        `where("${field}"): field is multi-currency \u2014 compare against { amount, currency }, not a bare amount`
+      );
+    }
+    currency = sole;
+    amount = raw;
+  }
+  if (typeof amount !== "number" && typeof amount !== "string") {
+    throw new MoneyUnsupportedError(
+      `where("${field}"): operand ${JSON.stringify(raw)} is not a money amount`
+    );
+  }
+  const r = parseToScaledInt(amount, desc.scaleFor(currency), desc.rounding);
+  if (!r.ok) {
+    throw new MoneyUnsupportedError(
+      `where("${field}"): operand ${JSON.stringify(amount)} is not a finite decimal`
+    );
+  }
+  return { scaled: r.value.toString(), currency };
+}
+function moneyFieldClause(field, op, value, desc) {
+  switch (op) {
+    case "==":
+    case "!=":
+    case "<":
+    case "<=":
+    case ">":
+    case ">=": {
+      const e = parseOperand(field, value, desc);
+      return withMoney(field, op, value, desc, [e]);
+    }
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) {
+        throw new MoneyUnsupportedError(`where("${field}"): 'between' needs a [lo, hi] tuple`);
+      }
+      const lo = parseOperand(field, value[0], desc);
+      const hi = parseOperand(field, value[1], desc);
+      if (lo.currency !== hi.currency) {
+        throw new MoneyUnsupportedError(
+          `where("${field}"): 'between' bounds mix currencies (${lo.currency} vs ${hi.currency})`
+        );
+      }
+      return withMoney(field, op, value, desc, [lo, hi]);
+    }
+    case "in": {
+      if (!Array.isArray(value)) {
+        throw new MoneyUnsupportedError(`where("${field}"): 'in' needs an array of amounts`);
+      }
+      return withMoney(field, op, value, desc, value.map((v) => parseOperand(field, v, desc)));
+    }
+    default:
+      throw new MoneyUnsupportedError(
+        `where("${field}"): operator '${op}' is not supported on a money field`
+      );
+  }
+}
+function withMoney(field, op, originalValue, desc, entries) {
+  const money = { mode: desc.mode, entries };
+  const value = desc.mode !== "fixed" ? originalValue : entries.length === 1 && op !== "in" && op !== "between" ? entries[0].scaled : entries.map((e) => e.scaled);
+  return { type: "field", field, op, value, money };
+}
+function readStored(actual, operand) {
+  let amount;
+  let currency;
+  if (operand.mode === "fixed") {
+    if (typeof actual !== "string" && typeof actual !== "number") return null;
+    amount = actual;
+    currency = operand.entries[0]?.currency ?? "";
+  } else {
+    if (!isMoneyValueObject(actual)) return null;
+    if (typeof actual.currency !== "string") return null;
+    amount = actual.amount;
+    currency = actual.currency;
+  }
+  if (typeof amount !== "string" && typeof amount !== "number") return null;
+  try {
+    return { scaled: BigInt(amount).toString(), currency };
+  } catch {
+    return null;
+  }
+}
+function evaluateMoneyClause(actual, op, operand) {
+  const stored = readStored(actual, operand);
+  if (stored === null) return op === "!=";
+  const a = BigInt(stored.scaled);
+  if (op === "in") {
+    return operand.entries.some(
+      (e2) => e2.currency === stored.currency && BigInt(e2.scaled) === a
+    );
+  }
+  if (op === "between") {
+    const [lo, hi] = operand.entries;
+    if (!lo || !hi || lo.currency !== stored.currency) return false;
+    return a >= BigInt(lo.scaled) && a <= BigInt(hi.scaled);
+  }
+  const e = operand.entries[0];
+  if (!e) return false;
+  if (e.currency !== stored.currency) return op === "!=";
+  const b = BigInt(e.scaled);
+  switch (op) {
+    case "==":
+      return a === b;
+    case "!=":
+      return a !== b;
+    case "<":
+      return a < b;
+    case "<=":
+      return a <= b;
+    case ">":
+      return a > b;
+    case ">=":
+      return a >= b;
+    default:
+      return false;
+  }
+}
+
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  if (clause.money) return evaluateMoneyClause(actual, op, clause.money);
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause, fnRecord) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record);
+    case "wherePredicate":
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record, clause.ctx);
+    case "crossJoin":
+      throw new Error(
+        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
+      );
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child, fnRecord)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child, fnRecord)) return true;
+        }
+        return false;
+      }
+  }
+}
+function hasFnClause(clauses) {
+  for (const c of clauses) {
+    if (c.type === "filter" || c.type === "wherePredicate") return true;
+    if (c.type === "group" && hasFnClause(c.clauses)) return true;
+  }
+  return false;
+}
+
 // src/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
@@ -501,89 +813,6 @@ var NO_AGGREGATE = {
   }
 };
 
-// src/money/fixed-point.ts
-function formatScaledInt(value, scale) {
-  const negative = value < 0n;
-  const abs = (negative ? -value : value).toString();
-  if (scale === 0) return (negative ? "-" : "") + abs;
-  const padded = abs.padStart(scale + 1, "0");
-  const cut = padded.length - scale;
-  const intPart = padded.slice(0, cut);
-  const fracPart = padded.slice(cut);
-  return (negative ? "-" : "") + intPart + "." + fracPart;
-}
-
-// src/money/iso4217.ts
-var MINOR_UNITS = {
-  // 2-decimal majors
-  EUR: 2,
-  USD: 2,
-  GBP: 2,
-  CHF: 2,
-  CAD: 2,
-  AUD: 2,
-  NZD: 2,
-  SGD: 2,
-  HKD: 2,
-  CNY: 2,
-  INR: 2,
-  BRL: 2,
-  MXN: 2,
-  ZAR: 2,
-  RUB: 2,
-  TRY: 2,
-  PLN: 2,
-  SEK: 2,
-  NOK: 2,
-  DKK: 2,
-  CZK: 2,
-  HUF: 2,
-  RON: 2,
-  ILS: 2,
-  THB: 2,
-  PHP: 2,
-  MYR: 2,
-  IDR: 2,
-  AED: 2,
-  SAR: 2,
-  QAR: 2,
-  EGP: 2,
-  // 0-decimal
-  JPY: 0,
-  KRW: 0,
-  ISK: 0,
-  CLP: 0,
-  VND: 0,
-  XOF: 0,
-  XAF: 0,
-  PYG: 0,
-  // 3-decimal
-  BHD: 3,
-  KWD: 3,
-  OMR: 3,
-  TND: 3,
-  JOD: 3,
-  IQD: 3,
-  LYD: 3
-};
-function scaleForCurrency(code) {
-  const v = MINOR_UNITS[code];
-  return v === void 0 ? null : v;
-}
-
-// src/money/descriptor.ts
-var MoneyUnsupportedError = class extends NoydbError {
-  constructor(field, message) {
-    super(
-      "MONEY_UNSUPPORTED",
-      message ?? `money: operation is not supported on field "${field}" \u2014 use sum() and count() and divide at the boundary`
-    );
-    this.field = field;
-    this.name = "MoneyUnsupportedError";
-  }
-  field;
-};
-
 // src/money/money-reducer.ts
 function toScaledInt(v) {
   if (typeof v === "string" || typeof v === "number" || typeof v === "bigint") {
@@ -758,8 +987,107 @@ function wrapMoneyReducers(spec, moneyFields) {
   return changed ? out : spec;
 }
 
+// src/money/paths.ts
+var SEGMENT_RE = /^(\*|[^.[\]*]+)(\[\])?$/;
+var parseCache = /* @__PURE__ */ new Map();
+function parseMoneyPath(path) {
+  const cached = parseCache.get(path);
+  if (cached) return cached;
+  if (typeof path !== "string" || path.length === 0) {
+    throw new ValidationError("moneyFields: path must be a non-empty string");
+  }
+  const segments = [];
+  for (const part of path.split(".")) {
+    const m = SEGMENT_RE.exec(part);
+    if (!m) {
+      throw new ValidationError(
+        `moneyFields: invalid path "${path}" \u2014 segment "${part}" must be a key, "key[]", "*", or "*[]"`
+      );
+    }
+    const array = m[2] === "[]";
+    segments.push(
+      m[1] === "*" ? { kind: "wildcard", array } : { kind: "key", key: m[1], array }
+    );
+  }
+  parseCache.set(path, segments);
+  return segments;
+}
+function isSimpleMoneyPath(path) {
+  return !path.includes(".") && !path.includes("[") && !path.includes("*");
+}
+function transformAtMoneyPath(node, path, segments, index, visit, lenient) {
+  if (node === null || node === void 0) return node;
+  const seg = segments[index];
+  const last = index === segments.length - 1;
+  if (seg.kind === "key") {
+    if (typeof node !== "object" || Array.isArray(node)) {
+      if (lenient) return node;
+      throw new ValidationError(
+        `moneyFields: path "${path}" expected an object at segment "${seg.key}", got ${Array.isArray(node) ? "an array" : typeof node}`
+      );
+    }
+    const obj2 = node;
+    if (!(seg.key in obj2) || obj2[seg.key] === null || obj2[seg.key] === void 0) return node;
+    if (seg.array) {
+      const arr = obj2[seg.key];
+      if (!Array.isArray(arr)) {
+        if (lenient) return node;
+        throw new ValidationError(
+          `moneyFields: path "${path}" declares "${seg.key}[]" but the value is not an array`
+        );
+      }
+      const cloned = [...arr];
+      if (last) {
+        for (let i = 0; i < cloned.length; i++) visit(cloned, i);
+      } else {
+        for (let i = 0; i < cloned.length; i++) {
+          cloned[i] = transformAtMoneyPath(cloned[i], path, segments, index + 1, visit, lenient);
+        }
+      }
+      return { ...obj2, [seg.key]: cloned };
+    }
+    const clone2 = { ...obj2 };
+    if (last) {
+      visit(clone2, seg.key);
+    } else {
+      clone2[seg.key] = transformAtMoneyPath(clone2[seg.key], path, segments, index + 1, visit, lenient);
+    }
+    return clone2;
+  }
+  if (seg.array) {
+    if (!Array.isArray(node)) {
+      if (lenient) return node;
+      throw new ValidationError(`moneyFields: path "${path}" declares "*[]" but the value is not an array`);
+    }
+    const cloned = [...node];
+    if (last) {
+      for (let i = 0; i < cloned.length; i++) visit(cloned, i);
+    } else {
+      for (let i = 0; i < cloned.length; i++) {
+        cloned[i] = transformAtMoneyPath(cloned[i], path, segments, index + 1, visit, lenient);
+      }
+    }
+    return cloned;
+  }
+  if (typeof node !== "object" || Array.isArray(node)) {
+    if (lenient) return node;
+    throw new ValidationError(
+      `moneyFields: path "${path}" applies "*" to a non-object (${Array.isArray(node) ? 'array \u2014 use "*[]"' : typeof node})`
+    );
+  }
+  const obj = node;
+  const clone = { ...obj };
+  for (const key of Object.keys(obj)) {
+    const v = clone[key];
+    if (v === null || v === void 0) continue;
+    if (last) visit(clone, key);
+    else clone[key] = transformAtMoneyPath(v, path, segments, index + 1, visit, lenient);
+  }
+  return clone;
+}
+
 // src/money/normalize.ts
-function isMoneyValueObject(v) {
+function isMoneyValueObject2(v) {
   return typeof v === "object" && v !== null && "currency" in v;
 }
 function formatCurrency(decimal, currency, scale, locale) {
@@ -771,33 +1099,70 @@ function formatCurrency(decimal, currency, scale, locale) {
   });
   return fmt.format(decimal);
 }
+function decodeValue(stored, desc) {
+  let currency;
+  let scaledIntString;
+  if (desc.mode === "fixed") {
+    if (typeof stored !== "string" && typeof stored !== "number") return null;
+    currency = desc.fixedCurrency;
+    scaledIntString = String(stored);
+  } else {
+    if (!isMoneyValueObject2(stored)) return null;
+    const amount = stored.amount;
+    if (typeof stored.currency !== "string" || typeof amount !== "string" && typeof amount !== "number") return null;
+    currency = stored.currency;
+    scaledIntString = String(amount);
+  }
+  const scale = desc.scaleFor(currency);
+  let decimal;
+  try {
+    decimal = formatScaledInt(BigInt(scaledIntString), scale);
+  } catch {
+    return null;
+  }
+  return {
+    decoded: desc.mode === "fixed" ? decimal : { amount: decimal, currency },
+    decimal,
+    currency,
+    scale
+  };
+}
 function decodeMoneyFields(record, moneyFields, locale) {
-  const out = { ...record };
+  let out = { ...record };
   const format = locale !== "raw";
   const fmtLocale = typeof locale === "string" && locale !== "raw" ? locale : "en-US";
-  for (const [field, desc] of Object.entries(moneyFields)) {
-    const stored = out[field];
-    if (stored === null || stored === void 0) continue;
-    let currency;
-    let scaledIntString;
-    if (desc.mode === "fixed") {
-      if (typeof stored !== "string" && typeof stored !== "number") continue;
-      currency = desc.fixedCurrency;
-      scaledIntString = String(stored);
-    } else {
-      if (!isMoneyValueObject(stored)) continue;
-      const amount = stored.amount;
-      if (typeof stored.currency !== "string" || typeof amount !== "string" && typeof amount !== "number") continue;
-      currency = stored.currency;
-      scaledIntString = String(amount);
-    }
-    const scale = desc.scaleFor(currency);
-    const decimal = formatScaledInt(BigInt(scaledIntString), scale);
-    out[field] = desc.mode === "fixed" ? decimal : { amount: decimal, currency };
-    if (format) {
-      out[`${field}Formatted`] = formatCurrency(decimal, currency, scale, fmtLocale);
-      out[`${field}Number`] = Number(decimal);
-    }
+  for (const [path, desc] of Object.entries(moneyFields)) {
+    if (isSimpleMoneyPath(path)) {
+      const stored = out[path];
+      if (stored === null || stored === void 0) continue;
+      const r = decodeValue(stored, desc);
+      if (r === null) continue;
+      out[path] = r.decoded;
+      if (format) {
+        out[`${path}Formatted`] = formatCurrency(r.decimal, r.currency, r.scale, fmtLocale);
+        out[`${path}Number`] = Number(r.decimal);
+      }
+      continue;
+    }
+    out = transformAtMoneyPath(
+      out,
+      path,
+      parseMoneyPath(path),
+      0,
+      (container, key) => {
+        const stored = container[key];
+        if (stored === null || stored === void 0) return;
+        const r = decodeValue(stored, desc);
+        if (r === null) return;
+        container[key] = r.decoded;
+        if (format && typeof key === "string" && !Array.isArray(container)) {
+          container[`${key}Formatted`] = formatCurrency(r.decimal, r.currency, r.scale, fmtLocale);
+          container[`${key}Number`] = Number(r.decimal);
+        }
+      },
+      /* lenient */
+      true
+    );
   }
   return out;
 }
@@ -894,9 +1259,18 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  /**
+   * Add a field comparison. Multiple where() calls are AND-combined.
+   *
+   * A declared money field compares in MAJOR units (#336): the operand
+   * (`10000`, `'10000.00'`, or `{ amount, currency }` in multi mode) is
+   * quantized into stored scaled-int space at build time and evaluated
+   * BigInt-exact per record. A malformed operand or a string operator
+   * (`contains`/`startsWith`) throws here, at the call site.
+   */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const desc = this.source.moneyFields?.[field];
+    const clause = desc ? moneyFieldClause(field, op, value, desc) : { type: "field", field, op, value };
     return new _Query(
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
@@ -1222,7 +1596,7 @@ var Query = class _Query {
     }
     const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
     if (remainingClauses.length === 0) return candidates.length;
-    return filterRecords(candidates, remainingClauses).length;
+    return filterRecords(candidates, remainingClauses, fnViewDecoder(this.source)).length;
   }
   /**
    * Reduce the matching records through a named set of reducers.
@@ -1279,7 +1653,7 @@ var Query = class _Query {
         return executeClausePipeline(source, clauses, joinCtx);
       }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
-      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -1302,7 +1676,7 @@ var Query = class _Query {
         return executeClausePipeline(source, clauses, joinCtx);
       }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
-      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -1454,7 +1828,7 @@ function executePlanWithSource(source, plan, joinContext) {
     result = executeClausePipeline(source, plan.clauses, joinContext);
   } else {
     const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
@@ -1477,6 +1851,7 @@ function candidateRecords(source, clauses) {
     const clause = clauses[i];
     if (clause.type !== "field") continue;
     if (!indexes.has(clause.field)) continue;
+    if (clause.money?.mode === "multi") continue;
     let ids = null;
     if (clause.op === "==") {
       ids = indexes.lookupEqual(clause.field, clause.value);
@@ -1522,13 +1897,20 @@ function executePlan(records, plan) {
   }
   return result;
 }
-function filterRecords(records, clauses) {
+function fnViewDecoder(source) {
+  const mf = source.moneyFields;
+  if (!mf || Object.keys(mf).length === 0) return void 0;
+  return (r) => decodeMoneyFields(r, mf, "raw");
+}
+function filterRecords(records, clauses, decodeForFns) {
   if (clauses.length === 0) return [...records];
+  const needsFnView = decodeForFns !== void 0 && hasFnClause(clauses);
   const out = [];
   for (const r of records) {
+    const fnView = needsFnView ? decodeForFns(r) : void 0;
     let matches = true;
     for (const clause of clauses) {
-      if (!evaluateClause(r, clause)) {
+      if (!evaluateClause(r, clause, fnView)) {
         matches = false;
         break;
       }
@@ -1540,10 +1922,11 @@ function filterRecords(records, clauses) {
 function executeClausePipeline(source, clauses, joinContext) {
   let rel = [...source.snapshot()];
   let filterBatch = [];
+  const decodeForFns = fnViewDecoder(source);
   for (const clause of clauses) {
     if (clause.type === "crossJoin") {
       if (filterBatch.length > 0) {
-        rel = filterRecords(rel, filterBatch);
+        rel = filterRecords(rel, filterBatch, decodeForFns);
         filterBatch = [];
       }
       const rightSource = joinContext.resolveSource(clause.target);
@@ -1556,7 +1939,7 @@ function executeClausePipeline(source, clauses, joinContext) {
     }
   }
   if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
+    rel = filterRecords(rel, filterBatch, decodeForFns);
   }
   return rel;
 }
@@ -2351,7 +2734,8 @@ var ScanBuilder = class _ScanBuilder {
    * evaluates clauses per record in O(1) per clause.
    */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const desc = this.moneyFields?.[field];
+    const clause = desc ? moneyFieldClause(field, op, value, desc) : { type: "field", field, op, value };
     return new _ScanBuilder(
       this.pageProvider,
       this.pageSize,
@@ -2697,8 +3081,9 @@ var ScanBuilder = class _ScanBuilder {
    */
   recordMatches(record) {
     if (this.clauses.length === 0) return true;
+    const fnView = this.moneyFields && Object.keys(this.moneyFields).length > 0 && hasFnClause(this.clauses) ? this.decodeMoney(record) : void 0;
     for (const clause of this.clauses) {
-      if (!evaluateClause(record, clause)) return false;
+      if (!evaluateClause(record, clause, fnView)) return false;
     }
     return true;
   }