@loro-dev/flock-sqlite 0.1.0 → 0.5.0

package/src/index.ts

@@ -29,8 +29,9 @@ import type {
   ScanOptions,
   ScanRow,
   Value,
-  VersionVector,
+  VersionVector as VersionVectorType,
   VersionVectorEntry,
+  EntryInfo,
 } from "./types";
 
 type ClockRow = {
@@ -60,9 +61,20 @@ type PutOperation = {
   eventSink?: Array<{ key: KeyPart[]; payload: ExportPayload; source: string }>;
 };
 
+type EncodableVersionVectorEntry = {
+  peer: string;
+  peerBytes: Uint8Array;
+  timestamp: number;
+  counter: number;
+};
+
+export interface VersionVector extends VersionVectorType {}
+
 const textEncoder = new TextEncoder();
-const structuredCloneFn: (<T>(value: T) => T) | undefined =
-  (globalThis as typeof globalThis & { structuredClone?: <T>(value: T) => T }).structuredClone;
+const textDecoder = new TextDecoder();
+const structuredCloneFn: (<T>(value: T) => T) | undefined = (
+  globalThis as typeof globalThis & { structuredClone?: <T>(value: T) => T }
+).structuredClone;
 
 function utf8ByteLength(value: string): number {
   return textEncoder.encode(value).length;
@@ -74,11 +86,18 @@ function isValidPeerId(peerId: unknown): peerId is string {
 
 function createRandomPeerId(): string {
   const id = new Uint8Array(32);
-  const cryptoAny = typeof crypto !== "undefined" ? (crypto as any) : undefined;
-  if (cryptoAny?.getRandomValues) {
-    cryptoAny.getRandomValues(id);
-  } else if (cryptoAny?.randomBytes) {
-    const buf: Uint8Array = cryptoAny.randomBytes(32);
+  type CryptoLike = {
+    getRandomValues?: (buffer: Uint8Array) => Uint8Array;
+    randomBytes?: (len: number) => Uint8Array;
+  };
+  const cryptoLike: CryptoLike | undefined =
+    typeof crypto !== "undefined"
+      ? (crypto as unknown as CryptoLike)
+      : undefined;
+  if (cryptoLike?.getRandomValues) {
+    cryptoLike.getRandomValues(id);
+  } else if (cryptoLike?.randomBytes) {
+    const buf: Uint8Array = cryptoLike.randomBytes(32);
     id.set(buf);
   } else {
     for (let i = 0; i < 32; i += 1) {
@@ -115,7 +134,15 @@ function cloneMetadata(metadata: unknown): MetadataMap | undefined {
   return cloneJson(metadata as MetadataMap);
 }
 
-function assignPayload(target: ExportPayload, source?: ExportPayload | void): void {
+function normalizeMetadataMap(metadata: unknown): MetadataMap {
+  const cloned = cloneMetadata(metadata);
+  return cloned ?? {};
+}
+
+function assignPayload(
+  target: ExportPayload,
+  source?: ExportPayload | void,
+): void {
   if (!source || typeof source !== "object") {
     return;
   }
@@ -134,12 +161,253 @@ function clonePayload(payload: ExportPayload | undefined): ExportPayload {
   return result;
 }
 
-function mergePayload(base: ExportPayload, update?: ExportPayload | void): ExportPayload {
+function mergePayload(
+  base: ExportPayload,
+  update?: ExportPayload | void,
+): ExportPayload {
   const result = clonePayload(base);
   assignPayload(result, update);
   return result;
 }
 
+function comparePeerBytes(a: Uint8Array, b: Uint8Array): number {
+  if (a === b) {
+    return 0;
+  }
+  const limit = Math.min(a.length, b.length);
+  for (let i = 0; i < limit; i += 1) {
+    const diff = a[i] - b[i];
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return a.length - b.length;
+}
+
+function collectEncodableVersionVectorEntries(
+  vv?: VersionVector,
+): EncodableVersionVectorEntry[] {
+  if (!vv || typeof vv !== "object") {
+    return [];
+  }
+  const entries: EncodableVersionVectorEntry[] = [];
+  for (const [peer, entry] of Object.entries(vv)) {
+    if (!entry || !isValidPeerId(peer)) {
+      continue;
+    }
+    const { physicalTime, logicalCounter } = entry;
+    if (
+      typeof physicalTime !== "number" ||
+      !Number.isFinite(physicalTime) ||
+      typeof logicalCounter !== "number" ||
+      !Number.isFinite(logicalCounter)
+    ) {
+      continue;
+    }
+    const peerBytes = textEncoder.encode(peer);
+    entries.push({
+      peer,
+      peerBytes,
+      timestamp: Math.trunc(physicalTime),
+      counter: Math.max(0, Math.trunc(logicalCounter)),
+    });
+  }
+  entries.sort((a, b) => {
+    if (a.timestamp !== b.timestamp) {
+      return a.timestamp - b.timestamp;
+    }
+    const peerCmp = comparePeerBytes(a.peerBytes, b.peerBytes);
+    if (peerCmp !== 0) {
+      return peerCmp;
+    }
+    return a.counter - b.counter;
+  });
+  return entries;
+}
+
+function writeUnsignedLeb128(value: number, target: number[]): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new TypeError("leb128 values must be finite and non-negative");
+  }
+  let remaining = Math.trunc(value);
+  if (remaining === 0) {
+    target.push(0);
+    return;
+  }
+  while (remaining > 0) {
+    const byte = remaining % 0x80;
+    remaining = Math.floor(remaining / 0x80);
+    target.push(remaining > 0 ? byte | 0x80 : byte);
+  }
+}
+
+function writeVarStringBytes(bytes: Uint8Array, target: number[]): void {
+  writeUnsignedLeb128(bytes.length, target);
+  for (let i = 0; i < bytes.length; i += 1) {
+    target.push(bytes[i]);
+  }
+}
+
+const VERSION_VECTOR_MAGIC = new Uint8Array([86, 69, 86, 69]); // "VEVE"
+
+function encodeVersionVectorBinary(vv?: VersionVector): Uint8Array {
+  const entries = collectEncodableVersionVectorEntries(vv);
+  const buffer: number[] = Array.from(VERSION_VECTOR_MAGIC);
+  if (entries.length === 0) {
+    return Uint8Array.from(buffer);
+  }
+
+  let lastTimestamp = 0;
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i];
+    if (entry.timestamp < 0) {
+      throw new TypeError("timestamp must be non-negative");
+    }
+    if (i === 0) {
+      writeUnsignedLeb128(entry.timestamp, buffer);
+      lastTimestamp = entry.timestamp;
+    } else {
+      const delta = entry.timestamp - lastTimestamp;
+      if (delta < 0) {
+        throw new TypeError("version vector timestamps must be non-decreasing");
+      }
+      writeUnsignedLeb128(delta, buffer);
+      lastTimestamp = entry.timestamp;
+    }
+
+    writeUnsignedLeb128(entry.counter, buffer);
+    writeVarStringBytes(entry.peerBytes, buffer);
+  }
+
+  return Uint8Array.from(buffer);
+}
+
+function decodeUnsignedLeb128(
+  bytes: Uint8Array,
+  offset: number,
+): [number, number] {
+  let result = 0;
+  let multiplier = 1;
+  let consumed = 0;
+  while (offset + consumed < bytes.length) {
+    const byte = bytes[offset + consumed];
+    consumed += 1;
+    // Use arithmetic instead of bitwise operations to avoid 32-bit overflow.
+    // JavaScript bitwise operators convert to 32-bit signed integers,
+    // which breaks for values >= 2^31.
+    result += (byte & 0x7f) * multiplier;
+    if ((byte & 0x80) === 0) {
+      break;
+    }
+    multiplier *= 128;
+  }
+  return [result, consumed];
+}
+
+function decodeVarString(bytes: Uint8Array, offset: number): [string, number] {
+  const [length, used] = decodeUnsignedLeb128(bytes, offset);
+  const start = offset + used;
+  const end = start + length;
+  if (end > bytes.length) {
+    throw new TypeError("varString length exceeds buffer");
+  }
+  const slice = bytes.subarray(start, end);
+  return [textDecoder.decode(slice), used + length];
+}
+
+function hasMagic(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === VERSION_VECTOR_MAGIC[0] &&
+    bytes[1] === VERSION_VECTOR_MAGIC[1] &&
+    bytes[2] === VERSION_VECTOR_MAGIC[2] &&
+    bytes[3] === VERSION_VECTOR_MAGIC[3]
+  );
+}
+
+function decodeLegacyVersionVector(bytes: Uint8Array): VersionVector {
+  let offset = 0;
+  const [count, usedCount] = decodeUnsignedLeb128(bytes, offset);
+  offset += usedCount;
+  const [baseTimestamp, usedBase] = decodeUnsignedLeb128(bytes, offset);
+  offset += usedBase;
+  const vv: VersionVector = {};
+  for (let i = 0; i < count; i += 1) {
+    const [peer, usedPeer] = decodeVarString(bytes, offset);
+    offset += usedPeer;
+    if (!isValidPeerId(peer)) {
+      throw new TypeError("invalid peer id in encoded version vector");
+    }
+    const [delta, usedDelta] = decodeUnsignedLeb128(bytes, offset);
+    offset += usedDelta;
+    const [counter, usedCounter] = decodeUnsignedLeb128(bytes, offset);
+    offset += usedCounter;
+    vv[peer] = {
+      physicalTime: baseTimestamp + delta,
+      logicalCounter: counter,
+    };
+  }
+  return vv;
+}
+
+function decodeNewVersionVector(bytes: Uint8Array): VersionVector {
+  let offset = 4;
+  const vv: VersionVector = {};
+  if (offset === bytes.length) {
+    return vv;
+  }
+
+  const [firstTimestamp, usedTs] = decodeUnsignedLeb128(bytes, offset);
+  offset += usedTs;
+  const [firstCounter, usedCounter] = decodeUnsignedLeb128(bytes, offset);
+  offset += usedCounter;
+  const [firstPeer, usedPeer] = decodeVarString(bytes, offset);
+  offset += usedPeer;
+  if (!isValidPeerId(firstPeer)) {
+    throw new TypeError("invalid peer id in encoded version vector");
+  }
+  vv[firstPeer] = {
+    physicalTime: firstTimestamp,
+    logicalCounter: firstCounter,
+  };
+
+  let lastTimestamp = firstTimestamp;
+  while (offset < bytes.length) {
+    const [delta, usedDelta] = decodeUnsignedLeb128(bytes, offset);
+    offset += usedDelta;
+    const [counter, usedCtr] = decodeUnsignedLeb128(bytes, offset);
+    offset += usedCtr;
+    const [peer, usedPeerLen] = decodeVarString(bytes, offset);
+    offset += usedPeerLen;
+    if (!isValidPeerId(peer)) {
+      throw new TypeError("invalid peer id in encoded version vector");
+    }
+    const timestamp = lastTimestamp + delta;
+    if (timestamp < lastTimestamp) {
+      throw new TypeError("version vector timestamps must be non-decreasing");
+    }
+    vv[peer] = { physicalTime: timestamp, logicalCounter: counter };
+    lastTimestamp = timestamp;
+  }
+
+  return vv;
+}
+
+function decodeVersionVectorBinary(bytes: Uint8Array): VersionVector {
+  if (hasMagic(bytes)) {
+    return decodeNewVersionVector(bytes);
+  }
+  return decodeLegacyVersionVector(bytes);
+}
+
+export function encodeVersionVector(vector: VersionVector): Uint8Array {
+  return encodeVersionVectorBinary(vector);
+}
+
+export function decodeVersionVector(bytes: Uint8Array): VersionVector {
+  return decodeVersionVectorBinary(bytes);
+}
+
 function buildRecord(clock: EntryClock, payload: ExportPayload): ExportRecord {
   const record: ExportRecord = {
     c: formatClock(clock),
@@ -154,7 +422,10 @@ function buildRecord(clock: EntryClock, payload: ExportPayload): ExportRecord {
   return record;
 }
 
-function normalizeImportDecision(decision: ImportDecision): { accept: boolean; reason?: string } {
+function normalizeImportDecision(decision: ImportDecision): {
+  accept: boolean;
+  reason?: string;
+} {
   if (!decision || typeof decision !== "object") {
     return { accept: true };
   }
@@ -167,7 +438,9 @@ function normalizeImportDecision(decision: ImportDecision): { accept: boolean; r
   return { accept: true };
 }
 
-function isExportOptions(arg: VersionVector | ExportOptions | undefined): arg is ExportOptions {
+function isExportOptions(
+  arg: VersionVector | ExportOptions | undefined,
+): arg is ExportOptions {
   return (
     typeof arg === "object" &&
     arg !== null &&
@@ -178,8 +451,14 @@ function isExportOptions(arg: VersionVector | ExportOptions | undefined): arg is
   );
 }
 
-function isImportOptions(arg: ExportBundle | ImportOptions): arg is ImportOptions {
-  return typeof arg === "object" && arg !== null && Object.prototype.hasOwnProperty.call(arg, "bundle");
+function isImportOptions(
+  arg: ExportBundle | ImportOptions,
+): arg is ImportOptions {
+  return (
+    typeof arg === "object" &&
+    arg !== null &&
+    Object.prototype.hasOwnProperty.call(arg, "bundle")
+  );
 }
 
 function parseMetadata(json: string | null): MetadataMap | undefined {
@@ -219,6 +498,31 @@ function parseClockString(raw: string): EntryClock {
   };
 }
 
+function normalizeRowClock(
+  physical: unknown,
+  logical: unknown,
+  peer: unknown,
+): EntryClock | undefined {
+  if (
+    typeof physical !== "number" ||
+    typeof logical !== "number" ||
+    typeof peer !== "string"
+  ) {
+    return undefined;
+  }
+  if (!isValidPeerId(peer)) {
+    return undefined;
+  }
+  if (!Number.isFinite(physical) || !Number.isFinite(logical)) {
+    return undefined;
+  }
+  return {
+    physicalTime: physical,
+    logicalCounter: Math.trunc(logical),
+    peerId: peer,
+  };
+}
+
 function formatClock(clock: EntryClock): string {
   return `${clock.physicalTime},${clock.logicalCounter},${clock.peerId}`;
 }
@@ -236,7 +540,9 @@ function compareClock(a: EntryClock, b: EntryClock): number {
   return a.peerId > b.peerId ? 1 : -1;
 }
 
-function normalizeVersionEntry(entry?: VersionVectorEntry): VersionVectorEntry | undefined {
+function normalizeVersionEntry(
+  entry?: VersionVectorEntry,
+): VersionVectorEntry | undefined {
   if (!entry) return undefined;
   const { physicalTime, logicalCounter } = entry;
   if (!Number.isFinite(physicalTime) || !Number.isFinite(logicalCounter)) {
@@ -296,7 +602,9 @@ function normalizeTablePrefix(prefix?: string): string {
     throw new TypeError("tablePrefix must be a string");
   }
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
-    throw new TypeError("tablePrefix must start with a letter/underscore and use only letters, digits, or underscores");
+    throw new TypeError(
+      "tablePrefix must start with a letter/underscore and use only letters, digits, or underscores",
+    );
   }
   return prefix;
 }
@@ -319,14 +627,38 @@ export class FlockSQLite {
   private maxHlc: { physicalTime: number; logicalCounter: number };
   private listeners: Set<EventListener>;
   private tables: TableNames;
-
-  private constructor(db: UniStoreConnection, peerId: string, vv: Map<string, VersionVectorEntry>, maxHlc: { physicalTime: number; logicalCounter: number }, tables: TableNames) {
+  /** Transaction state: undefined when not in transaction, array when accumulating */
+  private txnEventSink:
+    | Array<{ key: KeyPart[]; payload: ExportPayload; source: string }>
+    | undefined;
+  /** Debounce state for autoDebounceCommit */
+  private debounceState:
+    | {
+        timeout: number;
+        timerId: ReturnType<typeof setTimeout> | undefined;
+        pendingEvents: Array<{
+          key: KeyPart[];
+          payload: ExportPayload;
+          source: string;
+        }>;
+      }
+    | undefined;
+
+  private constructor(
+    db: UniStoreConnection,
+    peerId: string,
+    vv: Map<string, VersionVectorEntry>,
+    maxHlc: { physicalTime: number; logicalCounter: number },
+    tables: TableNames,
+  ) {
     this.db = db;
     this.peerIdValue = peerId;
     this.vv = vv;
     this.maxHlc = maxHlc;
     this.listeners = new Set();
     this.tables = tables;
+    this.txnEventSink = undefined;
+    this.debounceState = undefined;
   }
 
   static async open(options: FlockSQLiteOptions): Promise<FlockSQLite> {
@@ -339,17 +671,36 @@ export class FlockSQLite {
     return new FlockSQLite(db, peerId, vv, maxHlc, tables);
   }
 
-  static async fromJson(options: FlockSQLiteOptions & { bundle: ExportBundle }): Promise<FlockSQLite> {
+  static async fromJson(
+    options: FlockSQLiteOptions & { bundle: ExportBundle },
+  ): Promise<FlockSQLite> {
     const flock = await FlockSQLite.open(options);
     await flock.importJson(options.bundle);
     return flock;
   }
 
   async close(): Promise<void> {
+    // Commit any pending debounced events
+    if (this.debounceState !== undefined) {
+      this.disableAutoDebounceCommit();
+    }
+
+    // Commit any transaction events (edge case: close during txn)
+    if (this.txnEventSink !== undefined) {
+      const pending = this.txnEventSink;
+      this.txnEventSink = undefined;
+      if (pending.length > 0) {
+        this.emitEvents("local", pending);
+      }
+    }
+
     await this.db.close();
   }
 
-  private static async ensureSchema(db: UniStoreConnection, tables: TableNames): Promise<void> {
+  private static async ensureSchema(
+    db: UniStoreConnection,
+    tables: TableNames,
+  ): Promise<void> {
     await db.exec(`
       CREATE TABLE IF NOT EXISTS ${tables.kv} (
         key BLOB PRIMARY KEY,
@@ -382,9 +733,15 @@ export class FlockSQLite {
     );
   }
 
-  private static async resolvePeerId(db: UniStoreConnection, tables: TableNames, provided?: string): Promise<string> {
+  private static async resolvePeerId(
+    db: UniStoreConnection,
+    tables: TableNames,
+    provided?: string,
+  ): Promise<string> {
     const normalized = normalizePeerId(provided);
-    const rows = await db.query<{ peer_id: string }>(`SELECT peer_id FROM ${tables.meta} LIMIT 1`);
+    const rows = await db.query<{ peer_id: string }>(
+      `SELECT peer_id FROM ${tables.meta} LIMIT 1`,
+    );
     if (rows.length > 0 && typeof rows[0]?.peer_id === "string") {
       const existing = rows[0].peer_id;
       if (provided && existing !== normalized) {
@@ -394,11 +751,19 @@ export class FlockSQLite {
       return normalizePeerId(existing);
     }
     await db.exec(`DELETE FROM ${tables.meta}`);
-    await db.run(`INSERT INTO ${tables.meta}(peer_id) VALUES (?)`, [normalized]);
+    await db.run(`INSERT INTO ${tables.meta}(peer_id) VALUES (?)`, [
+      normalized,
+    ]);
     return normalized;
   }
 
-  private static async loadVersionState(db: UniStoreConnection, tables: TableNames): Promise<{ vv: Map<string, VersionVectorEntry>; maxHlc: { physicalTime: number; logicalCounter: number } }> {
+  private static async loadVersionState(
+    db: UniStoreConnection,
+    tables: TableNames,
+  ): Promise<{
+    vv: Map<string, VersionVectorEntry>;
+    maxHlc: { physicalTime: number; logicalCounter: number };
+  }> {
     const vv = new Map<string, VersionVectorEntry>();
     const rows = await db.query<ClockRow>(
       `SELECT peer, MAX(physical) AS physical, MAX(logical) AS logical FROM ${tables.kv} GROUP BY peer`,
@@ -419,14 +784,20 @@ export class FlockSQLite {
     const first = maxRow[0];
     const maxHlc =
       first && Number.isFinite(first.physical) && Number.isFinite(first.logical)
-        ? { physicalTime: Number(first.physical), logicalCounter: Number(first.logical) }
+        ? {
+            physicalTime: Number(first.physical),
+            logicalCounter: Number(first.logical),
+          }
         : { physicalTime: 0, logicalCounter: 0 };
     return { vv, maxHlc };
   }
 
   private bumpVersion(clock: EntryClock): void {
     const current = this.vv.get(clock.peerId);
-    if (!current || compareClock(clock, { ...current, peerId: clock.peerId }) > 0) {
+    if (
+      !current ||
+      compareClock(clock, { ...current, peerId: clock.peerId }) > 0
+    ) {
       this.vv.set(clock.peerId, {
         physicalTime: clock.physicalTime,
         logicalCounter: clock.logicalCounter,
@@ -437,7 +808,10 @@ export class FlockSQLite {
       (this.maxHlc.physicalTime === clock.physicalTime &&
         this.maxHlc.logicalCounter < clock.logicalCounter)
     ) {
-      this.maxHlc = { physicalTime: clock.physicalTime, logicalCounter: clock.logicalCounter };
+      this.maxHlc = {
+        physicalTime: clock.physicalTime,
+        logicalCounter: clock.logicalCounter,
+      };
     }
   }
 
@@ -451,16 +825,22 @@ export class FlockSQLite {
     } else {
       logical = logical + 1;
     }
-    return { physicalTime: physical, logicalCounter: logical, peerId: this.peerIdValue };
+    return {
+      physicalTime: physical,
+      logicalCounter: logical,
+      peerId: this.peerIdValue,
+    };
   }
 
   private async applyOperation(operation: PutOperation): Promise<boolean> {
     const keyBytes = encodeKeyParts(operation.key);
-    const clock = operation.clock ?? this.allocateClock(operation.now);
     const payload = mergePayload(operation.payload, {});
-    const dataJson = payload.data === undefined ? null : JSON.stringify(payload.data);
-    const metadataJson = payload.metadata === undefined ? null : JSON.stringify(payload.metadata);
+    const dataJson =
+      payload.data === undefined ? null : JSON.stringify(payload.data);
+    const metadataJson =
+      payload.metadata === undefined ? null : JSON.stringify(payload.metadata);
     let applied = false;
+    let usedClock: EntryClock | undefined;
 
     await this.db.asyncTransaction(async (tx) => {
       const existingRows = await tx.query<KvRow>(
@@ -469,12 +849,6 @@ export class FlockSQLite {
       );
       if (existingRows.length > 0) {
         const existing = existingRows[0];
-        const existingClock: EntryClock = {
-          physicalTime: Number(existing.physical ?? 0),
-          logicalCounter: Number(existing.logical ?? 0),
-          peerId: String(existing.peer ?? ""),
-        };
-        const cmp = compareClock(clock, existingClock);
         const existingData = existing.data ?? null;
         const existingMeta = existing.metadata ?? null;
         const samePayload =
@@ -484,10 +858,38 @@ export class FlockSQLite {
         if (samePayload) {
           return;
         }
+      } else if (
+        operation.skipSameValue &&
+        dataJson === null &&
+        metadataJson === null
+      ) {
+        // Key doesn't exist and we're trying to delete - skip
+        return;
+      }
+
+      // Now allocate clock only if we're going to apply the operation
+      const clock = operation.clock ?? this.allocateClock(operation.now);
+      usedClock = clock;
+
+      if (existingRows.length > 0) {
+        const existing = existingRows[0];
+        const existingClock: EntryClock = {
+          physicalTime: Number(existing.physical ?? 0),
+          logicalCounter: Number(existing.logical ?? 0),
+          peerId: String(existing.peer ?? ""),
+        };
+        const cmp = compareClock(clock, existingClock);
         if (cmp < 0) {
           await tx.run(
             `INSERT INTO ${this.tables.overridden}(key, data, metadata, physical, logical, peer) VALUES (?, ?, ?, ?, ?, ?)`,
-            [keyBytes, dataJson, metadataJson, clock.physicalTime, clock.logicalCounter, clock.peerId],
+            [
+              keyBytes,
+              dataJson,
+              metadataJson,
+              clock.physicalTime,
+              clock.logicalCounter,
+              clock.peerId,
+            ],
           );
           return;
         }
@@ -516,12 +918,21 @@ export class FlockSQLite {
            physical=excluded.physical,
            logical=excluded.logical,
            peer=excluded.peer`,
-        [keyBytes, dataJson, metadataJson, clock.physicalTime, clock.logicalCounter, clock.peerId],
+        [
+          keyBytes,
+          dataJson,
+          metadataJson,
+          clock.physicalTime,
+          clock.logicalCounter,
+          clock.peerId,
+        ],
       );
       applied = true;
     });
 
-    this.bumpVersion(clock);
+    if (usedClock) {
+      this.bumpVersion(usedClock);
+    }
     if (applied) {
       const eventPayload = {
         key: operation.key.slice(),
@@ -529,14 +940,37 @@ export class FlockSQLite {
         source: operation.source,
       };
       if (operation.eventSink) {
+        // Explicit event sink provided (e.g., import)
         operation.eventSink.push(eventPayload);
+      } else if (this.txnEventSink) {
+        // In transaction: accumulate events
+        this.txnEventSink.push(eventPayload);
+      } else if (this.debounceState) {
+        // Debounce active: accumulate and reset timer
+        this.debounceState.pendingEvents.push(eventPayload);
+        this.resetDebounceTimer();
       } else {
+        // Normal: emit immediately
         this.emitEvents(operation.source, [eventPayload]);
       }
     }
     return applied;
   }
 
+  private resetDebounceTimer(): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+
+    if (this.debounceState.timerId !== undefined) {
+      clearTimeout(this.debounceState.timerId);
+    }
+
+    this.debounceState.timerId = setTimeout(() => {
+      this.commit();
+    }, this.debounceState.timeout);
+  }
+
   private emitEvents(
     source: string,
     events: Array<{ key: KeyPart[]; payload: ExportPayload }>,
@@ -546,12 +980,17 @@ export class FlockSQLite {
     }
     const batch: EventBatch = {
       source,
-      events: events.map((event): Event => ({
-        key: cloneJson(event.key),
-        value: event.payload.data !== undefined ? cloneJson(event.payload.data) : undefined,
-        metadata: cloneMetadata(event.payload.metadata),
-        payload: clonePayload(event.payload),
-      })),
+      events: events.map(
+        (event): Event => ({
+          key: cloneJson(event.key),
+          value:
+            event.payload.data !== undefined
+              ? cloneJson(event.payload.data)
+              : undefined,
+          metadata: cloneMetadata(event.payload.metadata),
+          payload: clonePayload(event.payload),
+        }),
+      ),
     };
     this.listeners.forEach((listener) => {
       listener(batch);
@@ -568,7 +1007,11 @@ export class FlockSQLite {
     });
   }
 
-  async putWithMeta(key: KeyPart[], value: Value, options: PutWithMetaOptions = {}): Promise<void> {
+  async putWithMeta(
+    key: KeyPart[],
+    value: Value,
+    options: PutWithMetaOptions = {},
+  ): Promise<void> {
     const basePayload: ExportPayload = { data: cloneJson(value) };
     if (options.metadata) {
       basePayload.metadata = cloneMetadata(options.metadata);
@@ -576,7 +1019,10 @@ export class FlockSQLite {
     const hooks = options.hooks?.transform;
     if (hooks) {
       const working = clonePayload(basePayload);
-      const transformed = await hooks({ key: key.slice(), now: options.now }, working);
+      const transformed = await hooks(
+        { key: key.slice(), now: options.now },
+        working,
+      );
       const finalPayload = mergePayload(basePayload, transformed ?? working);
       if (finalPayload.data === undefined) {
         throw new TypeError("putWithMeta requires a data value");
@@ -609,6 +1055,76 @@ export class FlockSQLite {
     });
   }
 
+  /**
+   * Force put a value even if it's the same as the current value.
+   * This will refresh the timestamp.
+   */
+  async forcePut(key: KeyPart[], value: Value, now?: number): Promise<void> {
+    await this.applyOperation({
+      key,
+      payload: { data: cloneJson(value) },
+      now,
+      skipSameValue: false,
+      source: "local",
+    });
+  }
+
+  /**
+   * Force put a value with metadata even if it's the same as the current value.
+   * This will refresh the timestamp.
+   */
+  async forcePutWithMeta(
+    key: KeyPart[],
+    value: Value,
+    options: PutWithMetaOptions = {},
+  ): Promise<void> {
+    const basePayload: ExportPayload = { data: cloneJson(value) };
+    if (options.metadata) {
+      basePayload.metadata = cloneMetadata(options.metadata);
+    }
+    const hooks = options.hooks?.transform;
+    if (hooks) {
+      const working = clonePayload(basePayload);
+      const transformed = await hooks(
+        { key: key.slice(), now: options.now },
+        working,
+      );
+      const finalPayload = mergePayload(basePayload, transformed ?? working);
+      if (finalPayload.data === undefined) {
+        throw new TypeError("forcePutWithMeta requires a data value");
+      }
+      await this.applyOperation({
+        key,
+        payload: finalPayload,
+        now: options.now,
+        skipSameValue: false,
+        source: "local",
+      });
+      return;
+    }
+    await this.applyOperation({
+      key,
+      payload: basePayload,
+      now: options.now,
+      skipSameValue: false,
+      source: "local",
+    });
+  }
+
+  /**
+   * Force delete a key even if it's already deleted.
+   * This will refresh the timestamp.
+   */
+  async forceDelete(key: KeyPart[], now?: number): Promise<void> {
+    await this.applyOperation({
+      key,
+      payload: {},
+      now,
+      skipSameValue: false,
+      source: "local",
+    });
+  }
+
   async set(key: KeyPart[], value: Value, now?: number): Promise<void> {
     await this.put(key, value, now);
   }
@@ -616,7 +1132,9 @@ export class FlockSQLite {
   async setPeerId(peerId: string): Promise<void> {
     const normalized = normalizePeerId(peerId);
     await this.db.exec(`DELETE FROM ${this.tables.meta}`);
-    await this.db.run(`INSERT INTO ${this.tables.meta}(peer_id) VALUES (?)`, [normalized]);
+    await this.db.run(`INSERT INTO ${this.tables.meta}(peer_id) VALUES (?)`, [
+      normalized,
+    ]);
     this.peerIdValue = normalized;
   }
 
@@ -631,6 +1149,38 @@ export class FlockSQLite {
     return parseData(row.data);
   }
 
+  /**
+   * Returns the full entry payload (data, metadata, and clock) for a key.
+   *
+   * Compared to `get`, this preserves tombstone information: a deleted entry
+   * still returns its clock and an empty metadata object with `data` omitted.
+   * Missing or invalid keys return `undefined`. Metadata is cloned and
+   * normalized to `{}` when absent.
+   */
+  async getEntry(key: KeyPart[]): Promise<EntryInfo | undefined> {
+    let keyBytes: Uint8Array;
+    try {
+      keyBytes = encodeKeyParts(key);
+    } catch {
+      return undefined;
+    }
+    const rows = await this.db.query<KvRow>(
+      `SELECT data, metadata, physical, logical, peer FROM ${this.tables.kv} WHERE key = ? LIMIT 1`,
+      [keyBytes],
+    );
+    const row = rows[0];
+    if (!row) return undefined;
+    const clock = normalizeRowClock(row.physical, row.logical, row.peer);
+    if (!clock) return undefined;
+    const metadata = normalizeMetadataMap(parseMetadata(row.metadata));
+    const data = parseData(row.data);
+    const info: EntryInfo = { metadata, clock };
+    if (data !== undefined) {
+      info.data = data;
+    }
+    return info;
+  }
+
   async getMvr(key: KeyPart[]): Promise<Value[]> {
     const rows = await this.scan({ prefix: key });
     const values: Value[] = [];
@@ -657,14 +1207,20 @@ export class FlockSQLite {
     await this.put(composite, true, now);
   }
 
-  private buildScanBounds(
-    options: ScanOptions,
-  ): { where: string[]; params: unknown[]; empty?: boolean; postFilter?: (bytes: Uint8Array) => boolean } {
+  private buildScanBounds(options: ScanOptions): {
+    where: string[];
+    params: unknown[];
+    empty?: boolean;
+    postFilter?: (bytes: Uint8Array) => boolean;
+  } {
     let lower: { value: Uint8Array; inclusive: boolean } | undefined;
     let upper: { value: Uint8Array; inclusive: boolean } | undefined;
     let prefixFilter: Uint8Array | undefined;
 
-    const applyLower = (candidate: { value: Uint8Array; inclusive: boolean }) => {
+    const applyLower = (candidate: {
+      value: Uint8Array;
+      inclusive: boolean;
+    }) => {
       if (!lower) {
         lower = candidate;
         return;
@@ -673,11 +1229,17 @@ export class FlockSQLite {
       if (cmp > 0) {
         lower = candidate;
       } else if (cmp === 0) {
-        lower = { value: lower.value, inclusive: lower.inclusive && candidate.inclusive };
+        lower = {
+          value: lower.value,
+          inclusive: lower.inclusive && candidate.inclusive,
+        };
       }
     };
 
-    const applyUpper = (candidate: { value: Uint8Array; inclusive: boolean }) => {
+    const applyUpper = (candidate: {
+      value: Uint8Array;
+      inclusive: boolean;
+    }) => {
       if (!upper) {
         upper = candidate;
         return;
@@ -686,7 +1248,10 @@ export class FlockSQLite {
       if (cmp < 0) {
         upper = candidate;
       } else if (cmp === 0) {
-        upper = { value: upper.value, inclusive: upper.inclusive && candidate.inclusive };
+        upper = {
+          value: upper.value,
+          inclusive: upper.inclusive && candidate.inclusive,
+        };
       }
     };
 
@@ -727,7 +1292,10 @@ export class FlockSQLite {
       params.push(upper.value);
     }
     const postFilter = prefixFilter
-      ? ((pf: Uint8Array) => (bytes: Uint8Array) => keyMatchesPrefix(bytes, pf))(prefixFilter)
+      ? (
+          (pf: Uint8Array) => (bytes: Uint8Array) =>
+            keyMatchesPrefix(bytes, pf)
+        )(prefixFilter)
       : undefined;
     return { where, params, postFilter };
   }
@@ -737,7 +1305,8 @@ export class FlockSQLite {
     if (bounds.empty) {
       return [];
     }
-    const clauses = bounds.where.length > 0 ? `WHERE ${bounds.where.join(" AND ")}` : "";
+    const clauses =
+      bounds.where.length > 0 ? `WHERE ${bounds.where.join(" AND ")}` : "";
     const rows = await this.db.query<KvRow>(
       `SELECT key, data, metadata, physical, logical, peer FROM ${this.tables.kv} ${clauses} ORDER BY key ASC`,
       bounds.params as [],
@@ -765,7 +1334,42 @@ export class FlockSQLite {
     return result;
   }
 
-  version(): VersionVector {
+  /**
+   * Returns the exclusive version vector, which only includes peers that have
+   * at least one entry in the current state. This is consistent with the state
+   * after export and re-import.
+   *
+   * Use this version when sending to other peers for incremental sync.
+   */
+  async version(): Promise<VersionVector> {
+    // Find the maximum clock per peer. The clock ordering is (physical, logical).
+    // We need the row with the highest (physical, logical) pair for each peer,
+    // not MAX(physical) and MAX(logical) independently which could mix values from different rows.
+    // Use a window function with lexicographic ordering to avoid floating-point precision issues.
+    const rows = await this.db.query<{ peer: string; physical: number; logical: number }>(
+      `SELECT peer, physical, logical FROM (
+         SELECT peer, physical, logical,
+                ROW_NUMBER() OVER (PARTITION BY peer ORDER BY physical DESC, logical DESC) as rn
+         FROM ${this.tables.kv}
+       ) WHERE rn = 1`,
+    );
+    const vv: VersionVector = {};
+    for (const row of rows) {
+      vv[row.peer] = {
+        physicalTime: row.physical,
+        logicalCounter: row.logical,
+      };
+    }
+    return vv;
+  }
+
+  /**
+   * Returns the inclusive version vector, which includes all peers ever seen,
+   * even if their entries have been overridden by other peers.
+   *
+   * Use this version when checking if you have received all data from another peer.
+   */
+  inclusiveVersion(): VersionVector {
     const vv: VersionVector = {};
     for (const [peer, clock] of this.vv.entries()) {
       vv[peer] = { ...clock };
@@ -781,7 +1385,11 @@ export class FlockSQLite {
     return this.maxHlc.physicalTime;
   }
 
-  private async exportInternal(from?: VersionVector, pruneTombstonesBefore?: number, peerId?: string): Promise<ExportBundle> {
+  private async exportInternal(
+    from?: VersionVector,
+    pruneTombstonesBefore?: number,
+    peerId?: string,
+  ): Promise<ExportBundle> {
     const normalizedFrom = new Map<string, VersionVectorEntry>();
     if (from) {
       for (const [peer, entry] of Object.entries(from)) {
@@ -795,7 +1403,10 @@ export class FlockSQLite {
     const entries: Record<string, ExportRecord> = {};
 
     const peers = peerId ? [peerId] : Array.from(this.vv.keys());
-    const peersToExport: Array<{ peer: string; fromEntry?: VersionVectorEntry }> = [];
+    const peersToExport: Array<{
+      peer: string;
+      fromEntry?: VersionVectorEntry;
+    }> = [];
     for (const peer of peers) {
       const localEntry = this.vv.get(peer);
       const fromEntry = normalizedFrom.get(peer);
@@ -813,7 +1424,10 @@ export class FlockSQLite {
     }
 
     if (peerId && peersToExport.every((p) => p.peer !== peerId)) {
-      peersToExport.push({ peer: peerId, fromEntry: normalizedFrom.get(peerId) });
+      peersToExport.push({
+        peer: peerId,
+        fromEntry: normalizedFrom.get(peerId),
+      });
     }
 
     if (peersToExport.length === 0) {
@@ -867,7 +1481,11 @@ export class FlockSQLite {
   }
 
   private async exportWithHooks(options: ExportOptions): Promise<ExportBundle> {
-    const base = await this.exportInternal(options.from, options.pruneTombstonesBefore, options.peerId);
+    const base = await this.exportInternal(
+      options.from,
+      options.pruneTombstonesBefore,
+      options.peerId,
+    );
     const transform = options.hooks?.transform;
     if (!transform) {
       return base;
@@ -894,9 +1512,15 @@ export class FlockSQLite {
 
   exportJson(): Promise<ExportBundle>;
   exportJson(from: VersionVector): Promise<ExportBundle>;
-  exportJson(from: VersionVector, pruneTombstonesBefore: number): Promise<ExportBundle>;
+  exportJson(
+    from: VersionVector,
+    pruneTombstonesBefore: number,
+  ): Promise<ExportBundle>;
   exportJson(options: ExportOptions): Promise<ExportBundle>;
-  exportJson(arg?: VersionVector | ExportOptions, pruneTombstonesBefore?: number): Promise<ExportBundle> {
+  exportJson(
+    arg?: VersionVector | ExportOptions,
+    pruneTombstonesBefore?: number,
+  ): Promise<ExportBundle> {
     if (isExportOptions(arg)) {
       return this.exportWithHooks(arg);
     }
@@ -904,12 +1528,33 @@ export class FlockSQLite {
   }
 
   private async importInternal(bundle: ExportBundle): Promise<ImportReport> {
+    // Force commit if in transaction - this is an error condition
+    if (this.txnEventSink !== undefined) {
+      const pending = this.txnEventSink;
+      this.txnEventSink = undefined;
+      if (pending.length > 0) {
+        this.emitEvents("local", pending);
+      }
+      throw new Error(
+        "import called during transaction - transaction was auto-committed",
+      );
+    }
+
+    // Force commit if in debounce mode
+    if (this.debounceState !== undefined) {
+      this.commit();
+    }
+
     if (bundle.version !== 0) {
       throw new TypeError("Unsupported bundle version");
     }
     let accepted = 0;
     const skipped: Array<{ key: KeyPart[]; reason: string }> = [];
-    const appliedEvents: Array<{ key: KeyPart[]; payload: ExportPayload; source: string }> = [];
+    const appliedEvents: Array<{
+      key: KeyPart[];
+      payload: ExportPayload;
+      source: string;
+    }> = [];
     for (const [keyString, record] of Object.entries(bundle.entries)) {
       let keyParts: KeyPart[];
       try {
@@ -945,14 +1590,18 @@ export class FlockSQLite {
   async importJson(arg: ExportBundle | ImportOptions): Promise<ImportReport> {
     if (isImportOptions(arg)) {
       const preprocess = arg.hooks?.preprocess;
-      const working = preprocess ? { version: arg.bundle.version, entries: { ...arg.bundle.entries } } : arg.bundle;
+      const working = preprocess
+        ? { version: arg.bundle.version, entries: { ...arg.bundle.entries } }
+        : arg.bundle;
       const skipped: Array<{ key: KeyPart[]; reason: string }> = [];
       if (preprocess) {
         for (const [key, record] of Object.entries(working.entries)) {
           const contextKey = JSON.parse(key) as KeyPart[];
           const clock = parseClockString(record.c);
           const payload: ExportPayload = {};
-          if (record.d !== undefined) payload.data = cloneJson(record.d);
+          if (record.d !== undefined) {
+            payload.data = cloneJson(record.d);
+          }
           const metadata = cloneMetadata(record.m);
           if (metadata !== undefined) payload.metadata = metadata;
           const decision = await preprocess(
@@ -961,7 +1610,10 @@ export class FlockSQLite {
           );
           const normalized = normalizeImportDecision(decision);
           if (!normalized.accept) {
-            skipped.push({ key: contextKey, reason: normalized.reason ?? "rejected" });
+            skipped.push({
+              key: contextKey,
+              reason: normalized.reason ?? "rejected",
+            });
             delete working.entries[key];
           } else {
             working.entries[key] = buildRecord(clock, payload);
@@ -969,7 +1621,10 @@ export class FlockSQLite {
         }
       }
       const baseReport = await this.importInternal(working);
-      return { accepted: baseReport.accepted, skipped: skipped.concat(baseReport.skipped) };
+      return {
+        accepted: baseReport.accepted,
+        skipped: skipped.concat(baseReport.skipped),
+      };
     }
     return this.importInternal(arg);
   }
@@ -996,7 +1651,10 @@ export class FlockSQLite {
     await this.importJson(bundle);
   }
 
-  static async checkConsistency(a: FlockSQLite, b: FlockSQLite): Promise<boolean> {
+  static async checkConsistency(
+    a: FlockSQLite,
+    b: FlockSQLite,
+  ): Promise<boolean> {
     const [digestA, digestB] = await Promise.all([a.digest(), b.digest()]);
     return digestA === digestB;
   }
@@ -1011,6 +1669,154 @@ export class FlockSQLite {
       this.listeners.delete(listener);
     };
   }
+
+  /**
+   * Execute operations within a transaction. All put/delete operations inside
+   * the callback will be batched and emitted as a single EventBatch when the
+   * transaction commits successfully.
+   *
+   * If the callback throws or rejects, the transaction is rolled back and no
+   * events are emitted. Note: Database operations are NOT rolled back - only
+   * event emission is affected.
+   *
+   * @param callback - Async function containing put/delete operations
+   * @returns The return value of the callback
+   * @throws Error if nested transaction attempted
+   * @throws Error if called while autoDebounceCommit is active
+   *
+   * @example
+   * ```ts
+   * await flock.txn(async () => {
+   *   await flock.put(["a"], 1);
+   *   await flock.put(["b"], 2);
+   *   await flock.put(["c"], 3);
+   * });
+   * // Subscribers receive a single EventBatch with 3 events
+   * ```
+   */
+  async txn<T>(callback: () => Promise<T>): Promise<T> {
+    if (this.txnEventSink !== undefined) {
+      throw new Error("Nested transactions are not supported");
+    }
+    if (this.debounceState !== undefined) {
+      throw new Error(
+        "Cannot start transaction while autoDebounceCommit is active",
+      );
+    }
+
+    const eventSink: Array<{
+      key: KeyPart[];
+      payload: ExportPayload;
+      source: string;
+    }> = [];
+    this.txnEventSink = eventSink;
+
+    try {
+      const result = await callback();
+      // Commit: emit all accumulated events as single batch
+      if (eventSink.length > 0) {
+        this.emitEvents("local", eventSink);
+      }
+      return result;
+    } finally {
+      this.txnEventSink = undefined;
+    }
+  }
+
+  /**
+   * Check if a transaction is currently active.
+   */
+  isInTxn(): boolean {
+    return this.txnEventSink !== undefined;
+  }
+
+  /**
+   * Enable auto-debounce mode. Events will be accumulated and emitted after
+   * the specified timeout of inactivity. Each new operation resets the timer.
+   *
+   * Use `commit()` to force immediate emission of pending events.
+   * Use `disableAutoDebounceCommit()` to disable and emit pending events.
+   *
+   * Import operations will automatically call `commit()` before proceeding.
+   *
+   * @param timeout - Debounce timeout in milliseconds
+   * @throws Error if called while a transaction is active
+   * @throws Error if autoDebounceCommit is already active
+   *
+   * @example
+   * ```ts
+   * flock.autoDebounceCommit(100);
+   * await flock.put(["a"], 1);
+   * await flock.put(["b"], 2);
+   * // No events emitted yet...
+   * // After 100ms of inactivity, subscribers receive single EventBatch
+   * ```
+   */
+  autoDebounceCommit(timeout: number): void {
+    if (this.txnEventSink !== undefined) {
+      throw new Error(
+        "Cannot enable autoDebounceCommit while transaction is active",
+      );
+    }
+    if (this.debounceState !== undefined) {
+      throw new Error("autoDebounceCommit is already active");
+    }
+
+    this.debounceState = {
+      timeout,
+      timerId: undefined,
+      pendingEvents: [],
+    };
+  }
+
+  /**
+   * Disable auto-debounce mode and emit any pending events immediately.
+   * No-op if autoDebounceCommit is not active.
+   */
+  disableAutoDebounceCommit(): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+
+    const { timerId, pendingEvents } = this.debounceState;
+    if (timerId !== undefined) {
+      clearTimeout(timerId);
+    }
+    this.debounceState = undefined;
+
+    if (pendingEvents.length > 0) {
+      this.emitEvents("local", pendingEvents);
+    }
+  }
+
+  /**
+   * Force immediate emission of any pending debounced events.
+   * Does not disable auto-debounce mode - new operations will continue to be debounced.
+   * No-op if autoDebounceCommit is not active or no events are pending.
+   */
+  commit(): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+
+    const { timerId, pendingEvents } = this.debounceState;
+    if (timerId !== undefined) {
+      clearTimeout(timerId);
+      this.debounceState.timerId = undefined;
+    }
+
+    if (pendingEvents.length > 0) {
+      this.emitEvents("local", pendingEvents);
+      this.debounceState.pendingEvents = [];
+    }
+  }
+
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean {
+    return this.debounceState !== undefined;
+  }
 }
 
 export type {
@@ -1032,8 +1838,8 @@ export type {
   ScanOptions,
   ScanRow,
   Value,
-  VersionVector,
   VersionVectorEntry,
+  EntryInfo,
 };
 
 export { FlockSQLite as Flock };