Zum Inhalt springen
Deutsch

Maps (LWWMap, ORMap, GCounterMap)

Drei Map-CRDTs, ausgewählt danach, was die Werte sind:

TypWert-TypWann
LWWMap<K, V>Plain Values (LWW pro Key)Konfig pro Key — Flags, Einstellungen.
ORMap<K, C>Andere CRDTsCounter, Sets, Register pro Key.
GCounterMap<K>Implizite GCounter-WerteCounts pro Key (Clicks pro Page, Requests pro Route).

GCounterMap<K> ist Zucker über ORMap<K, GCounter> — der Fall ist so häufig, dass er einen eigenen Typ bekommt.

import { LWWMap } from 'actor-ts/crdt';
let m = LWWMap.empty<string, string>();
m = m.put('node-a', 'theme', 'dark', 1000);
m = m.put('node-b', 'lang', 'en', 2000);
m.get('theme'); // → 'dark'
m.get('lang'); // → 'en'

LWW-Semantik pro Key — wie LWWRegister, aber indiziert. Nebenläufige Writes auf denselben Key werden über Timestamps aufgelöst; Writes auf verschiedene Keys kollidieren nicht.

m = m.remove('node-a', 'theme'); // ebenfalls LWW — jüngste Aktion gewinnt

remove wird ebenfalls als LWW-Operation getrackt — ein kürzlicher Remove schlägt ein älteres Put, auch von einer anderen Replika.

Nimm es für Konfig pro Key mit Einzelwert: User-Preferences, Feature-Flag-Overrides pro Tenant, Version pro Ressource.

import { ORMap, GCounter } from 'actor-ts/crdt';
let m = ORMap.empty<string, GCounter>();
m = m.update('node-a', 'clicks',
GCounter.empty,
(c) => c.increment('node-a', 1),
);
m = m.update('node-b', 'views',
GCounter.empty,
(c) => c.increment('node-b', 1),
);
m.get('clicks')?.value(); // → 1

Die Werte sind selbst CRDTs. Der Wert jedes Keys merged mit dem eigenen Merge des Value-CRDT — GCounter-Keys mergen per-Replika-Max, ORSet-Keys per Add-wins usw.

m = m.update('a', 'tags',
() => ORSet.empty<string>(),
(s) => s.add('a', 'urgent'),
);

Heterogene Wert-Typen sind erlaubt, aber abgeraten — eine einzelne ORMap hält typischerweise eine CRDT-Art pro Map. Wenn verschiedene Keys verschiedene Arten halten, kann das Framework die Typen nicht inferieren und du kämpfst mit dem Compiler.

Nimm es für replizierten State pro Key, der pro Key CRDT-Semantik braucht — Shopping-Carts pro User, Counter + Last-Changed-Register pro Feature.

m = m.remove('clicks');

Einen Key aus ORMap zu entfernen nutzt die OR-Semantik — getaggte Operation, die nebenläufige Re-Adds überschreiben können. Gleiche “Add wins”-Semantik wie bei ORSet.

Eine ORMap stellt beim Dekodieren eines Frames ihre eigene Key-Identität wieder her, die CRDTs in ihr bleiben aber auf der Standard-Regel JSON.stringify — die Grenze, die die Sets-Seite ausbuchstabiert, samt der Begründung, warum die äußere Funktion weiterzureichen schlimmer wäre als die Lücke (#1421). Am meisten zählt das dort, wo die Werte Sets sind: ORMap<RoomId, ORSet<UserId>> ist eine Form, die diese Seite empfiehlt, und genau das innere ORSet bekommt deine Identität nicht zurück.

Map-spezifisch ist die Frage, welche Operation sie noch retten kann. update nutzt den Wert weiter, der schon unter dem Key liegt — die factory, der einzige Ort, an dem die innere Identität steht, läuft für einen per Gossip angekommenen Key also nie, und ein zweites update bringt sie ihm ebenso wenig bei. Nach einem remove sieht get den Key nicht mehr, das nächste update ruft die Factory deshalb auf, und der Wert, den sie baut, trägt deine Identität.

Das ist ein Neuanfang und keine Reparatur, und der Unterschied zählt: Der Wert, der unter dem Key lag, ist weg — genau das bedeutet ein Remove —, und ein Peer, der den Stand von vor dem Remove noch hält, legt seine Elemente beim nächsten Merge wieder unter seinen eigenen Keys ab. Einen Key zu entfernen ist ein Weg, einen neuen Wert auf deine Identität zu bekommen, nie ein Weg, einen bestehenden umzuschlüsseln.

import { GCounterMap } from 'actor-ts/crdt';
let m = GCounterMap.empty<string>();
m = m.increment('node-a', 'page-home', 1);
m = m.increment('node-a', 'page-about', 1);
m = m.increment('node-b', 'page-home', 1);
m.value('page-home'); // → 2 (Summe über Replikas)
m.value('page-about'); // → 1

Eine GCounterMap<K> ist funktional ORMap<K, GCounter> — eine Map, deren Werte jeweils ein Counter sind. Sie existiert, weil Counts pro Key häufig genug sind (Page Views pro URL, Clicks pro Button, Requests pro Route), um eine getypte Abkürzung zu rechtfertigen.

Die API ist flacher:

m.increment(replicaId, key, delta); // den Counter eines Keys hochzählen
m.value(key); // → number (Summe über Replikas)
m.pairs(); // → ReadonlyArray<readonly [K, number]>

Nimm sie überall, wo du in normalem Code Map<K, number> schreiben würdest und Konvergenz bei nebenläufigen Writes brauchst.

Wert-Typ pro KeyMap-Typ
Ein Plain Value mit Last-Writer-Wins-AuflösungLWWMap
Ein CRDT (Counter, Set, Register, andere Map)ORMap
Ein Counter (sehr häufiger Fall)GCounterMap — Zucker über ORMap<K, GCounter>

Häufige Formen:

  • User-Preferences pro User — LWWMap<UserId, UserPrefs> (Pref-Edits sind LWW; Konflikte sind selten).
  • Feature Flags pro Tenant — LWWMap<TenantId, FlagSet>.
  • View Counts pro Ressource — GCounterMap<ResourceId>.
  • Online Members pro Raum — ORMap<RoomId, ORSet<UserId>>.
  • Rebalance Counts pro Shard — GCounterMap<ShardId>.
// Subscription-Set pro Raum + Nachrichtenzähler pro Raum
let rooms = ORMap.empty<string, ORSet<string>>();
let counts = GCounterMap.empty<string>();
rooms = rooms.update('a', 'general',
() => ORSet.empty<string>(),
(s) => s.add('a', 'user-1'),
);
counts = counts.increment('a', 'general', 1);

ORMap von ORSet ist die häufige Form für Map von Sets. ORMap von LWWRegister<T> ist eine getypte Version von LWWMap<K, T> mit denselben Semantiken (nimm direkt LWWMap, wenn du genau das meinst).

  • Counter — für nicht-keyed Counter.
  • Register — für nicht-keyed Einzelwerte.
  • Sets — für nicht-keyed Collections.
  • Daten gestalten — Auswahl zwischen flachen und Map-CRDTs.

Die API-Referenzen LWWMap, ORMap und GCounterMap decken die vollständige Oberfläche ab.