Convergent Replicated Map (CR-Map), a delta CRDT for dynamic non-empty string-keyed maps.

Read the specification:

• https://sovereignbase.dev/convergent-replicated-map

• Runtimes: Node >= 20, modern browsers, Bun, Deno, Cloudflare Workers, Edge Runtime.
• Module format: ESM + CommonJS.
• Required globals / APIs: EventTarget, CustomEvent, structuredClone.
• TypeScript: bundled types.

• Deterministic convergence of the live map 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.

npm install @sovereignbase/convergent-replicated-map
# or
pnpm add @sovereignbase/convergent-replicated-map
# or
yarn add @sovereignbase/convergent-replicated-map
# or
bun add @sovereignbase/convergent-replicated-map
# or
deno add jsr:@sovereignbase/convergent-replicated-map
# or
vlt install jsr:@sovereignbase/convergent-replicated-map

import { CRMap } from '@sovereignbase/convergent-replicated-map'

type EntryValue = {
  label: string
  version: number
}

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'
const KEY_B = '019d81fd-a1ea-75cf-b513-f35976cefc93'

const left = new CRMap<EntryValue>()
const right = new CRMap<EntryValue>()

left.addEventListener('delta', (event) => {
  right.merge(event.detail)
})

left.set(KEY_A, { label: 'alpha', version: 1 })
left.set(KEY_B, { label: 'beta', version: 1 })

console.log(right.get(KEY_A)?.label) // 'alpha'
console.log(right.entries())

import {
  CRMap,
  type CRMapSnapshot,
} from '@sovereignbase/convergent-replicated-map'

type EntryValue = {
  label: string
  version: number
}

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'

const source = new CRMap<EntryValue>()
let snapshot!: CRMapSnapshot<string, EntryValue>

source.addEventListener(
  'snapshot',
  (event) => {
    snapshot = event.detail
  },
  { once: true }
)

source.set(KEY_A, { label: 'draft', version: 1 })
source.snapshot()

const restored = new CRMap<EntryValue>(snapshot)

console.log(restored.get(KEY_A)?.label) // 'draft'

import { CRMap } from '@sovereignbase/convergent-replicated-map'

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'

const map = new CRMap<string>()

map.addEventListener('delta', (event) => {
  console.log('delta', event.detail)
})

map.addEventListener('change', (event) => {
  console.log('change', event.detail)
})

map.addEventListener('snapshot', (event) => {
  console.log('snapshot', event.detail)
})

map.addEventListener('ack', (event) => {
  console.log('ack', event.detail)
})

map.set(KEY_A, 'draft')
map.delete(KEY_A)
map.snapshot()
map.acknowledge()

import { CRMap } from '@sovereignbase/convergent-replicated-map'

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'
const KEY_B = '019d81fd-a1ea-75cf-b513-f35976cefc93'

const map = new CRMap<string>()

map.set(KEY_A, 'alpha')
map.set(KEY_B, 'beta')

const serialized = JSON.stringify(map)
const restored = new CRMap<string>(JSON.parse(serialized))

for (const [key, value] of map) {
  console.log(key, value)
}

map.forEach((value, key, target) => {
  console.log(key, value, target.size)
})

console.log(map.keys())
console.log(map.values())
console.log(map.entries())
console.log(restored.get(KEY_A)) // 'alpha'

This example assumes your map values are JSON-compatible. For general structuredClone-compatible values such as Date, Map, or BigInt, persist snapshots with a structured-clone-capable store or an application-level codec instead of plain JSON.stringify / JSON.parse.

get(), for...of, values(), entries(), and forEach() return detached copies of visible values. Mutating those returned values does not mutate the underlying replica state.

import { CRMap, type CRMapAck } from '@sovereignbase/convergent-replicated-map'

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'

const left = new CRMap<string>()
const right = new CRMap<string>()
const frontiers = new Map<string, CRMapAck>()

left.addEventListener('delta', (event) => right.merge(event.detail))
right.addEventListener('delta', (event) => left.merge(event.detail))

left.addEventListener('ack', (event) => {
  frontiers.set('left', event.detail)
})

right.addEventListener('ack', (event) => {
  frontiers.set('right', event.detail)
})

left.set(KEY_A, 'draft')
left.set(KEY_A, 'published')
left.delete(KEY_A)

left.acknowledge()
right.acknowledge()

left.garbageCollect([...frontiers.values()])
right.garbageCollect([...frontiers.values()])

If you need to build your own string-keyed CRDT binding instead of using the high-level CRMap 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 map abstractions, protocol wrappers, or framework-specific bindings while preserving the same convergence rules as the default CRMap binding.

import {
  __create,
  __update,
  __merge,
  __snapshot,
  type CRMapDelta,
  type CRMapSnapshot,
} from '@sovereignbase/convergent-replicated-map'

const KEY_A = '019d81fd-a1e9-76dd-aaf0-f4dd2ac2accc'

const replica = __create<string>()
const local = __update(KEY_A, 'draft', replica)

if (local) {
  const outgoing: CRMapDelta<string, string> = local.delta
  const remoteChange = __merge(outgoing, replica)

  console.log(remoteChange)
}

const snapshot: CRMapSnapshot<string, string> = __snapshot(replica)
console.log(snapshot)

The exports are grouped as follows:

• __create, __read, __update, __delete for local replica mutations.
• __merge, __acknowledge, __garbageCollect, __snapshot for gossip, compaction, and serialization.
• CRMap when you want the default event-driven class API.

Low-level exports and invalid public keyed mutations can throw CRMapError with stable error codes:

• INVALID_KEY
• VALUE_NOT_CLONEABLE

Ingress stays tolerant:

• malformed top-level merge payloads are ignored
• malformed snapshot values are dropped during hydration
• invalid UUIDs, invalid keys, and malformed entries are ignored
• duplicate identical deltas are idempotent
• stale same-key contenders can trigger a reply delta instead of mutating live state

• Snapshots are serializable full-state payloads with values and tombstones.
• Deltas are serializable partial snapshot payloads with values and tombstones.
• change is a minimal key-indexed visible patch where deleted keys map to undefined.
• toJSON() returns a detached serializable snapshot.
• JSON.stringify() and toString() are only reliable when map values are JSON-compatible.
• get(), for...of, values(), entries(), and forEach() expose detached copies of visible values rather than mutable references into replica state.
• keys(), set(), delete(), clear(), merge(), snapshot(), acknowledge(), and garbageCollect() all operate on the live map projection.

• The convergence target is the visible map projection, not identical internal tombstone sets.
• Same-key conflict resolution follows this order:
  • a direct descendant wins
  • the same UUID can advance via a larger predecessor
  • otherwise the larger UUIDv7 wins
• When local state already dominates an incoming contender, merge emits a reply delta instead of silently discarding that information.
• Tombstones remain until acknowledgement frontiers make them safe to collect.
• Garbage collection compacts tombstones below the smallest valid acknowledgement frontier while preserving active predecessor links.

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 CRMap surface: constructor, get(), has(), set(), delete(), clear(), iteration, forEach(), events, and JSON / inspect behavior.
• Core edge paths and hostile ingress handling for __create, __read, __update, __delete, __merge, __snapshot, __acknowledge, and __garbageCollect.
• Snapshot hydration edge cases for duplicate key contenders, tombstoned entries, malformed values, and stale helper-index cleanup.
• Integration convergence stress for:
  • local CRUD live-view semantics
  • snapshot hydration independent of entry order
  • merge idempotency for duplicate deltas
  • acknowledgement and garbage collection recovery
  • deterministic shuffled snapshot exchange
  • queued delta delivery with reply deltas and replica restarts
  • 25 aggressive deterministic convergence 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).

npm run bench

Last measured on Node v22.14.0 (win32 x64):

Apache-2.0