@sovereignbase/convergent-replicated-struct 0.0.0 → 1.1.0

package/README.md

@@ -1,271 +1,402 @@
-[![npm version](https://img.shields.io/npm/v/@sovereignbase/convergent-replicated-struct)](https://www.npmjs.com/package/@sovereignbase/convergent-replicated-struct)
-[![CI](https://github.com/sovereignbase/convergent-replicated-struct/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/sovereignbase/convergent-replicated-struct/actions/workflows/ci.yaml)
-[![codecov](https://codecov.io/gh/sovereignbase/convergent-replicated-struct/branch/master/graph/badge.svg)](https://codecov.io/gh/sovereignbase/convergent-replicated-struct)
-[![license](https://img.shields.io/npm/l/@sovereignbase/convergent-replicated-struct)](LICENSE)
-
-# convergent-replicated-struct
-
-State-based CRDT for fixed-key object structs with per-field overwrite tracking.
-
-## Compatibility
-
-- Runtimes: Node >= 20; modern browsers; Bun; Deno; Cloudflare Workers; Edge Runtime.
-- Module format: ESM + CommonJS.
-- Required globals / APIs: `EventTarget`, `CustomEvent`, `structuredClone`.
-- TypeScript: bundled types.
-
-## Goals
-
-- Fixed-key replica shape defined by a default struct.
-- One visible value per field at any time.
-- Malformed ingress is ignored during hydration and merge instead of crashing the replica.
-- `read()`, `values()`, `entries()`, snapshots, deltas, and change payloads are detached with `structuredClone`.
-- Explicit `acknowledge()` and `garbageCollect()` APIs for overwrite-history compaction.
-- Consistent behavior across Node, browsers, and worker/edge runtimes.
-
-## Installation
-
-```sh
-npm install @sovereignbase/convergent-replicated-struct
-# or
-pnpm add @sovereignbase/convergent-replicated-struct
-# or
-yarn add @sovereignbase/convergent-replicated-struct
-# or
-bun add @sovereignbase/convergent-replicated-struct
-# or
-deno add jsr:@sovereignbase/convergent-replicated-struct
-# or
-vlt install jsr:@sovereignbase/convergent-replicated-struct
-```
-
-## Usage
-
-### Copy-paste example
-
-```ts
-import { OOStruct } from '@sovereignbase/convergent-replicated-struct'
-
-type TodoStruct = {
-  title: string
-  count: number
-  meta: { done: boolean }
-  tags: string[]
-}
-
-const alice = OOStruct.create<TodoStruct>({
-  title: '',
-  count: 0,
-  meta: { done: false },
-  tags: [],
-})
-const bob = OOStruct.create<TodoStruct>({
-  title: '',
-  count: 0,
-  meta: { done: false },
-  tags: [],
-})
-
-alice.addEventListener('delta', (event) => bob.merge(event.detail))
-alice.update('title', 'hello world')
-alice.update('meta', { done: true })
-
-console.log(bob.read('title')) // "hello world"
-console.log(bob.read('meta')) // { done: true }
-```
-
-### Hydrating from a snapshot
-
-```ts
-import {
-  OOStruct,
-  type OOStructSnapshot,
-} from '@sovereignbase/convergent-replicated-struct'
-
-type DraftStruct = {
-  title: string
-  count: number
-}
-
-const source = new OOStruct<DraftStruct>({
-  title: '',
-  count: 0,
-})
-let snapshot!: OOStructSnapshot<DraftStruct>
-
-source.addEventListener(
-  'snapshot',
-  (event) => {
-    snapshot = event.detail
-  },
-  { once: true }
-)
-
-source.update('title', 'draft')
-source.snapshot()
-
-const restored = OOStruct.create<DraftStruct>(
-  {
-    title: '',
-    count: 0,
-  },
-  snapshot
-)
-
-console.log(restored.entries()) // [['title', 'draft'], ['count', 0]]
-```
-
-### Event channels
-
-```ts
-import { OOStruct } from '@sovereignbase/convergent-replicated-struct'
-
-const replica = new OOStruct({
-  name: '',
-  count: 0,
-})
-
-replica.addEventListener('delta', (event) => {
-  console.log('delta', event.detail)
-})
-
-replica.addEventListener('change', (event) => {
-  console.log('change', event.detail)
-})
-
-replica.addEventListener('ack', (event) => {
-  console.log('ack', event.detail)
-})
-
-replica.addEventListener('snapshot', (event) => {
-  console.log('snapshot', event.detail)
-})
-```
-
-### Acknowledgements and garbage collection
-
-```ts
-import {
-  OOStruct,
-  type OOStructAck,
-} from '@sovereignbase/convergent-replicated-struct'
-
-type CounterStruct = {
-  title: string
-  count: number
-}
-
-const left = new OOStruct<CounterStruct>({
-  title: '',
-  count: 0,
-})
-const right = new OOStruct<CounterStruct>({
-  title: '',
-  count: 0,
-})
-
-const frontiers: Array<OOStructAck<CounterStruct>> = []
-
-left.addEventListener(
-  'ack',
-  (event) => {
-    frontiers.push(event.detail)
-  },
-  { once: true }
-)
-
-right.addEventListener(
-  'ack',
-  (event) => {
-    frontiers.push(event.detail)
-  },
-  { once: true }
-)
-
-left.acknowledge()
-right.acknowledge()
-
-left.garbageCollect(frontiers)
-right.garbageCollect(frontiers)
-```
-
-## Runtime behavior
-
-### Validation and errors
-
-Local API misuse throws `OOStructError` with stable error codes:
-
-- `DEFAULTS_NOT_CLONEABLE`
-- `VALUE_NOT_CLONEABLE`
-- `VALUE_TYPE_MISMATCH`
-
-Hydration and merge are ingress-tolerant: malformed top-level payloads, unknown keys, malformed field entries, invalid UUIDs, invalid overwrite members, and mismatched runtime kinds are ignored instead of throwing.
-
-### Safety and copying semantics
-
-- Constructor defaults must be `structuredClone`-compatible.
-- `read()`, `values()`, and `entries()` return detached clones.
-- `delta`, `change`, and `snapshot` event payloads are detached from live state.
-- `update()` stores a cloned value, so later caller-side mutation does not mutate replica state through shared references.
-
-### Convergence and compaction
-
-- The convergence guarantee is the resolved live struct state.
-- Internal overwrite history may differ between replicas after acknowledgement-based garbage collection while the resolved live state still converges.
-- `garbageCollect()` compacts overwritten identifiers that are below the smallest acknowledgement frontier for a key while preserving the active predecessor link.
-
-## Tests
-
-- Suite: unit, integration, and end-to-end runtime tests.
-- Node test runner: `node --test` for unit and integration suites.
-- Coverage: `c8` with 100% statements / branches / functions / lines on built `dist/**/*.js`.
-- E2E runtimes: Node ESM, Node CJS, Bun ESM, Bun CJS, Deno ESM, Cloudflare Workers ESM, Edge Runtime ESM.
-- Browser E2E: Chromium, Firefox, WebKit, mobile Chrome, mobile Safari via Playwright.
-- Current status: `npm run test` passes on Node 22.14.0 (`win32 x64`).
-
-## Benchmarks
-
-How it was run:
-
-```sh
-node benchmark/bench.js
-```
-
-Environment: Node 22.14.0 (`win32 x64`)
-
-| Benchmark                     | Result                    |
-| ----------------------------- | ------------------------- |
-| constructor empty             | 44,359 ops/s (2254.3 ms)  |
-| constructor hydrate x64       | 19,610 ops/s (255.0 ms)   |
-| constructor hydrate x256      | 8,088 ops/s (247.3 ms)    |
-| constructor hydrate x1024     | 1,724 ops/s (290.0 ms)    |
-| create() empty                | 49,874 ops/s (2005.1 ms)  |
-| create() hydrate x256         | 6,886 ops/s (290.4 ms)    |
-| read primitive                | 846,289 ops/s (236.3 ms)  |
-| read object                   | 298,983 ops/s (668.9 ms)  |
-| read array                    | 278,710 ops/s (717.6 ms)  |
-| keys()                        | 32,349,896 ops/s (6.2 ms) |
-| values()                      | 103,489 ops/s (966.3 ms)  |
-| entries()                     | 110,300 ops/s (906.6 ms)  |
-| snapshot()                    | 65,513 ops/s (305.3 ms)   |
-| acknowledge()                 | 536,890 ops/s (93.1 ms)   |
-| update string                 | 29,547 ops/s (1692.2 ms)  |
-| update number                 | 30,591 ops/s (1634.5 ms)  |
-| update object                 | 22,114 ops/s (2261.0 ms)  |
-| update array                  | 24,763 ops/s (2019.1 ms)  |
-| delete(key)                   | 8,352 ops/s (5986.8 ms)   |
-| delete() reset all            | 6,836 ops/s (2925.5 ms)   |
-| merge direct successor        | 32,541 ops/s (1536.5 ms)  |
-| merge stale conflict          | 30,995 ops/s (645.3 ms)   |
-| merge hydrate snapshot x256   | 5,748 ops/s (869.9 ms)    |
-| merge noop duplicate          | 7,576 ops/s (6600.1 ms)   |
-| garbageCollect() x512 history | 3,111 ops/s (1607.0 ms)   |
-| add/remove listener roundtrip | 49,005 ops/s (4081.2 ms)  |
-| update with listeners         | 25,120 ops/s (1194.3 ms)  |
-| merge with listeners          | 31,649 ops/s (631.9 ms)   |
-
-Results vary by machine, runtime version, and payload shape.
-
-## License
-
-Apache-2.0
+[![npm version](https://img.shields.io/npm/v/@sovereignbase/convergent-replicated-list)](https://www.npmjs.com/package/@sovereignbase/convergent-replicated-struct)
+[![CI](https://github.com/sovereignbase/convergent-replicated-struct/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/sovereignbase/convergent-replicated-struct/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/sovereignbase/convergent-replicated-struct/branch/master/graph/badge.svg)](https://codecov.io/gh/sovereignbase/convergent-replicated-struct)
+[![license](https://img.shields.io/npm/l/@sovereignbase/convergent-replicated-struct)](LICENSE)
+
+# convergent-replicated-struct
+
+Convergent Replicated Struct (CR-Struct), a delta CRDT for an fixed-key object structs.
+
+## Compatibility
+
+- Runtimes: Node >= 20, modern browsers, Bun, Deno, Cloudflare Workers, Edge Runtime.
+- Module format: ESM + CommonJS.
+- Required globals / APIs: `EventTarget`, `CustomEvent`, `structuredClone`.
+- TypeScript: bundled types.
+
+## Goals
+
+- Deterministic convergence of the live struct projection under asynchronous gossip delivery.
+- Consistent behavior across Node, browsers, worker, and edge runtimes.
+- Garbage collection possibility without breaking live-view convergence.
+- Event-driven API
+
+## Installation
+
+```sh
+npm install @sovereignbase/convergent-replicated-struct
+# or
+pnpm add @sovereignbase/convergent-replicated-struct
+# or
+yarn add @sovereignbase/convergent-replicated-struct
+# or
+bun add @sovereignbase/convergent-replicated-struct
+# or
+deno add jsr:@sovereignbase/convergent-replicated-struct
+# or
+vlt install jsr:@sovereignbase/convergent-replicated-struct
+```
+
+## Usage
+
+### Copy-paste example
+
+```ts
+import {
+  CRStruct,
+  type CRStructSnapshot,
+} from '@sovereignbase/convergent-replicated-struct'
+
+type MetaStruct = {
+  done: boolean
+}
+
+type TodoStruct = {
+  title: string
+  count: number
+  meta: CRStructSnapshot<MetaStruct>
+  tags: string[]
+}
+
+const aliceMeta = new CRStruct<MetaStruct>({done: false})
+
+const alice = new CRStruct<TodoStruct>({
+  title: '',
+  count: 0,
+  meta: aliceMeta.toJSON()
+  tags: [],
+})
+
+const bobMeta = new CRStruct<MetaStruct>({done: false})
+
+const bob = new CRStruct<TodoStruct>({
+  title: '',
+  count: 0,
+  meta: bobMeta.toJSON()
+  tags: [],
+})
+
+alice.addEventListener('delta', (event) => {
+  bob.merge(event.detail)
+})
+
+aliceMeta.done = true
+
+alice.title = 'hello world'
+alice.meta = aliceMeta.toJSON()
+
+console.log(bob.title) // 'hello world'
+console.log(bobMeta.done) // true
+```
+
+### Hydrating from a snapshot
+
+```ts
+import {
+  CRStruct,
+  type CRStructSnapshot,
+} from '@sovereignbase/convergent-replicated-struct'
+
+type DraftStruct = {
+  title: string
+  count: number
+}
+
+const source = new CRStruct<DraftStruct>({
+  title: '',
+  count: 0,
+})
+let snapshot!: CRStructSnapshot<DraftStruct>
+
+source.addEventListener('snapshot', (event) => {
+  localStorage.setItem('snapshot', JSON.stringify(event.detail))
+})
+
+source.title = 'draft'
+source.snapshot()
+
+const restored = new CRStruct<DraftStruct>(
+  { title: '', count: 0 },
+  JSON.parse(localStorage.getItem('snapshot'))
+)
+
+console.log(restored.entries()) // [['title', 'draft'], ['count', 0]]
+```
+
+### Event channels
+
+```ts
+import { CRStruct } from '@sovereignbase/convergent-replicated-struct'
+
+const replica = new CRStruct({
+  name: '',
+  count: 0,
+})
+
+replica.addEventListener('delta', (event) => {
+  console.log('delta', event.detail)
+})
+
+replica.addEventListener('change', (event) => {
+  console.log('change', event.detail)
+})
+
+replica.addEventListener('ack', (event) => {
+  console.log('ack', event.detail)
+})
+
+replica.addEventListener('snapshot', (event) => {
+  console.log('snapshot', event.detail)
+})
+
+replica.name = 'alice'
+delete replica.name
+replica.snapshot()
+replica.acknowledge()
+```
+
+### Iteration and JSON serialization
+
+```ts
+import { CRStruct } from '@sovereignbase/convergent-replicated-struct'
+
+const struct = new CRStruct({
+  givenName: '',
+  familyName: '',
+})
+
+struct.givenName = 'Jori'
+struct.familyName = 'Lehtinen'
+
+for (const key in struct) console.log(key)
+for (const [key, val] of struct) console.log(key, val)
+console.log(struct.keys())
+console.log(struct.values())
+console.log(struct.entries())
+console.log(struct.clone())
+```
+
+Direct property reads, `for...of`, `values()`, `entries()`, and `clone()`
+return detached copies of visible values. Mutating those returned values does
+not mutate the underlying replica state.
+
+### Acknowledgements and garbage collection
+
+```ts
+import {
+  CRStruct,
+  type CRStructAck,
+} from '@sovereignbase/convergent-replicated-struct'
+
+type CounterStruct = {
+  title: string
+  count: number
+}
+
+const alice = new CRStruct<CounterStruct>({
+  title: '',
+  count: 0,
+})
+const bob = new CRStruct<CounterStruct>({
+  title: '',
+  count: 0,
+})
+
+const frontiers = new Map<string, CRStructAck<CounterStruct>>()
+
+alice.addEventListener('delta', (event) => {
+  bob.merge(event.detail)
+})
+
+bob.addEventListener('delta', (event) => {
+  alice.merge(event.detail)
+})
+
+alice.addEventListener('ack', (event) => {
+  frontiers.set('alice', event.detail)
+})
+
+bob.addEventListener('ack', (event) => {
+  frontiers.set('bob', event.detail)
+})
+
+alice.title = 'x'
+alice.title = 'y'
+delete alice.title
+
+alice.acknowledge()
+bob.acknowledge()
+
+alice.garbageCollect([...frontiers.values()])
+bob.garbageCollect([...frontiers.values()])
+```
+
+### Advanced exports
+
+If you need to build your own fixed-key CRDT binding instead of using the
+high-level `CRStruct` class, the package also exports the core CRUD and MAGS
+functions together with the replica and payload types.
+
+Those low-level exports let you build custom struct abstractions, protocol
+wrappers, or framework-specific bindings while preserving the same convergence
+rules as the default `CRStruct` binding.
+
+```ts
+import {
+  __create,
+  __update,
+  __merge,
+  __snapshot,
+  type CRStructDelta,
+  type CRStructSnapshot,
+} from '@sovereignbase/convergent-replicated-struct'
+
+type DraftStruct = {
+  title: string
+  count: number
+}
+
+const defaults: DraftStruct = {
+  title: '',
+  count: 0,
+}
+
+const replica = __create(defaults)
+const local = __update('title', 'draft', replica)
+
+if (local) {
+  const outgoing: CRStructDelta<DraftStruct> = local.delta
+  const remoteChange = __merge(outgoing, replica)
+
+  console.log(remoteChange)
+}
+
+const snapshot: CRStructSnapshot<DraftStruct> = __snapshot(replica)
+console.log(snapshot)
+```
+
+The intended split is:
+
+- `__create`, `__read`, `__update`, `__delete` for local replica mutations.
+- `__merge`, `__acknowledge`, `__garbageCollect`, `__snapshot` for gossip,
+  compaction, and serialization.
+- `CRStruct` when you want the default event-driven class API.
+
+## Runtime behavior
+
+### Validation and errors
+
+Low-level exports can throw `CRStructError` with stable error codes:
+
+- `DEFAULTS_NOT_CLONEABLE`
+- `VALUE_NOT_CLONEABLE`
+- `VALUE_TYPE_MISMATCH`
+
+Ingress stays tolerant:
+
+- malformed top-level merge payloads are ignored
+- malformed snapshot values are dropped during hydration
+- unknown keys are ignored
+- invalid UUIDs and malformed field entries are ignored
+- mismatched runtime kinds do not break live-state convergence
+
+### Safety and copying semantics
+
+- Snapshots are serializable full-state payloads keyed by field name.
+- Deltas are serializable gossip payloads keyed by field name.
+- `change` is a minimal field-keyed visible patch.
+- `toJSON()` returns a detached serializable snapshot.
+- Direct property reads, `for...of`, `values()`, `entries()`, and `clone()`
+  expose detached copies of visible values rather than mutable references into
+  replica state.
+- Property assignment, `delete`, `clear()`, `merge()`, `snapshot()`,
+  `acknowledge()`, and `garbageCollect()` all operate on the live struct
+  projection.
+
+### Convergence and compaction
+
+- The convergence target is the live struct projection, not identical internal
+  tombstone sets.
+- Tombstones remain until acknowledgement frontiers make them safe to collect.
+- Garbage collection compacts overwritten identifiers below the smallest valid
+  acknowledgement frontier for a field while preserving the active predecessor
+  link.
+- Internal overwrite history may differ between replicas after
+  acknowledgement-based garbage collection while the resolved live struct still
+  converges.
+
+## Tests
+
+```sh
+npm run test
+```
+
+What the current test suite covers:
+
+- Coverage on built `dist/**/*.js`: `100%` statements, `100%` branches,
+  `100%` functions, and `100%` lines via `c8`.
+- Public `CRStruct` surface: proxy property access, deletes, `clear()`,
+  iteration, events, and JSON / inspect behavior.
+- Core edge paths and hostile ingress handling for `__create`, `__read`,
+  `__update`, `__delete`, `__merge`, `__snapshot`, `__acknowledge`, and
+  `__garbageCollect`.
+- Snapshot hydration independent of field order, acknowledgement and garbage
+  collection recovery, and deterministic multi-replica gossip scenarios.
+- End-to-end runtime matrix for:
+  - Node ESM
+  - Node CJS
+  - Bun ESM
+  - Bun CJS
+  - Deno ESM
+  - Cloudflare Workers ESM
+  - Edge Runtime ESM
+  - Browsers via Playwright: Chromium, Firefox, WebKit, mobile Chrome, mobile Safari
+- Current status: `npm run test` passes on Node `v22.14.0` (`win32 x64`).
+
+## Benchmarks
+
+```sh
+npm run bench
+```
+
+The benchmark runner currently uses:
+
+- `HISTORY_DEPTH = 5_000`
+- `RUN_TIMES = 250`
+- output columns: `group`, `scenario`, `n`, `ops`, `ms`, `ms/op`, `ops/sec`
+
+Last measured on Node `v22.14.0` (`win32 x64`):
+
+| group   | scenario                         |     n | ops |     ms | ms/op |    ops/sec |
+| ------- | -------------------------------- | ----: | --: | -----: | ----: | ---------: |
+| `crud`  | `create / hydrate snapshot`      | 5,000 | 250 | 714.80 |  2.86 |     349.75 |
+| `crud`  | `read / primitive field`         | 5,000 | 250 |   0.55 |  0.00 | 450,531.63 |
+| `crud`  | `read / object field`            | 5,000 | 250 |   0.83 |  0.00 | 301,568.15 |
+| `crud`  | `update / overwrite string`      | 5,000 | 250 |   5.77 |  0.02 |  43,291.54 |
+| `crud`  | `update / overwrite object`      | 5,000 | 250 |   4.79 |  0.02 |  52,198.61 |
+| `crud`  | `delete / reset single field`    | 5,000 | 250 |   3.67 |  0.01 |  68,162.61 |
+| `crud`  | `delete / reset all fields`      | 5,000 | 250 |  18.86 |  0.08 |  13,253.95 |
+| `mags`  | `snapshot`                       | 5,000 | 250 |   7.80 |  0.03 |  32,062.38 |
+| `mags`  | `acknowledge`                    | 5,000 | 250 |  39.72 |  0.16 |   6,294.04 |
+| `mags`  | `garbage collect`                | 5,000 | 250 | 260.93 |  1.04 |     958.12 |
+| `mags`  | `merge ordered deltas`           | 5,000 | 250 | 204.53 |  0.82 |   1,222.32 |
+| `mags`  | `merge direct successor`         | 5,000 | 250 |   1.46 |  0.01 | 171,385.48 |
+| `mags`  | `merge shuffled gossip`          | 5,000 | 250 | 263.91 |  1.06 |     947.29 |
+| `mags`  | `merge stale conflict`           | 5,000 | 250 |   2.11 |  0.01 | 118,315.19 |
+| `class` | `constructor / hydrate snapshot` | 5,000 | 250 | 781.32 |  3.13 |     319.97 |
+| `class` | `property read / primitive`      | 5,000 | 250 |   0.45 |  0.00 | 559,659.73 |
+| `class` | `property read / object`         | 5,000 | 250 |   0.95 |  0.00 | 262,687.82 |
+| `class` | `property write / string`        | 5,000 | 250 |   5.04 |  0.02 |  49,613.02 |
+| `class` | `property write / object`        | 5,000 | 250 |   8.57 |  0.03 |  29,157.24 |
+| `class` | `delete property`                | 5,000 | 250 |   4.80 |  0.02 |  52,128.95 |
+| `class` | `clear()`                        | 5,000 | 250 |  15.35 |  0.06 |  16,283.14 |
+| `class` | `snapshot`                       | 5,000 | 250 |   9.49 |  0.04 |  26,356.29 |
+| `class` | `acknowledge`                    | 5,000 | 250 |  45.49 |  0.18 |   5,495.59 |
+| `class` | `garbage collect`                | 5,000 | 250 | 162.70 |  0.65 |   1,536.53 |
+| `class` | `merge ordered deltas`           | 5,000 | 250 | 193.20 |  0.77 |   1,293.98 |
+| `class` | `merge direct successor`         | 5,000 | 250 |   2.90 |  0.01 |  86,331.93 |
+| `class` | `merge shuffled gossip`          | 5,000 | 250 | 264.43 |  1.06 |     945.44 |
+
+## License
+
+Apache-2.0