@noy-db/hub 0.2.0-pre.10 → 0.2.0-pre.12

package/README.md

@@ -178,6 +178,132 @@ Core has zero `node:` imports — it runs unchanged in browsers, Node, Bun, Deno
 
 CSV, XML, xlsx, and the rest of the plaintext tier — plus encrypted `.noydb` bundles under the `as-noydb` encrypted tier — all live in the [`@noy-db/as-*`](https://www.npmjs.com/search?q=%40noy-db%2Fas-) family. Every invocation is gated by the two-tier authorization model (`canExportPlaintext` default off, `canExportBundle` default on for owner/admin) and lands in the audit ledger.
 
+## Money fields
+
+`money()` is a schema-layer field descriptor (a sibling of `i18nText()` / `dictKey()`) for currency-safe, exact decimal values. Money is stored as a scaled integer encoded as a **digit string**, so it is exact for any magnitude — past `Number.MAX_SAFE_INTEGER` included (a JSON number would silently truncate at 2^53).
+
+```ts
+vault.collection('invoices', {
+  schema: z.object({ id: z.string(), total: z.union([z.number(), z.string()]) }),
+  moneyFields: { total: money({ currency: 'EUR', scale: 2 }) }, // scale optional — ISO-4217 default
+})
+
+await invoices.put('a', { id: 'a', total: '123.45' })          // stored as '12345'
+const inv = await invoices.get('a', { locale: 'de-DE' })
+// inv.total           → '123.45'   (exact decimal string)
+// inv.totalFormatted  → '123,45 €' (Intl, full precision)
+// inv.totalNumber     → 123.45     (convenience JS number; lossy past 2^53)
+
+// Exact aggregation — sum/min/max run in BigInt, no float drift:
+invoices.query().aggregate({ total: sum('total') }).run() // → '0.60', never 0.6000000000000001
+```
+
+- **Rounding:** excess precision is **rejected** by default; opt in per field with `money({ ..., rounding: 'half-even' })` (`half-up` / `half-even` / `half-down` / `up` / `down` / `ceil` / `floor`).
+- **Multi-currency:** opt in with `money({ currencies: 'any' | ['EUR','USD'] })` — currency travels per record as `{ amount, currency }`; `sum` returns an exact per-currency map (`{ EUR: '15.50', USD: '3.00' }`), or one figure with `sum('total', { convertTo: 'EUR', fx })`.
+- Money `sum`/`min`/`max` implement incremental `remove()`, so they stay exact under live aggregation and materialized-view maintenance.
+
+## Computed fields
+
+`computed` declares schema-owned scalar fields derived on write — keeping the arithmetic next to the schema instead of scattered across handlers. Each function is pure and synchronous; they run **first** in the write pipeline (before schema validation), in declaration order, so a later field can read an earlier one. The result is **materialized** on the record — stored, queryable, and `aggregate(sum())`-able like any field.
+
+```ts
+vault.collection('lines', {
+  schema: z.object({
+    id: z.string(), unitPrice: z.number(), qty: z.number(),
+    netAmount: z.number().optional(), taxAmount: z.number().optional(), total: z.number().optional(),
+  }),
+  computed: {
+    netAmount: (r) => r.unitPrice * r.qty,
+    taxAmount: (r) => r.netAmount * 0.22,   // reads the field computed above
+    total:     (r) => r.netAmount + r.taxAmount,
+  },
+})
+
+await lines.put('a', { id: 'a', unitPrice: 10, qty: 3 })  // computed fields not supplied
+const line = await lines.get('a')   // → { …, netAmount: 30, taxAmount: 6.6, total: 36.6 }
+```
+
+- A computed field **overwrites** any user-supplied value of the same name (the field is schema-owned); a throwing function rejects the write with `ComputedFieldError`.
+- **Composes with `money()`** — declare a computed field as a money field too and it's quantized after evaluation, so `sum()` over it is exact.
+
+## Immutable collections (WORM)
+
+`immutableGuard` makes a collection write-once after a condition holds — issued invoices/DDTs that must never change. It's declarative sugar over `guards`: it generates the block-on-`check`/`onDelete` + ledgered admin-`amendment` strategy, so it reuses the whole guard machinery (and composes with `periods`/`history`).
+
+```ts
+import { createNoydb, immutableGuard } from '@noy-db/hub'
+
+await createNoydb({
+  store, user, secret,
+  guardStrategies: [
+    immutableGuard({ collection: 'invoices', after: (r) => r.status === 'issued' }),
+  ],
+})
+
+await invoices.put('a', { id: 'a', status: 'draft',  total: 100 }) // ok
+await invoices.put('a', { id: 'a', status: 'issued', total: 100 }) // ok — the transition write
+await invoices.put('a', { id: 'a', status: 'issued', total: 999 }) // ✗ RecordLockedError
+await invoices.delete('a')                                          // ✗ RecordLockedError
+
+// the sanctioned, ledgered override:
+await db.transaction({ amendment: true, reason: 'correct issued total' }, async (tx) => {
+  tx.vault('books').collection('invoices').put('a', { id: 'a', status: 'issued', total: 110 })
+})
+```
+
+- `after(record)` is evaluated on the **existing** record, so inserts and the write that *first* makes a record immutable are allowed; everything after is blocked.
+- `appendOnly: true` is shorthand for `after: () => true` — immutable from creation.
+- The admin/owner `amendment` path is the only way through, and every amendment is appended to the audit ledger.
+
+## Retention, legal-hold & archival
+
+For retention-bound data (e.g. 10-year fiscal records), two facilities share one rule — **a legal hold blocks eviction**.
+
+**Blob retention** (`vault.compact()`) gains a hold and a period-bound floor:
+
+```ts
+vault.collection('invoices', {
+  blobFields: {
+    pdf: {
+      retainDays: 3650,                              // base TTL
+      legalHold:  (r) => r.underLitigation === true, // never evict while held
+      retainUntil:(r) => r.fiscalYearEnd,            // floor: keep until period obligation ends
+    },
+  },
+})
+const { evicted, held } = await vault.compact() // held = retained-by-hold count
+```
+
+**Record archival** (`withArchive`) relocates sealed records to a cold store — envelope-level, no re-encryption — and restores on demand:
+
+```ts
+import { createNoydb, withArchive } from '@noy-db/hub'
+
+const db = await createNoydb({ store: primary, archiveStrategy: withArchive({ store: coldStore }) })
+vault.collection('invoices', {
+  archive: { archiveWhen: (r) => r.fiscalYear <= thisYear - 1, legalHold: (r) => r.underHold },
+})
+
+await vault.archive()                       // → { archived, held, scanned }
+await vault.listArchived('invoices')        // → [{ collection, id }, …]
+await vault.restore('invoices', 'inv-2020') // relocate back to primary (decryptable)
+```
+
+Archival uses low-level relocation, so it **bypasses guards** (issued/immutable records over a sealed period can still be archived) and doesn't recompute finalized aggregates. Archived records read `null` from the primary store until restored; a `legalHold` predicate blocks archival entirely.
+
+## Atomic sequences
+
+`vault.sequence(name)` gives gap-free, exactly-once numbering — the primitive fiscal/ERP/ticketing apps need for invoice or DDT numbers — backed by an optimistic compare-and-swap counter.
+
+```ts
+const n = await vault.sequence('invoice-2026').next()   // 1, then 2, 3, … no gaps, no duplicates
+const cur = await vault.sequence('invoice-2026').peek()  // read current value without allocating
+```
+
+- **Independent per name** — `sequence('invoice-2026')` and `sequence('ddt-2026')` are separate counters.
+- **Concurrency-safe** — concurrent `next()` calls retry on CAS contention (jittered backoff); a genuine burst beyond the retry budget surfaces `SequenceContentionError` so the caller can retry or queue.
+- **Online-only — by design.** Gap-free numbering needs single-authority serialization, which an offline writer can't provide. `next()` throws `SequenceOfflineError` unless the store advertises `capabilities.casAtomic`. This is the honest wall: assign each `next()` value to its record in the same operation (a discarded value is a gap in *usage*, not in the sequence).
+
 ## Status
 
 **Pre-release** (`0.1.0-pre.1`). API may change before `1.0`. Install from the `next` dist-tag:

package/dist/aggregate/index.cjs

@@ -218,6 +218,263 @@ var GroupCardinalityError = class extends NoydbError {
   }
 };
 
+// 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") {
+    try {
+      return BigInt(v);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function readMoney(record, field, desc) {
+  const raw = readPath(record, field);
+  if (raw === null || raw === void 0) return null;
+  if (desc.mode === "fixed") {
+    const value2 = toScaledInt(raw);
+    return value2 === null ? null : { currency: desc.fixedCurrency, value: value2 };
+  }
+  if (typeof raw !== "object") return null;
+  const o = raw;
+  if (typeof o.currency !== "string") return null;
+  const value = toScaledInt(o.amount);
+  return value === null ? null : { currency: o.currency, value };
+}
+function targetScaleFor(desc, currency) {
+  if (desc.allows(currency)) return desc.scaleFor(currency);
+  const s = scaleForCurrency(currency);
+  if (s === null) {
+    throw new Error(`money: cannot determine scale for conversion target "${currency}"`);
+  }
+  return s;
+}
+function parseRate(rate) {
+  const s = String(rate).trim();
+  const neg = s.startsWith("-");
+  const body = neg ? s.slice(1) : s;
+  const dot = body.indexOf(".");
+  const intPart = dot === -1 ? body : body.slice(0, dot);
+  const fracPart = dot === -1 ? "" : body.slice(dot + 1);
+  const int = BigInt((intPart === "" ? "0" : intPart) + fracPart);
+  return { int: neg ? -int : int, scale: fracPart.length };
+}
+function divRoundHalfEven(n, d) {
+  const q = n / d;
+  const r = n % d;
+  const twiceR = (r < 0n ? -r : r) * 2n;
+  if (twiceR < d) return q;
+  if (twiceR > d) return q + (n < 0n ? -1n : 1n);
+  return q % 2n === 0n ? q : q + (n < 0n ? -1n : 1n);
+}
+function convertScaled(value, srcScale, rate, targetScale) {
+  const { int: rateInt, scale: rateScale } = parseRate(rate);
+  const product = value * rateInt;
+  const curScale = srcScale + rateScale;
+  if (curScale === targetScale) return product;
+  if (curScale < targetScale) return product * 10n ** BigInt(targetScale - curScale);
+  return divRoundHalfEven(product, 10n ** BigInt(curScale - targetScale));
+}
+function finalizeSum(state, desc, convertTo, fx) {
+  if (convertTo !== void 0) {
+    if (fx === void 0) {
+      throw new Error(`money: sum convertTo "${convertTo}" requires an fx rate map`);
+    }
+    const targetScale = targetScaleFor(desc, convertTo);
+    let total = 0n;
+    for (const [cur, v] of state) {
+      if (cur === convertTo) {
+        total += convertScaled(v, desc.scaleFor(cur), 1, targetScale);
+        continue;
+      }
+      const rate = fx[`${cur}->${convertTo}`];
+      if (rate === void 0) {
+        throw new Error(`money: no fx rate for "${cur}->${convertTo}"`);
+      }
+      total += convertScaled(v, desc.scaleFor(cur), rate, targetScale);
+    }
+    return formatScaledInt(total, targetScale);
+  }
+  if (desc.mode === "fixed") {
+    const cur = desc.fixedCurrency;
+    return formatScaledInt(state.get(cur) ?? 0n, desc.scaleFor(cur));
+  }
+  const out = {};
+  for (const [cur, v] of state) out[cur] = formatScaledInt(v, desc.scaleFor(cur));
+  return out;
+}
+function moneySumReducer(field, desc, convertTo, fx) {
+  return {
+    op: "sum",
+    field,
+    init: () => /* @__PURE__ */ new Map(),
+    step: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) state.set(m.currency, (state.get(m.currency) ?? 0n) + m.value);
+      return state;
+    },
+    remove: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) state.set(m.currency, (state.get(m.currency) ?? 0n) - m.value);
+      return state;
+    },
+    finalize: (state) => finalizeSum(state, desc, convertTo, fx)
+  };
+}
+function extremum(values, op) {
+  let out = values[0];
+  for (let i = 1; i < values.length; i++) {
+    const v = values[i];
+    if (op === "min" ? v < out : v > out) out = v;
+  }
+  return out;
+}
+function moneyMinMaxReducer(op, field, desc) {
+  return {
+    op,
+    field,
+    init: () => /* @__PURE__ */ new Map(),
+    step: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) {
+        const arr = state.get(m.currency);
+        if (arr) arr.push(m.value);
+        else state.set(m.currency, [m.value]);
+      }
+      return state;
+    },
+    remove: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) {
+        const arr = state.get(m.currency);
+        if (arr) {
+          const idx = arr.indexOf(m.value);
+          if (idx >= 0) arr.splice(idx, 1);
+        }
+      }
+      return state;
+    },
+    finalize: (state) => {
+      if (desc.mode === "fixed") {
+        const cur = desc.fixedCurrency;
+        const arr = state.get(cur);
+        if (!arr || arr.length === 0) return null;
+        return formatScaledInt(extremum(arr, op), desc.scaleFor(cur));
+      }
+      const out = {};
+      for (const [cur, arr] of state) {
+        if (arr.length > 0) out[cur] = formatScaledInt(extremum(arr, op), desc.scaleFor(cur));
+      }
+      return out;
+    }
+  };
+}
+function wrapMoneyReducers(spec, moneyFields) {
+  let changed = false;
+  const out = {};
+  for (const [key, reducer] of Object.entries(spec)) {
+    const field = reducer.field;
+    const desc = field ? moneyFields[field] : void 0;
+    if (desc && reducer.op === "avg") {
+      throw new MoneyUnsupportedError(
+        field,
+        `avg() is not supported on money field "${field}" in v1 \u2014 use sum() and count() and divide at the boundary.`
+      );
+    }
+    if (desc && (reducer.op === "sum" || reducer.op === "min" || reducer.op === "max")) {
+      changed = true;
+      out[key] = reducer.op === "sum" ? moneySumReducer(field, desc, reducer.convertTo, reducer.fx) : moneyMinMaxReducer(reducer.op, field, desc);
+    } else {
+      out[key] = reducer;
+    }
+  }
+  return changed ? out : spec;
+}
+
 // src/aggregate/groupby.ts
 var GROUPBY_WARN_CARDINALITY = 1e4;
 var GROUPBY_MAX_CARDINALITY = 1e5;
@@ -235,15 +492,17 @@ function resetGroupByWarnings() {
   warnedCardinalityFields.clear();
 }
 var GroupedQueryBase = class {
-  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
+  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver, moneyFields) {
     this.executeRecords = executeRecords;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.moneyFields = moneyFields;
     this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
   }
   executeRecords;
   upstreams;
   dictLabelResolver;
+  moneyFields;
   /**
    * Field set this grouped query buckets on. Stored in declaration
    * order — the same order is preserved on every result row by
@@ -251,6 +510,10 @@ var GroupedQueryBase = class {
    * `[field]`.
    */
   fields;
+  /** Apply money-aware reducer rewriting when money fields are declared. */
+  wrapSpec(spec) {
+    return this.moneyFields ? wrapMoneyReducers(spec, this.moneyFields) : spec;
+  }
 };
 var GroupedQuery = class extends GroupedQueryBase {
   /**
@@ -263,7 +526,7 @@ var GroupedQuery = class extends GroupedQueryBase {
     return new GroupedAggregation(
       this.executeRecords,
       this.fields,
-      spec,
+      this.wrapSpec(spec),
       this.upstreams,
       this.dictLabelResolver
     );
@@ -274,7 +537,7 @@ var GroupedQueryN = class extends GroupedQueryBase {
     return new GroupedAggregation(
       this.executeRecords,
       this.fields,
-      spec,
+      this.wrapSpec(spec),
       this.upstreams,
       this.dictLabelResolver
     );
@@ -408,11 +671,11 @@ function withAggregate() {
     aggregate(executeRecords, spec, upstreams) {
       return new Aggregation(executeRecords, spec, upstreams);
     },
-    groupBy(executeRecords, field, upstreams, dictLabelResolver) {
-      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver);
+    groupBy(executeRecords, field, upstreams, dictLabelResolver, moneyFields) {
+      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver, moneyFields);
     },
-    groupByN(executeRecords, fields, upstreams) {
-      return new GroupedQueryN(executeRecords, fields, upstreams);
+    groupByN(executeRecords, fields, upstreams, moneyFields) {
+      return new GroupedQueryN(executeRecords, fields, upstreams, void 0, moneyFields);
     },
     async scanAggregate(iter, spec) {
       const collected = [];
@@ -431,7 +694,8 @@ function count(opts) {
     init: () => 0,
     step: (state) => state + 1,
     remove: (state) => state - 1,
-    finalize: (state) => state
+    finalize: (state) => state,
+    merge: (a, b) => a + b
   };
 }
 function sum(field, opts) {
@@ -440,10 +704,15 @@ function sum(field, opts) {
   return {
     op: "sum",
     field,
+    // Money-only metadata, read by `wrapMoneyReducers`. No effect on a
+    // generic numeric sum.
+    ...opts?.convertTo !== void 0 ? { convertTo: opts.convertTo } : {},
+    ...opts?.fx !== void 0 ? { fx: opts.fx } : {},
     init: () => 0,
     step: (state, record) => state + readNumber(record, field),
     remove: (state, record) => state - readNumber(record, field),
-    finalize: (state) => state
+    finalize: (state) => state,
+    merge: (a, b) => a + b
   };
 }
 function avg(field, opts) {
@@ -461,7 +730,8 @@ function avg(field, opts) {
       sum: state.sum - readNumber(record, field),
       count: state.count - 1
     }),
-    finalize: (state) => state.count === 0 ? null : state.sum / state.count
+    finalize: (state) => state.count === 0 ? null : state.sum / state.count,
+    merge: (a, b) => ({ sum: a.sum + b.sum, count: a.count + b.count })
   };
 }
 function pushValue(state, value) {
@@ -491,7 +761,8 @@ function min(field, opts) {
         if (v < out) out = v;
       }
       return out;
-    }
+    },
+    merge: (a, b) => ({ values: [...a.values, ...b.values] })
   };
 }
 function max(field, opts) {
@@ -511,11 +782,17 @@ function max(field, opts) {
         if (v > out) out = v;
       }
       return out;
-    }
+    },
+    merge: (a, b) => ({ values: [...a.values, ...b.values] })
   };
 }
 function readNumber(record, field) {
   const value = readPath(record, field);
+  if (typeof value === "object" && value !== null && "amount" in value && "currency" in value) {
+    throw new Error(
+      `aggregate: field "${field}" holds a money value but was not money-aware \u2014 declare it in the collection's moneyFields so sum/min/max stay exact`
+    );
+  }
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 // Annotate the CommonJS export names for ESM import in node: