@vrtmrz/livesync-commonlib 0.3.1 → 0.4.0

package/README.md

@@ -14,7 +14,7 @@ This package is primarily for maintainers of those clients and for integrations
 
 ## Status and versioning
 
-Commonlib [0.3.0](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.0)
+Commonlib [0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1)
 is published on npm. Self-hosted LiveSync
 [1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
 uses Commonlib 0.2.3. The [0.2.3 release notes](updates.md#023) record its
@@ -45,6 +45,16 @@ while retaining conditional revalidation within a Seed. See
 [CouchDB response caching](docs/couchdb-http-cache.md) for the request,
 replication-preparation, and host-adapter boundaries.
 
+Journal receipt stops at a per-Journal decode, record, or write failure and
+retries that Journal on the next receive attempt. A host can offer the explicit
+'Skip stopped Journal and resume' operation for the current stopped failure;
+it skips only that Journal, and a later failure stops receipt again. A skip can
+leave content or history incomplete. Use the existing Reset journal received
+history operation to replay entries after correcting the failure, while the
+remote objects remain available and readable. See the
+[Journal receive failures and recovery](docs/journal-receive-recovery.md) for
+the receive, skip, and replay boundaries.
+
 ## Package entry points
 
 | Entry point                                        | Intended use                                                                      | Current contract status                                                                     |
@@ -139,6 +149,23 @@ After the Self-hosted LiveSync 1.0 work, the planned high-level composition is a
 
 The factory is not implemented yet. Until it is available, service implementations exposed under `compat/*` retain their owning client's lifecycle rather than becoming a general public composition API.
 
+### Host cleanup registration
+
+Available from 0.4.0, `services.API.registerCleanup(callback)` registers synchronous
+cleanup for the owning host's normal terminal unload. The default `APIService` implementation
+uses the context-owned `EVENT_PLATFORM_UNLOADED` event once per registration.
+CLI and browser hosts already deliver that event through `ControlService.onUnload()`
+after their asynchronous lifecycle work and local database closure. An unload
+interrupted before that event does not invoke these callbacks.
+
+The Obsidian adapter delegates to native `Component.register()` and retains that
+host's unload timing. This API therefore does not promise one shared shutdown
+phase across hosts. Register callbacks before terminal unload, and use it for
+presentation resources and subscriptions. Returned promises are not awaited;
+resources which must retire before database closure belong to
+`appLifecycle.onUnload` instead. The registration does not add process signals,
+browser navigation handlers, or a new shutdown/recovery path.
+
 ## UI commands
 
 Import `declareUICommand` and `UICommandRegistry` from `@vrtmrz/livesync-commonlib/ui-commands`. A declaration binds a stable command ID to its request and result types. Each `UIService` owns its own `commands` registry; declarations do not register global handlers.
@@ -315,7 +342,7 @@ Commonlib 0.3.0 provides [Unicode NFC path identity](docs/unicode-path-identity.
 
 ## Direct database watches
 
-An unreleased extension lets direct CouchDB integrations select
+Commonlib 0.3.1 lets direct CouchDB integrations select
 `pathNormalizationVersion: 1` in `DirectFileManipulator` options. Omitted or
 `0` retains Legacy identity. The configured mode must match the database;
 NFC does not relabel a populated Legacy database. A confirmed empty database

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -162,7 +162,7 @@ async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarg
       path: note.path,
       ctime: note.ctime,
       mtime: note.mtime,
-      size: note.size,
+      size: data.size,
       type: note.datatype,
       eden: {}
     };

package/dist/p2p/P2PService.d.ts

@@ -1,8 +1,9 @@
+import { type P2PDiagnosticEvent, type P2PDiagnosticSnapshot } from "./p2pDiagnostics.js";
 import type { ObsidianLiveSyncSettings } from "../common/types.js";
 import type { ReplicatorInstance } from "../replication/ReplicatorInstance.js";
 import type { DiagRTCPeerConnectionMetrics } from "../rpc/transports/DiagRTCPeerConnections.types.js";
 import { LiveSyncTrysteroReplicator, type LiveSyncTrysteroReplicatorEnv } from "../replication/trystero/LiveSyncTrysteroReplicator.js";
-import type { P2PReplicationResult } from "../replication/trystero/TrysteroReplicator.js";
+import type { P2PReplicationProgress, P2PReplicationResult } from "../replication/trystero/TrysteroReplicator.js";
 import type { AcceptanceDecision, RevokeAcceptanceDecision } from "../replication/trystero/TrysteroReplicatorP2PServer.js";
 import type { Advertisement } from "../replication/trystero/types.js";
 import { type PrepareP2PSettings } from "../replication/trystero/P2PRoomSessionOwner.js";
@@ -79,6 +80,14 @@ export interface P2PConfigurationExchange {
 /** Supplies transport diagnostics without exposing a room or peer connection. */
 export interface P2PDiagnostics {
     requestStatus(): void;
+    /** Latest owned observation in each category; absent categories remain unobserved. */
+    getDiagnosticSnapshot?(): P2PDiagnosticSnapshot;
+    /** Observe accepted diagnostic events; the returned function removes this subscription. */
+    onDiagnosticEvent?(listener: (event: P2PDiagnosticEvent) => void): () => void;
+    /** Current per-peer sequence progress and optional cumulative transfer statistics. */
+    getReplicationProgress?(): readonly P2PReplicationProgress[];
+    /** Observe subsequent snapshots; the returned function removes this subscription. */
+    onReplicationProgress?(listener: (snapshot: readonly P2PReplicationProgress[]) => void): () => void;
     getPeerConnectionMetrics(peerId: string): Promise<P2PPeerConnectionMetrics | undefined>;
 }
 /** Focused contract views backed by one private P2P service context. */

package/dist/p2p/P2PService.js

@@ -1,7 +1,9 @@
+import { createP2PDiagnosticStore } from "./p2pDiagnostics.js";
 import { getPeerConnectionStats } from "../rpc/transports/DiagRTCPeerConnections.utils.js";
 import {
   LiveSyncTrysteroReplicator
 } from "../replication/trystero/LiveSyncTrysteroReplicator.js";
+import { P2PLogCollector } from "../replication/trystero/P2PLogCollector.js";
 import {
   P2PRoomSessionOwner
 } from "../replication/trystero/P2PRoomSessionOwner.js";
@@ -207,6 +209,15 @@ function createServiceViews(context) {
     getRemoteConfiguration: (peerId) => context.compatibilityReplicator.getRemoteConfig(peerId)
   };
   const diagnostics = {
+    getDiagnosticSnapshot: context.diagnosticStore.getSnapshot,
+    onDiagnosticEvent: context.diagnosticStore.subscribe,
+    getReplicationProgress: () => context.progressCollector.p2pReplicationStats.value,
+    onReplicationProgress: (listener) => {
+      const progress = context.progressCollector.p2pReplicationStats;
+      const onChanged = () => listener(progress.value);
+      progress.onChanged(onChanged);
+      return () => progress.offChanged(onChanged);
+    },
     requestStatus: () => context.compatibilityReplicator.requestStatus(),
     getPeerConnectionMetrics: (peerId) => getPeerConnectionMetrics(context, peerId)
   };
@@ -231,7 +242,11 @@ function createServiceLifecycle(context) {
   };
 }
 function createP2PService(env, options = {}) {
-  const roomSessionOwner = new P2PRoomSessionOwner(env, void 0, options);
+  const diagnosticStore = createP2PDiagnosticStore(env.services.context.events);
+  const roomSessionOwner = new P2PRoomSessionOwner(env, void 0, {
+    ...options,
+    onDiagnosticEvent: diagnosticStore.record
+  });
   const state = {
     explicitDisconnectVeto: false,
     lifecycleClosed: false,
@@ -242,7 +257,15 @@ function createP2PService(env, options = {}) {
     env,
     createCompatibilitySessionAccess(roomSessionOwner, state)
   );
-  const context = { env, roomSessionOwner, compatibilityReplicator, state };
+  const progressCollector = new P2PLogCollector(env.services.context.events);
+  const context = {
+    env,
+    roomSessionOwner,
+    compatibilityReplicator,
+    state,
+    progressCollector,
+    diagnosticStore
+  };
   return {
     compatibilityReplicator,
     views: createServiceViews(context),

package/dist/p2p/index.d.ts

@@ -4,7 +4,10 @@ export { useP2PReplicatorCommands } from "../replication/trystero/useP2PReplicat
 export { useP2PReplicatorFeature } from "../replication/trystero/useP2PReplicatorFeature.js";
 export type { OpenRebuildUIFactory, OpenReplicationUIFactory, } from "../replication/trystero/useP2PReplicatorFeature.js";
 export type { UseP2PReplicatorResult } from "../replication/trystero/UseP2PReplicatorResult.js";
-export type { P2PReplicationResult } from "../replication/trystero/TrysteroReplicator.js";
+export type { ReplicationStatistics } from "../pouchdb/ReplicatorShim.js";
+export type { P2PReplicationProgress, P2PReplicationDirectionProgress, P2PReplicationResult, } from "../replication/trystero/TrysteroReplicator.js";
 export type { Advertisement } from "../replication/trystero/types.js";
 export { P2P_ICE_SERVER_EXPIRY_MARGIN_MS, P2P_SETTINGS_PREPARATION_TIMEOUT_MS, } from "../replication/trystero/P2PRoomSessionOwner.js";
 export type { P2PReplicatorFeatureOptions } from "../replication/trystero/useP2PReplicatorFeature.js";
+export { EVENT_P2P_DIAGNOSTIC } from "./p2pDiagnostics.js";
+export type { P2PDiagnosticCategory, P2PDiagnosticCode, P2PDiagnosticReason, P2PDiagnosticEvent, P2PDiagnosticSnapshot, } from "./p2pDiagnostics.js";

package/dist/p2p/index.js

@@ -5,8 +5,10 @@ import {
   P2P_ICE_SERVER_EXPIRY_MARGIN_MS,
   P2P_SETTINGS_PREPARATION_TIMEOUT_MS
 } from "../replication/trystero/P2PRoomSessionOwner.js";
+import { EVENT_P2P_DIAGNOSTIC } from "./p2pDiagnostics.js";
 export {
   ACTIVE_P2P_RELAY_BINDING_CONFLICT,
+  EVENT_P2P_DIAGNOSTIC,
   P2P_ICE_SERVER_EXPIRY_MARGIN_MS,
   P2P_SETTINGS_PREPARATION_TIMEOUT_MS,
   useP2PReplicatorCommands,

package/dist/p2p/p2pDiagnostics.d.ts

@@ -0,0 +1,35 @@
+import type { LiveSyncEventHub } from "../hub/hub.js";
+/** Lightweight, context-owned observations without transport or configuration secrets. */
+export type P2PDiagnosticCategory = "relay" | "peer" | "sync";
+export type P2PDiagnosticCode = "room-opening" | "room-opened" | "room-closed" | "room-open-failed" | "room-close-failed" | "room-open-cancelled" | "room-join-error" | "peer-advertised" | "peer-left" | "rtc-failed" | "auth-accepted" | "auth-refused" | "auth-timeout" | "auth-cancelled" | "auth-error" | "pull-started" | "pull-completed" | "pull-failed" | "pull-cancelled" | "watch-enabled" | "watch-disabled" | "watch-skipped" | "broadcast-enabled" | "broadcast-disabled" | "change-notification-received" | "change-notification-ignored" | "change-notification-sent" | "change-notification-timeout" | "change-notification-cancelled" | "change-notification-error";
+export type P2PDiagnosticReason = "relay-details-unobserved" | "transport-error" | "operation-cancelled" | "rpc-timeout" | "rpc-cancelled" | "rpc-error" | "authentication-refused" | "authentication-unobserved" | "replication-error" | "replication-not-ready" | "already-running" | "not-watching" | "not-accepted" | "setup-in-progress" | "peer-not-broadcasting" | "peer-broadcast-unobserved" | "ICE_GATHERING_NOT_COMPLETED" | "ICE_CONNECTIVITY_FAILED" | "STUN_REQUEST_TIMEOUT" | "SIGNALING_NOT_STABLE" | "CONNECTION_DROPPED_AFTER_ESTABLISHED" | "NETWORK_INTERRUPTED" | "UNKNOWN";
+export type P2PDiagnosticEvent = {
+    readonly category: P2PDiagnosticCategory;
+    readonly code: P2PDiagnosticCode;
+    /** Milliseconds since the Unix epoch, captured at the observed source boundary. */
+    readonly timestamp: number;
+    readonly peerId?: string;
+    readonly reason?: P2PDiagnosticReason;
+};
+/** Missing categories have not been observed; no zero or successful result is implied. */
+export type P2PDiagnosticSnapshot = Readonly<Partial<Record<P2PDiagnosticCategory, P2PDiagnosticEvent>>>;
+export type P2PDiagnosticInput = Omit<P2PDiagnosticEvent, "timestamp">;
+export type P2PDiagnosticReporter = (event: P2PDiagnosticEvent) => void;
+/** Accepted, fenced events from the diagnostic store of this Commonlib context. */
+export declare const EVENT_P2P_DIAGNOSTIC = "p2p-diagnostic";
+declare global {
+    interface LSEvents {
+        [EVENT_P2P_DIAGNOSTIC]: P2PDiagnosticEvent;
+    }
+}
+/** Publish a fixed observation without allowing diagnostic callbacks to affect the operation. */
+export declare function reportP2PDiagnostic(reporter: P2PDiagnosticReporter | undefined, input: P2PDiagnosticInput): void;
+/** Classify only stable RPC error identifiers; never expose the error text or details. */
+export declare function classifyP2PRpcFailure(error: unknown, signal?: AbortSignal): "rpc-timeout" | "rpc-cancelled" | "rpc-error";
+/** Retain only the latest observation of each category for one service context. */
+export declare function createP2PDiagnosticStore(events: LiveSyncEventHub): {
+    getSnapshot: () => P2PDiagnosticSnapshot;
+    subscribe: (listener: P2PDiagnosticReporter) => (() => void);
+    record: (input: P2PDiagnosticEvent) => void;
+    dispose: () => void;
+};

package/dist/p2p/p2pDiagnostics.js

@@ -0,0 +1,76 @@
+import { EVENT_PLATFORM_UNLOADED } from "../events/coreEvents.js";
+const EVENT_P2P_DIAGNOSTIC = "p2p-diagnostic";
+function reportP2PDiagnostic(reporter, input) {
+  if (!reporter) {
+    return;
+  }
+  try {
+    reporter(Object.freeze({ ...input, timestamp: Date.now() }));
+  } catch {
+  }
+}
+function classifyP2PRpcFailure(error, signal) {
+  const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+  const name = typeof error === "object" && error !== null && "name" in error ? error.name : void 0;
+  if (signal?.aborted || code === "CANCELLED" || name === "AbortError") {
+    return "rpc-cancelled";
+  }
+  return code === "TIMEOUT" ? "rpc-timeout" : "rpc-error";
+}
+function createP2PDiagnosticStore(events) {
+  let snapshot = Object.freeze({});
+  let disposed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const lifetime = new AbortController();
+  const dispose = () => {
+    disposed = true;
+    listeners.clear();
+    lifetime.abort();
+  };
+  events.onEvent(EVENT_PLATFORM_UNLOADED, dispose, { signal: lifetime.signal });
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      if (!disposed) {
+        listeners.add(listener);
+      }
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    record: (input) => {
+      if (disposed) {
+        return;
+      }
+      const event = Object.freeze({
+        category: input.category,
+        code: input.code,
+        timestamp: input.timestamp,
+        ...input.peerId !== void 0 ? { peerId: input.peerId } : {},
+        ...input.reason !== void 0 ? { reason: input.reason } : {}
+      });
+      const previous = snapshot[event.category];
+      if (previous?.code === event.code && previous.peerId === event.peerId && previous.reason === event.reason && previous.timestamp === event.timestamp) {
+        return;
+      }
+      snapshot = Object.freeze({ ...snapshot, [event.category]: event });
+      for (const listener of listeners) {
+        try {
+          listener(event);
+        } catch {
+        }
+      }
+      try {
+        events.emitEvent(EVENT_P2P_DIAGNOSTIC, event);
+      } catch {
+      }
+    },
+    dispose
+  };
+}
+export {
+  EVENT_P2P_DIAGNOSTIC,
+  classifyP2PRpcFailure,
+  createP2PDiagnosticStore,
+  reportP2PDiagnostic
+};

package/dist/pouchdb/ReplicatorShim.batch.d.ts

@@ -0,0 +1,30 @@
+import type { ShimReplicationWriteFailure } from "./ReplicatorShim.js";
+export type MissingRevisionRequest = {
+    id: string;
+    rev: string;
+};
+/** Parse the numeric part of a PouchDB sequence value ("42-xyz" → 42). */
+export declare function parseSeq(seq: string | number): number;
+/**
+ * Build the `{docId: [rev, ...]}` map required by `revsDiff` from a changes
+ * feed result set, merging revisions when the same document appears multiple
+ * times in a batch.
+ */
+export declare function buildRevsDiffParam(changesResults: PouchDB.Core.ChangesResponseChange<object>[]): Record<string, string[]>;
+/**
+ * Sort fetched documents in ascending sequence order so that consumers receive
+ * them in the same order they were written to the source.
+ */
+export declare function sortBySeq<T extends {
+    _id: string;
+}>(docs: T[], changesResults: PouchDB.Core.ChangesResponseChange<object>[]): T[];
+export declare function buildMissingRevisionRequests(diff: PouchDB.Core.RevisionDiffResponse): MissingRevisionRequest[];
+export declare function findUnavailableRevisionRequests(requests: readonly MissingRevisionRequest[], fetchedDocs: readonly {
+    _id: string;
+    _rev?: string;
+}[]): MissingRevisionRequest[];
+export declare function buildUnavailableRevisionFailures(requests: readonly MissingRevisionRequest[]): ShimReplicationWriteFailure[];
+export declare function mapBulkDocResultsToFailures<T extends {
+    _id: string;
+    _rev?: string;
+}>(writeResults: (PouchDB.Core.Response | PouchDB.Core.Error)[], fetchedDocs: T[]): ShimReplicationWriteFailure[];

package/dist/pouchdb/ReplicatorShim.batch.js

@@ -0,0 +1,62 @@
+function parseSeq(seq) {
+  return parseInt(String(seq).split("-")[0], 10);
+}
+function buildRevsDiffParam(changesResults) {
+  const param = {};
+  for (const { id, changes } of changesResults) {
+    param[id] = [...param[id] ?? [], ...changes.map((c) => c.rev)];
+  }
+  return param;
+}
+function sortBySeq(docs, changesResults) {
+  const maxSeqById = /* @__PURE__ */ new Map();
+  for (const { id, seq } of changesResults) {
+    maxSeqById.set(id, Math.max(maxSeqById.get(id) ?? 0, parseSeq(seq)));
+  }
+  return docs.slice().sort((a, b) => (maxSeqById.get(a._id) ?? 0) - (maxSeqById.get(b._id) ?? 0));
+}
+function isSuccessfulBulkDocResult(result) {
+  return typeof result === "object" && result !== null && "ok" in result && result.ok === true;
+}
+function buildMissingRevisionRequests(diff) {
+  return Object.entries(diff).filter(([, entry]) => entry.missing !== void 0).flatMap(([id, entry]) => entry.missing.map((rev) => ({ id, rev })));
+}
+function findUnavailableRevisionRequests(requests, fetchedDocs) {
+  const fetchedRevisionKeys = new Set(fetchedDocs.map((doc) => doc._id + "\0" + String(doc._rev)));
+  return requests.filter(({ id, rev }) => !fetchedRevisionKeys.has(id + "\0" + rev));
+}
+function buildUnavailableRevisionFailures(requests) {
+  return requests.map((request, index) => ({
+    index,
+    id: request.id,
+    revision: request.rev,
+    result: void 0
+  }));
+}
+function mapBulkDocResultsToFailures(writeResults, fetchedDocs) {
+  return writeResults.flatMap((result, index) => {
+    if (isSuccessfulBulkDocResult(result)) {
+      return [];
+    }
+    const resultId = typeof result === "object" && result !== null && "id" in result ? result.id : void 0;
+    const owningIndex = typeof resultId === "string" ? fetchedDocs.findIndex((doc) => doc._id === resultId) : -1;
+    const owningDocument = fetchedDocs[owningIndex >= 0 ? owningIndex : index];
+    return [
+      {
+        index: owningIndex >= 0 ? owningIndex : index,
+        id: typeof resultId === "string" ? resultId : owningDocument?._id ?? "",
+        revision: owningDocument?._rev,
+        result
+      }
+    ];
+  });
+}
+export {
+  buildMissingRevisionRequests,
+  buildRevsDiffParam,
+  buildUnavailableRevisionFailures,
+  findUnavailableRevisionRequests,
+  mapBulkDocResultsToFailures,
+  parseSeq,
+  sortBySeq
+};

package/dist/pouchdb/ReplicatorShim.d.ts

@@ -26,6 +26,11 @@ export type ShimReplicationOptionBase = {
     batch_size?: number;
     /** Abort before a new batch starts, or after the current batch settles. */
     signal?: AbortSignal;
+    /**
+     * Observe cumulative counts, including batches with no missing revisions and
+     * accepted writes before a batch failure. Observation does not commit a checkpoint.
+     */
+    onStatistics?: (info: ProgressInfo) => void | Promise<void>;
 };
 /** Options for a finite replication which settles after catching up or cancellation. */
 export type ShimReplicationOneShot = {
@@ -66,10 +71,18 @@ export declare class ShimReplicationError extends Error {
     readonly failures: readonly ShimReplicationWriteFailure[];
     constructor(message: string, failures: readonly ShimReplicationWriteFailure[]);
 }
-/** Sequence boundary committed by one successfully written batch. */
+/** Cumulative work observed during one invocation of the replication shim. */
+export type ReplicationStatistics = {
+    /** Successfully transferred document revisions, including Metadata and Chunks. */
+    documents: number;
+    /** Changes-feed entries compared, including revisions already held by the target. */
+    checkedChanges: number;
+};
+/** Source sequence boundary for a batch, with optional cumulative transfer counts. */
 export type ProgressInfo = {
     lastSeq: number;
     maxSeqInBatch: number;
+    statistics?: ReplicationStatistics;
 };
 /** Receives the documents and committed sequence boundary for each completed batch. */
 export type ShimReplicationProgressReportFunc<T extends object> = (progress: SomeDocument<T>[], progressInfo: ProgressInfo) => Promise<void>;

package/dist/pouchdb/ReplicatorShim.js

@@ -1,6 +1,15 @@
 import { serialized } from "octagonal-wheels/concurrency/lock";
 import { Logger } from "../common/logger.js";
 import { LOG_LEVEL_VERBOSE } from "../common/types.js";
+import {
+  buildMissingRevisionRequests,
+  buildRevsDiffParam,
+  buildUnavailableRevisionFailures,
+  findUnavailableRevisionRequests,
+  mapBulkDocResultsToFailures,
+  parseSeq,
+  sortBySeq
+} from "./ReplicatorShim.batch.js";
 async function upsert(db, id, func) {
   try {
     const doc = await db.get(id);
@@ -31,32 +40,14 @@ class ShimReplicationError extends Error {
   }
   failures;
 }
-function parseSeq(seq) {
-  return parseInt(String(seq).split("-")[0], 10);
-}
-function buildRevsDiffParam(changesResults) {
-  const param = {};
-  for (const { id, changes } of changesResults) {
-    param[id] = [...param[id] ?? [], ...changes.map((c) => c.rev)];
-  }
-  return param;
-}
-function sortBySeq(docs, changesResults) {
-  const maxSeqById = /* @__PURE__ */ new Map();
-  for (const { id, seq } of changesResults) {
-    maxSeqById.set(id, Math.max(maxSeqById.get(id) ?? 0, parseSeq(seq)));
-  }
-  return docs.slice().sort((a, b) => (maxSeqById.get(a._id) ?? 0) - (maxSeqById.get(b._id) ?? 0));
-}
-function isSuccessfulBulkDocResult(result) {
-  return typeof result === "object" && result !== null && "ok" in result && result.ok === true;
-}
 function isCancellationError(error) {
   if (typeof error !== "object" || error === null) return false;
   return "code" in error && error.code === "CANCELLED" || "name" in error && error.name === "AbortError";
 }
 async function replicateShim(targetDB, sourceDB, progress, option = {}) {
   const signal = option.signal ?? option.controller?.signal;
+  const statistics = { documents: 0, checkedChanges: 0 };
+  let lastProcessedSeq = 0;
   if (signal?.aborted) {
     Logger(`Replication cancelled`, LOG_LEVEL_VERBOSE);
     return { status: "cancelled" };
@@ -96,71 +87,64 @@ async function replicateShim(targetDB, sourceDB, progress, option = {}) {
         const changesResults = changes.results;
         const revsDiffParam = buildRevsDiffParam(changesResults);
         const diff = await targetDB.revsDiff(revsDiffParam);
-        if (signal?.aborted) return { status: "cancelled" };
-        const missingRequests = Object.entries(diff).filter(([, entry]) => entry.missing !== void 0).flatMap(([id, entry]) => entry.missing.map((rev) => ({ id, rev })));
-        if (missingRequests.length > 0) {
-          const bulkGetResult = await sourceDB.bulkGet({ docs: missingRequests, revs: true });
-          const fetchedDocs = bulkGetResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
+        statistics.checkedChanges += changesResults.length;
+        const progressInfo = (lastSeq = lastProcessedSeq) => ({
+          lastSeq,
+          maxSeqInBatch: maxNumSeq,
+          statistics: { ...statistics }
+        });
+        try {
           if (signal?.aborted) return { status: "cancelled" };
-          const fetchedRevisionKeys = new Set(
-            fetchedDocs.map((doc) => `${doc._id}\0${String(doc._rev)}`)
-          );
-          const unavailableRequests = missingRequests.filter(
-            ({ id, rev }) => !fetchedRevisionKeys.has(`${id}\0${rev}`)
-          );
-          if (unavailableRequests.length > 0) {
-            const unavailableFailures = unavailableRequests.map(
-              (request, index) => ({
-                index,
-                id: request.id,
-                revision: request.rev,
-                result: void 0
-              })
-            );
-            throw new ShimReplicationError(
-              `Could not fetch ${unavailableRequests.length} required revision(s)`,
-              unavailableFailures
-            );
-          }
-          const writeResults = await targetDB.bulkDocs(fetchedDocs, { new_edits: false });
-          const failedWrites = writeResults.flatMap((result, index) => {
-            if (isSuccessfulBulkDocResult(result)) return [];
-            const resultId = typeof result === "object" && result !== null && "id" in result ? result.id : void 0;
-            const owningIndex = typeof resultId === "string" ? fetchedDocs.findIndex((doc) => doc._id === resultId) : -1;
-            const owningDocument = fetchedDocs[owningIndex >= 0 ? owningIndex : index];
-            return [
-              {
-                index: owningIndex >= 0 ? owningIndex : index,
-                id: typeof resultId === "string" ? resultId : owningDocument?._id ?? "",
-                revision: owningDocument?._rev,
-                result
-              }
-            ];
-          });
-          if (failedWrites.length > 0) {
-            throw new ShimReplicationError(
-              `Target rejected ${failedWrites.length} document write(s)`,
-              failedWrites
-            );
+          const missingRequests = buildMissingRevisionRequests(diff);
+          if (missingRequests.length > 0) {
+            const bulkGetResult = await sourceDB.bulkGet({ docs: missingRequests, revs: true });
+            const fetchedDocs = bulkGetResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
+            if (signal?.aborted) return { status: "cancelled" };
+            const unavailableRequests = findUnavailableRevisionRequests(missingRequests, fetchedDocs);
+            if (unavailableRequests.length > 0) {
+              const unavailableFailures = buildUnavailableRevisionFailures(unavailableRequests);
+              throw new ShimReplicationError(
+                `Could not fetch ${unavailableRequests.length} required revision(s)`,
+                unavailableFailures
+              );
+            }
+            const writeResults = await targetDB.bulkDocs(fetchedDocs, { new_edits: false });
+            const failedWrites = mapBulkDocResultsToFailures(writeResults, fetchedDocs);
+            statistics.documents += Math.max(0, fetchedDocs.length - failedWrites.length);
+            if (failedWrites.length > 0) {
+              throw new ShimReplicationError(
+                `Target rejected ${failedWrites.length} document write(s)`,
+                failedWrites
+              );
+            }
+            const uniqueIds = [...new Set(changesResults.map((c) => c.id))];
+            const refreshResult = await targetDB.bulkGet({ docs: uniqueIds.map((id) => ({ id })) });
+            const refreshedDocs = refreshResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
+            const orderedDocs = sortBySeq(refreshedDocs, changesResults);
+            try {
+              const batchSeq = parseSeq(changes.last_seq);
+              await progress(orderedDocs, progressInfo(batchSeq));
+              lastProcessedSeq = batchSeq;
+            } catch (ex) {
+              Logger(`Progress callback failed during shim-replication`, LOG_LEVEL_VERBOSE);
+              Logger(ex, LOG_LEVEL_VERBOSE);
+            }
           }
-          const uniqueIds = [...new Set(changesResults.map((c) => c.id))];
-          const refreshResult = await targetDB.bulkGet({ docs: uniqueIds.map((id) => ({ id })) });
-          const refreshedDocs = refreshResult.results.flatMap((r) => r.docs).filter((d) => "ok" in d).map((d) => d.ok);
-          const orderedDocs = sortBySeq(refreshedDocs, changesResults);
-          const lastSeqNum = parseSeq(changes.last_seq);
+          since = changes.last_seq;
+          await upsert(targetDB, targetCheckpointID, (doc) => ({
+            ...doc,
+            since
+          }));
+          if (missingRequests.length === 0) lastProcessedSeq = parseSeq(changes.last_seq);
+          if (signal?.aborted) return { status: "cancelled" };
+        } finally {
           try {
-            await progress(orderedDocs, { lastSeq: lastSeqNum, maxSeqInBatch: maxNumSeq });
-          } catch (ex) {
-            Logger(`Progress callback failed during shim-replication`, LOG_LEVEL_VERBOSE);
-            Logger(ex, LOG_LEVEL_VERBOSE);
+            await option.onStatistics?.(progressInfo());
+          } catch (error) {
+            Logger(`Statistics observer failed during shim-replication`, LOG_LEVEL_VERBOSE);
+            Logger(error, LOG_LEVEL_VERBOSE);
           }
         }
-        since = changes.last_seq;
-        await upsert(targetDB, targetCheckpointID, (doc) => ({
-          ...doc,
-          since
-        }));
-        if (signal?.aborted) return { status: "cancelled" };
       }
     });
     Logger(outcome.status === "cancelled" ? `Replication cancelled` : `Replication completed`, LOG_LEVEL_VERBOSE);

package/dist/replication/SyncParamsHandler.d.ts

@@ -32,6 +32,7 @@ export declare class SyncParamsNotFoundError extends SyncParamsHandlerError {
 }
 export declare class SyncParamsUpdateError extends SyncParamsHandlerError {
 }
+export declare function isSyncParamsError(error: unknown): error is SyncParamsFetchError | SyncParamsNotFoundError | SyncParamsUpdateError;
 /** Create a handler owned by one operation rather than the process-wide server cache. */
 export declare function createSyncParamsHandler({ put, get, create }: CreateSyncParamsHanderOptions): SyncParamsHandler;
 export {};

package/dist/replication/SyncParamsHandler.js

@@ -22,6 +22,9 @@ class SyncParamsNotFoundError extends SyncParamsHandlerError {
 }
 class SyncParamsUpdateError extends SyncParamsHandlerError {
 }
+function isSyncParamsError(error) {
+  return error instanceof SyncParamsFetchError || error instanceof SyncParamsNotFoundError || error instanceof SyncParamsUpdateError;
+}
 function createSyncParamsHandler({ put, get, create }) {
   let taskFetchParameters = void 0;
   const _fetchSyncParameters = async () => {
@@ -115,5 +118,6 @@ export {
   SyncParamsUpdateError,
   clearHandlers,
   createSyncParamsHanderForServer,
-  createSyncParamsHandler
+  createSyncParamsHandler,
+  isSyncParamsError
 };

package/dist/replication/journal/JournalReceiveFailure.d.ts

@@ -0,0 +1,7 @@
+import type { JournalReceiveFailureStage } from "./JournalSyncTypes.js";
+export declare class JournalReceiveFailure extends Error {
+    readonly stage: JournalReceiveFailureStage;
+    readonly key?: string;
+    constructor(stage: JournalReceiveFailureStage, key?: string);
+}
+export declare function isJournalReceiveFailure(error: unknown): error is JournalReceiveFailure;

package/dist/replication/journal/JournalReceiveFailure.js

@@ -0,0 +1,16 @@
+class JournalReceiveFailure extends Error {
+  constructor(stage, key) {
+    super("Journal receive failed at " + stage);
+    this.stage = stage;
+    this.key = key;
+  }
+  stage;
+  key;
+}
+function isJournalReceiveFailure(error) {
+  return error instanceof JournalReceiveFailure;
+}
+export {
+  JournalReceiveFailure,
+  isJournalReceiveFailure
+};