@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

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: