@vrtmrz/livesync-commonlib 0.2.0 → 0.2.1

package/README.md

@@ -108,6 +108,49 @@ The `/replication` entry includes the `joined-devices` finite resource contract.
 
 `forget(id)` removes one other device from all participation maps and the accepted list, while retaining the lock state, preferred tweaks, and unknown fields. The CouchDB implementation rereads the existing milestone before editing and verifies removal after saving. CouchDB local documents do not reject stale revisions, so concurrent changes to other device records can be overwritten. A failed verification is reported to the caller for manual refresh and retry. Object Storage checks ETags with conditional writes and retries conflicts a bounded number of times. Missing records, unsupported conditional writes, and exhausted conflicts have distinct results. Forgetting is not credential revocation: an unlocked remote permits a returning device to register again.
 
+## Replication statistics
+
+Hosts can read the latest `services.replicator.replicationStatics.value` and
+subscribe to that reactive source. The focused `/replication` entry exports
+`ReplicationStatics`, `CouchDBReplicationProgress`, and
+`ReplicationCheckpointProgress`. Existing transfer counters and `syncStatus`
+retain their meanings.
+
+The optional `couchDB` snapshot describes the ordinary CouchDB replication
+attempt. Other providers omit it. Its `phase` distinguishes `one-shot`,
+`catch-up` (the pull preceding each continuous start or reconnect),
+`continuous`, and `idle`. Preparation can expose a phase before directional
+progress is available. This is independent of activity, pause, or failure in
+`syncStatus`; entering `continuous` does not establish that Vault reflection
+has finished or that editing is safe.
+
+Optional `pull` and `push` observations each contain:
+
+- `checkedChanges`: changes-feed entries presented for revision comparison,
+  including both existing and missing revisions. One entry with several
+  revisions counts once; repeated entries during retries can count again.
+  This is neither a Vault file count nor an exact count of skipped transfers.
+- `completedBatches`: batches which reached PouchDB's checkpoint notification,
+  including batches which transferred no documents.
+- `lastSeq`: the last processed checkpoint position, preserved as a number or
+  an opaque string. It is not a remaining-work estimate, percentage, or proof
+  that a checkpoint was durably written.
+- `checking`: observed revision comparison in the current batch, cleared by
+  a transfer notification, pause, or termination. It does not establish that
+  network transfer has not begun.
+
+Counts and positions reset for each underlying PouchDB handler, including the
+transition from catch-up to continuous replication and a replacement attempt.
+Completion, failure, and cancellation retain final values with `phase: 'idle'`
+and `checking: false`. Replacing the provider clears its previous snapshot.
+
+Checkpoint events are accumulated internally and published periodically
+(currently about 200 ms). Transfer, pause, and terminal boundaries flush
+pending observations promptly. The interval is an implementation detail.
+The observer releases its timer and listeners on termination; late callbacks
+cannot publish into the next attempt. These observations do not modify the
+replication options, received documents, or native checkpoints.
+
 ## Rooted storage
 
 Both platform storage factories receive an existing root from the host. They never select a directory, request browser permission, infer a process directory, or persist a handle.

package/dist/API/processSetting.d.ts

@@ -59,6 +59,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     idDerivationKey: string;
     pathNormalizationVersion: import("../settings.js").PathNormalizationVersion;
     liveSync: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
     syncOnFileOpen: boolean;

package/dist/common/models/setting.const.defaults.js

@@ -40,6 +40,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   couchDB_PASSWORD: "",
   couchDB_DBNAME: "",
   liveSync: false,
+  batchSaveInLiveSync: false,
   syncOnSave: false,
   syncOnStart: false,
   savingDelay: 200,

package/dist/common/models/setting.const.qr.js

@@ -181,6 +181,7 @@ const KeyIndexOfSettings = {
   idDerivationVersion: 166,
   idDerivationKey: 167,
   pathNormalizationVersion: 168,
+  batchSaveInLiveSync: 169,
   encryptedIdDerivationKey: -1
 };
 export {

package/dist/common/models/setting.policy.d.ts

@@ -53,6 +53,10 @@ export declare const SETTINGS_PROPERTY_POLICY: {
         readonly markdown: "include";
         readonly persistence: "include";
     };
+    readonly batchSaveInLiveSync: {
+        readonly markdown: "include";
+        readonly persistence: "include";
+    };
     readonly syncOnSave: {
         readonly markdown: "include";
         readonly persistence: "include";

package/dist/common/models/setting.policy.js

@@ -14,6 +14,7 @@ const SettingPolicies = {
 };
 const SETTINGS_PROPERTY_POLICY = {
   liveSync: SettingPolicies.Default,
+  batchSaveInLiveSync: SettingPolicies.Default,
   syncOnSave: SettingPolicies.Default,
   syncOnStart: SettingPolicies.Default,
   syncOnFileOpen: SettingPolicies.Default,

package/dist/common/models/setting.type.d.ts

@@ -80,6 +80,8 @@ interface SyncMethodSettings {
      * Synchronise in Live. This is an exclusive setting against other sync methods.
      */
     liveSync: boolean;
+    /** Explicitly enable batched local database updates in LiveSync mode; an absent value is false. */
+    batchSaveInLiveSync?: boolean;
     /**
      * automatically run sync on save.
      * File modification will trigger the sync, even if the file is not changed on the editor.

package/dist/common/models/shared.definition.d.ts

@@ -10,6 +10,24 @@ export declare const DatabaseConnectingStatuses: {
     readonly JOURNAL_RECEIVE: "JOURNAL_RECEIVE";
 };
 export type DatabaseConnectingStatus = (typeof DatabaseConnectingStatuses)[keyof typeof DatabaseConnectingStatuses];
+/** The transfer stage; entering continuous replication does not imply Vault reflection is complete. */
+export type CouchDBReplicationPhase = "idle" | "one-shot" | "catch-up" | "continuous";
+export type ReplicationCheckpointProgress = {
+    /** Changes-feed entries presented for revision comparison, including repeated entries on retries. */
+    readonly checkedChanges: number;
+    /** Batches which reached PouchDB's checkpoint notification, including batches without transfers. */
+    readonly completedBatches: number;
+    /** Opaque processed position, not a remaining-document count or proof of durable checkpoint storage. */
+    readonly lastSeq?: string | number;
+    /** Revision comparison is progressing; this does not establish that network transfer has not begun. */
+    readonly checking: boolean;
+};
+/** Counters reset for each underlying PouchDB attempt, including the transition from catch-up to continuous. */
+export type CouchDBReplicationProgress = {
+    readonly phase: CouchDBReplicationPhase;
+    readonly pull?: ReplicationCheckpointProgress;
+    readonly push?: ReplicationCheckpointProgress;
+};
 export type ReplicationStatics = {
     sent: number;
     arrived: number;
@@ -18,5 +36,7 @@ export type ReplicationStatics = {
     lastSyncPullSeq: number;
     lastSyncPushSeq: number;
     syncStatus: DatabaseConnectingStatus;
+    /** Present only when the provider supplies CouchDB checkpoint observations. */
+    couchDB?: CouchDBReplicationProgress;
 };
 export declare const DEFAULT_REPLICATION_STATICS: ReplicationStatics;

package/dist/common/models/tweak.definition.d.ts

@@ -142,6 +142,7 @@ export declare const TweakValuesTemplate: {
     enableCompression: boolean;
     handleFilenameCaseSensitive: boolean;
     liveSync?: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave?: boolean;
     syncOnStart?: boolean;
     syncOnFileOpen?: boolean;

package/dist/common/settingConstants.d.ts

@@ -30,6 +30,7 @@ export declare const AllSettingDefault: {
     dummy: number;
     deviceAndVaultName: string;
     liveSync: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
     syncOnFileOpen: boolean;

package/dist/common/settingConstants.js

@@ -144,6 +144,10 @@ const SettingInformation = {
     name: "Batch database update",
     desc: "Reducing the frequency with which on-disk changes are reflected into the DB"
   },
+  batchSaveInLiveSync: {
+    name: "Batch database updates in LiveSync mode",
+    desc: "Wait for a bounded local quiet period before processing file updates in LiveSync mode, reducing intermediate database updates while delaying their reflection to remote devices."
+  },
   readChunksOnline: {
     name: "Fetch chunks on demand",
     desc: "(ex. Read chunks online) If this option is enabled, LiveSync reads chunks online directly instead of replicating them locally. Increasing Custom chunk size is recommended."
@@ -313,11 +317,11 @@ const SettingInformation = {
   },
   batchSaveMinimumDelay: {
     name: "Minimum delay for batch database updating",
-    desc: "Seconds. Saving to the local database will be delayed until this value after we stop typing or saving."
+    desc: "Seconds. The quiet period after the latest pending update before local database processing becomes due."
   },
   batchSaveMaximumDelay: {
     name: "Maximum delay for batch database updating",
-    desc: "Saving will be performed forcefully after this number of seconds."
+    desc: "Seconds. The maximum intentional wait from the first pending update before local database processing becomes due. This does not guarantee when database processing, network delivery, or reflection to another device will complete."
   },
   notifyThresholdOfRemoteStorageSize: {
     name: "Notify when the estimated remote storage size exceeds on start up",

package/dist/interfaces/FileHandler.d.ts

@@ -1,5 +1,9 @@
 import type { FilePath, FilePathWithPrefix, MetaEntry } from "../common/models/db.type.js";
 import type { UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../common/models/fileaccess.type.js";
+export interface StoreFileOptions {
+    /** Recheck storage and provenance, with bounded retries for recovery scans. */
+    revalidateStorage?: boolean;
+}
 export interface IFileHandler {
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
     /**
@@ -8,7 +12,7 @@ export interface IFileHandler {
      * operation never stores a document revision or writes to storage.
      */
     tryRecordUntrackedFileRevision(info: UXFileInfoStub | UXFileInfo, expectedRevision: string): Promise<boolean>;
-    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean, options?: StoreFileOptions): Promise<boolean>;
     /**
      * Store the current storage content as a child of an exact live database revision.
      *

package/dist/interfaces/StorageEventManager.d.ts

@@ -13,4 +13,9 @@ export declare abstract class StorageEventManager {
     abstract isWaiting(filename: FilePath): boolean;
     abstract waitForIdle(): Promise<void>;
     abstract restoreState(): Promise<void>;
+    /**
+     * Complete accepted work before its storage closes. Custom hosts must stop
+     * their watcher admission before invoking this default implementation.
+     */
+    stopWatching?(): Promise<void>;
 }

package/dist/interfaces/StorageEventManager.js

@@ -1,4 +1,11 @@
 class StorageEventManager {
+  /**
+   * Complete accepted work before its storage closes. Custom hosts must stop
+   * their watcher admission before invoking this default implementation.
+   */
+  stopWatching() {
+    return this.waitForIdle();
+  }
 }
 export {
   StorageEventManager

package/dist/managers/StorageEventManager.d.ts

@@ -71,26 +71,35 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
      * Restore and complete the previous storage-event snapshot when it exists.
      */
     restoreState(): Promise<void>;
+    private acceptingEvents;
+    private admissions;
     appendQueue(params: FileEvent[], ctx?: unknown): Promise<void>;
+    private appendQueueInternal;
     protected bufferedQueuedItems: (FileEventItem | FileEventItemSentinel)[];
+    private pendingSnapshot;
+    private operations;
+    private latestByPath;
+    private nextSequence;
+    private snapshotTail;
+    private dispatching;
+    private retainEvent;
+    private reportOperationFailure;
+    private failOperation;
     enqueue(newItem: FileEventItem): void;
-    /**
-     * Immediately take snapshot.
-     */
     private _triggerTakeSnapshot;
-    /**
-     * Trigger taking snapshot after throttled period.
-     */
     triggerTakeSnapshot: import("octagonal-wheels/function").ThrottledFunction<() => void>;
     protected concurrentProcessing: import("octagonal-wheels/concurrency/semaphore_v2").SemaphoreObject;
     protected _waitingMap: Map<string, WaitInfo>;
-    private _waitForIdle;
+    private pendingOperations;
+    private releaseOperations;
+    private waitForOperations;
     /**
-     * Wait until all queued events are processed.
-     * Subsequent new events will not be waited, but new events will not be added.
-     * @returns
+     * Complete the finite set of operations accepted before this call.
+     * Later edits cannot replace or extend that set while it is being flushed.
      */
     waitForIdle(): Promise<void>;
+    /** Stop watcher admission before draining or preserving accepted work. */
+    stopWatching(): Promise<void>;
     /**
      * Proceed waiting for the given key immediately.
      */