@loro-dev/flock 3.1.0 → 4.1.0

package/dist/index.d.mts

@@ -14,7 +14,11 @@ type VersionVectorEntry = {
   physicalTime: number;
   logicalCounter: number;
 };
-type VersionVector = Record<string, VersionVectorEntry>;
+interface VersionVector {
+  [peer: string]: VersionVectorEntry | undefined;
+}
+declare function encodeVersionVector(vector: VersionVector): Uint8Array;
+declare function decodeVersionVector(bytes: Uint8Array): VersionVector;
 type Value = string | number | boolean | null | Array<Value> | {
   [key: string]: Value;
 };
@@ -34,6 +38,11 @@ type EntryClock = {
   logicalCounter: number;
   peerId: string;
 };
+type EntryInfo = {
+  data?: Value;
+  metadata: MetadataMap;
+  clock: EntryClock;
+};
 type ExportPayload = {
   data?: Value;
   metadata?: MetadataMap;
@@ -135,8 +144,30 @@ declare class Flock {
    */
   delete(key: KeyPart[], now?: number): void;
   get(key: KeyPart[]): Value | undefined;
+  /**
+   * Returns the full entry payload (data, metadata, and clock) for a key.
+   *
+   * Unlike `get`, this distinguishes between a missing key (`undefined`) and a
+   * tombstone (returns the clock and metadata with `data` omitted). Metadata is
+   * cloned and defaults to `{}` when absent.
+   */
+  getEntry(key: KeyPart[]): EntryInfo | undefined;
   merge(other: Flock): void;
+  /**
+   * 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.
+   */
   version(): VersionVector;
+  /**
+   * 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;
   private exportJsonInternal;
   private exportJsonWithHooks;
   exportJson(): ExportBundle;
@@ -147,6 +178,7 @@ declare class Flock {
   private importJsonWithHooks;
   importJson(bundle: ExportBundle): ImportReport;
   importJson(options: ImportOptions): Promise<ImportReport>;
+  importJsonStr(bundle: string): ImportReport;
   getMaxPhysicalTime(): number;
   peerId(): string;
   digest(): string;
@@ -157,5 +189,5 @@ declare class Flock {
   subscribe(listener: (batch: EventBatch) => void): () => void;
 }
 //#endregion
-export { EntryClock, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry };
+export { EntryClock, EntryInfo, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry, decodeVersionVector, encodeVersionVector };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.ts

@@ -14,7 +14,11 @@ type VersionVectorEntry = {
   physicalTime: number;
   logicalCounter: number;
 };
-type VersionVector = Record<string, VersionVectorEntry>;
+interface VersionVector {
+  [peer: string]: VersionVectorEntry | undefined;
+}
+declare function encodeVersionVector(vector: VersionVector): Uint8Array;
+declare function decodeVersionVector(bytes: Uint8Array): VersionVector;
 type Value = string | number | boolean | null | Array<Value> | {
   [key: string]: Value;
 };
@@ -34,6 +38,11 @@ type EntryClock = {
   logicalCounter: number;
   peerId: string;
 };
+type EntryInfo = {
+  data?: Value;
+  metadata: MetadataMap;
+  clock: EntryClock;
+};
 type ExportPayload = {
   data?: Value;
   metadata?: MetadataMap;
@@ -135,8 +144,30 @@ declare class Flock {
    */
   delete(key: KeyPart[], now?: number): void;
   get(key: KeyPart[]): Value | undefined;
+  /**
+   * Returns the full entry payload (data, metadata, and clock) for a key.
+   *
+   * Unlike `get`, this distinguishes between a missing key (`undefined`) and a
+   * tombstone (returns the clock and metadata with `data` omitted). Metadata is
+   * cloned and defaults to `{}` when absent.
+   */
+  getEntry(key: KeyPart[]): EntryInfo | undefined;
   merge(other: Flock): void;
+  /**
+   * 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.
+   */
   version(): VersionVector;
+  /**
+   * 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;
   private exportJsonInternal;
   private exportJsonWithHooks;
   exportJson(): ExportBundle;
@@ -147,6 +178,7 @@ declare class Flock {
   private importJsonWithHooks;
   importJson(bundle: ExportBundle): ImportReport;
   importJson(options: ImportOptions): Promise<ImportReport>;
+  importJsonStr(bundle: string): ImportReport;
   getMaxPhysicalTime(): number;
   peerId(): string;
   digest(): string;
@@ -157,5 +189,5 @@ declare class Flock {
   subscribe(listener: (batch: EventBatch) => void): () => void;
 }
 //#endregion
-export { EntryClock, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry };
+export { EntryClock, EntryInfo, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry, decodeVersionVector, encodeVersionVector };
 //# sourceMappingURL=index.d.ts.map