@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/hub/hub.d.ts

@@ -0,0 +1,11 @@
+import { EventHub } from "octagonal-wheels/events";
+declare global {
+    interface LSEvents {
+        hello: string;
+        world: undefined;
+    }
+}
+/** An event hub owned by one Commonlib service context. */
+export type LiveSyncEventHub = EventHub<LSEvents>;
+/** Creates an isolated event hub for one Commonlib client or host composition. */
+export declare function createLiveSyncEventHub(): LiveSyncEventHub;

package/dist/hub/hub.js

@@ -0,0 +1,7 @@
+import { EventHub } from "octagonal-wheels/events";
+function createLiveSyncEventHub() {
+  return new EventHub();
+}
+export {
+  createLiveSyncEventHub
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { DirectFileManipulator, type DirectFileManipulatorOptions } from "./API/DirectFileManipulator.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+import { DirectFileManipulator } from "./API/DirectFileManipulator.js";
+export {
+  DirectFileManipulator
+};

package/dist/interfaces/AsyncActivityRunner.d.ts

@@ -0,0 +1,18 @@
+/** Options attached to one bounded asynchronous activity. */
+export interface AsyncActivityOptions {
+    /** An optional diagnostic label supplied to the activity owner. */
+    label?: string;
+}
+/**
+ * Runs bounded asynchronous work inside a consumer-owned activity scope.
+ *
+ * The common library deliberately does not prescribe what the scope does. A
+ * browser host may keep the screen awake, while a headless host may omit the
+ * runner and execute the task directly.
+ */
+export interface AsyncActivityRunner {
+    /** Runs the task and returns its result without changing its error semantics. */
+    run<T>(task: () => T | PromiseLike<T>, options?: AsyncActivityOptions): Promise<T>;
+}
+/** Runs a task through the injected activity owner, or directly when none is supplied. */
+export declare function runWithOptionalActivity<T>(runner: AsyncActivityRunner | undefined, task: () => T | PromiseLike<T>, options?: AsyncActivityOptions): Promise<T>;

package/dist/interfaces/AsyncActivityRunner.js

@@ -0,0 +1,7 @@
+async function runWithOptionalActivity(runner, task, options) {
+  if (runner) return await runner.run(task, options);
+  return await task();
+}
+export {
+  runWithOptionalActivity
+};

package/dist/interfaces/Confirm.d.ts

@@ -0,0 +1,17 @@
+export interface Confirm {
+    askYesNo(message: string): Promise<"yes" | "no">;
+    askString(title: string, key: string, placeholder: string, isPassword?: boolean): Promise<string | false>;
+    askYesNoDialog(message: string, opt: {
+        title?: string;
+        defaultOption?: "Yes" | "No";
+        timeout?: number;
+    }): Promise<"yes" | "no">;
+    askSelectString(message: string, items: string[]): Promise<string>;
+    askSelectStringDialogue<T extends readonly string[]>(message: string, buttons: T, opt: {
+        title?: string;
+        defaultAction: T[number];
+        timeout?: number;
+    }): Promise<T[number] | false>;
+    askInPopup(key: string, dialogText: string, anchorCallback: (anchor: HTMLAnchorElement) => void): void;
+    confirmWithMessage(title: string, contentMd: string, buttons: string[], defaultAction: (typeof buttons)[number], timeout?: number): Promise<(typeof buttons)[number] | false>;
+}

package/dist/interfaces/DatabaseFileAccess.d.ts

@@ -0,0 +1,14 @@
+import type { FilePathWithPrefix, LoadedEntry, MetaEntry, UXFileInfo, UXFileInfoStub } from "../common/types.js";
+export interface DatabaseFileAccess {
+    delete: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string) => Promise<boolean>;
+    store: (file: UXFileInfo, force?: boolean, skipCheck?: boolean) => Promise<boolean>;
+    storeAsConflictedRevision: (file: UXFileInfo, currentRev: string, skipCheck?: boolean) => Promise<boolean>;
+    storeContent(path: FilePathWithPrefix, content: string): Promise<boolean>;
+    createChunks: (file: UXFileInfo, force?: boolean, skipCheck?: boolean) => Promise<boolean>;
+    hasContentInRevisionHistory: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string) => Promise<boolean>;
+    fetch: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean) => Promise<UXFileInfo | false>;
+    fetchEntryFromMeta: (meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean) => Promise<LoadedEntry | false>;
+    fetchEntryMeta: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, skipCheck?: boolean) => Promise<MetaEntry | false>;
+    fetchEntry: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean) => Promise<LoadedEntry | false>;
+    getConflictedRevs: (file: UXFileInfoStub | FilePathWithPrefix) => Promise<string[]>;
+}

package/dist/interfaces/DatabaseRebuilder.d.ts

@@ -0,0 +1,13 @@
+export interface Rebuilder {
+    $performRebuildDB(method: "localOnly" | "remoteOnly" | "rebuildBothByThisDevice" | "localOnlyWithChunks"): Promise<void>;
+    $rebuildRemote(): Promise<void>;
+    $rebuildEverything(): Promise<void>;
+    $fetchLocal(makeLocalChunkBeforeSync?: boolean, preventMakeLocalFilesBeforeSync?: boolean): Promise<void>;
+    $fetchLocalDBFast(autoResume: boolean): Promise<void>;
+    scheduleRebuild(): Promise<void>;
+    scheduleFetch(): Promise<void>;
+    /**
+     * Declares the finish of the rebuild process and unlock remote, resume reflecting the changes.
+     */
+    finishRebuild(): Promise<void>;
+}

package/dist/interfaces/FileHandler.d.ts

@@ -0,0 +1,13 @@
+import type { FilePath, FilePathWithPrefix, MetaEntry } from "../common/models/db.type.js";
+import type { UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../common/models/fileaccess.type.js";
+export interface IFileHandler {
+    readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
+    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
+    renameFileInDB(info: UXFileInfoStub | UXFileInfo, oldPath: FilePath | FilePathWithPrefix): Promise<boolean>;
+    deleteRevisionFromDB(info: UXFileInfoStub | FilePath | FilePathWithPrefix, rev: string): Promise<boolean | undefined>;
+    resolveConflictedByDeletingRevision(info: UXFileInfoStub | FilePath, rev: string): Promise<boolean | undefined>;
+    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | null, rev: string, force?: boolean): Promise<boolean>;
+    dbToStorage(entryInfo: MetaEntry | FilePathWithPrefix, info: UXFileInfoStub | UXFileInfo | FilePath | null, force?: boolean): Promise<boolean>;
+    createAllChunks(showingNotice?: boolean): Promise<void>;
+}

package/dist/interfaces/KeyValueDatabase.d.ts

@@ -0,0 +1,11 @@
+export interface KeyValueDatabase {
+    get<T>(key: IDBValidKey): Promise<T>;
+    set<T>(key: IDBValidKey, value: T): Promise<IDBValidKey>;
+    del(key: IDBValidKey): Promise<void>;
+    clear(): Promise<void>;
+    keys(query?: IDBValidKey | IDBKeyRange, count?: number): Promise<IDBValidKey[]>;
+    close(): Promise<void>;
+    destroy(): Promise<void>;
+}
+/** Opens the key-value database owned by one service composition. */
+export type KeyValueDatabaseFactory = (databaseKey: string) => Promise<KeyValueDatabase>;

package/dist/interfaces/ServiceModule.d.ts

@@ -0,0 +1,59 @@
+import type { DatabaseFileAccess } from "./DatabaseFileAccess.js";
+import type { Rebuilder } from "./DatabaseRebuilder.js";
+import type { IFileHandler } from "./FileHandler.js";
+import type { StorageAccess } from "./StorageAccess.js";
+import type { LogFunction } from "../services/lib/logUtils.js";
+import type { ServiceHub } from "../services/ServiceHub.js";
+import type { IServiceHub } from "../services/base/IService.js";
+export interface ServiceModules {
+    storageAccess: StorageAccess;
+    /**
+     * Database File Accessor for handling file operations related to the database, such as exporting the database, importing from a file, etc.
+     */
+    databaseFileAccess: DatabaseFileAccess;
+    /**
+     * File Handler for handling file operations related to replication, such as resolving conflicts, applying changes from replication, etc.
+     */
+    fileHandler: IFileHandler;
+    /**
+     * Rebuilder for handling database rebuilding operations.
+     */
+    rebuilder: Rebuilder;
+}
+export type RequiredServices<T extends keyof ServiceHub> = Pick<ServiceHub, T | "context">;
+export type RequiredServiceModules<T extends keyof ServiceModules> = Pick<ServiceModules, T>;
+export type RequiredServicesInterfaces<T extends keyof IServiceHub> = Pick<IServiceHub, T>;
+export type RequiredServiceModulesInterfaces<T extends keyof ServiceModules> = Pick<ServiceModules, T>;
+export type NecessaryServices<T extends keyof ServiceHub, U extends keyof ServiceModules> = {
+    services: RequiredServices<T>;
+    serviceModules: RequiredServiceModules<U>;
+};
+export type NecessaryServicesInterfaces<T extends keyof IServiceHub, U extends keyof ServiceModules> = {
+    services: RequiredServicesInterfaces<T>;
+    serviceModules: RequiredServiceModulesInterfaces<U>;
+};
+export type ServiceFeatureFunction<T extends keyof ServiceHub, U extends keyof ServiceModules, TR> = (host: NecessaryServices<T, U>) => TR;
+type ServiceFeatureContext<T> = T & {
+    _log: LogFunction;
+};
+export type ServiceFeatureFunctionWithContext<T extends keyof ServiceHub, U extends keyof ServiceModules, C, TR> = (host: NecessaryServices<T, U>, context: ServiceFeatureContext<C>) => TR;
+/**
+ * Helper function to create a service feature with proper typing.
+ * @param featureFunction The feature function to be wrapped.
+ * @returns The same feature function with proper typing.
+ * @example
+ * const myFeatureDef = createServiceFeature(({ services: { API }, serviceModules: { storageAccess } }) => {
+ *   // ...
+ * });
+ * const myFeature = myFeatureDef.bind(null, this); // <- `this` may `ObsidianLiveSyncPlugin` or a custom context object
+ * appLifecycle.onLayoutReady(myFeature);
+ */
+export declare function createServiceFeature<T extends keyof ServiceHub, U extends keyof ServiceModules, TR>(featureFunction: ServiceFeatureFunction<T, U, TR>): ServiceFeatureFunction<T, U, TR>;
+type ContextFactory<T extends keyof ServiceHub, U extends keyof ServiceModules, C> = (host: NecessaryServices<T, U>) => ServiceFeatureContext<C>;
+export declare function serviceFeature<T extends keyof ServiceHub, U extends keyof ServiceModules>(): {
+    create<TR>(featureFunction: ServiceFeatureFunction<T, U, TR>): ServiceFeatureFunction<T, U, TR>;
+    withContext<C extends object = object>(ContextFactory: ContextFactory<T, U, C>): {
+        create: <TR>(featureFunction: ServiceFeatureFunctionWithContext<T, U, C, TR>) => (host: NecessaryServices<T, U>, context: ServiceFeatureContext<C>) => TR;
+    };
+};
+export {};

package/dist/interfaces/ServiceModule.js

@@ -0,0 +1,19 @@
+function createServiceFeature(featureFunction) {
+  return featureFunction;
+}
+function serviceFeature() {
+  return {
+    create(featureFunction) {
+      return featureFunction;
+    },
+    withContext(ContextFactory) {
+      return {
+        create: (featureFunction) => (host, context) => featureFunction(host, ContextFactory(host))
+      };
+    }
+  };
+}
+export {
+  createServiceFeature,
+  serviceFeature
+};

package/dist/interfaces/StorageAccess.d.ts

@@ -0,0 +1,44 @@
+import type { FilePath, FilePathWithPrefix, UXDataWriteOptions, UXFileInfo, UXFileInfoStub, UXFolderInfo, UXStat } from "../common/types.js";
+import type { CustomRegExp } from "../common/utils.js";
+import type { FileWithFileStat, FileWithStatAsProp } from "../common/models/fileaccess.type.js";
+export interface IStorageAccessManager {
+    processWriteFile<T>(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise<T>): Promise<T>;
+    processReadFile<T>(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise<T>): Promise<T>;
+    isFileProcessing(file: UXFileInfoStub | FilePathWithPrefix): boolean;
+    recentlyTouched(file: FileWithStatAsProp | FileWithFileStat): boolean;
+    touch(file: FileWithStatAsProp | FileWithFileStat): void;
+    clearTouched(): void;
+}
+export interface StorageAccess {
+    normalisePath(path: string): string;
+    restoreState(): Promise<void>;
+    deleteVaultItem(file: FilePathWithPrefix | UXFileInfoStub | UXFolderInfo): Promise<void>;
+    renameFile(file: UXFileInfoStub | FilePathWithPrefix, newPath: FilePathWithPrefix): Promise<UXFileInfoStub | null>;
+    writeFileAuto(path: string, data: string | ArrayBuffer, opt?: UXDataWriteOptions): Promise<boolean>;
+    readFileAuto(path: string): Promise<string | ArrayBuffer>;
+    readFileText(path: string): Promise<string>;
+    isExists(path: string): Promise<boolean>;
+    writeHiddenFileAuto(path: string, data: string | ArrayBuffer, opt?: UXDataWriteOptions): Promise<boolean>;
+    appendHiddenFile(path: string, data: string, opt?: UXDataWriteOptions): Promise<boolean>;
+    stat(path: string): Promise<UXStat | null>;
+    statHidden(path: string): Promise<UXStat | null>;
+    removeHidden(path: string): Promise<boolean>;
+    readHiddenFileAuto(path: string): Promise<string | ArrayBuffer>;
+    readHiddenFileBinary(path: string): Promise<ArrayBuffer>;
+    readHiddenFileText(path: string): Promise<string>;
+    isExistsIncludeHidden(path: string): Promise<boolean>;
+    ensureDir(path: string): Promise<boolean>;
+    triggerFileEvent(event: string, path: string): void;
+    triggerHiddenFile(path: string): Promise<void>;
+    getFileStub(path: string): Promise<UXFileInfoStub | null>;
+    readStubContent(stub: UXFileInfoStub): Promise<UXFileInfo | false>;
+    getStub(path: string): Promise<UXFileInfoStub | UXFolderInfo | null>;
+    getFiles(): Promise<UXFileInfoStub[]>;
+    getFileNames(): Promise<FilePathWithPrefix[]>;
+    touched(file: UXFileInfoStub | FilePathWithPrefix): Promise<void>;
+    recentlyTouched(file: UXFileInfoStub | FilePathWithPrefix): Promise<boolean>;
+    clearTouched(): void;
+    delete(file: FilePathWithPrefix | UXFileInfoStub | string, force: boolean): Promise<void>;
+    trash(file: FilePathWithPrefix | UXFileInfoStub | string, system: boolean): Promise<void>;
+    getFilesIncludeHidden(basePath: string, includeFilter?: CustomRegExp[], excludeFilter?: CustomRegExp[], skipFolder?: string[]): Promise<FilePath[]>;
+}

package/dist/interfaces/StorageEventManager.d.ts

@@ -0,0 +1,16 @@
+import type { FileEventType, FilePath, UXFileInfoStub, UXInternalFileInfoStub } from "../common/types.js";
+export type FileEvent = {
+    type: FileEventType;
+    file: UXFileInfoStub | UXInternalFileInfoStub;
+    oldPath?: string;
+    cachedData?: string;
+    skipBatchWait?: boolean;
+    cancelled?: boolean;
+};
+export declare abstract class StorageEventManager {
+    abstract beginWatch(): Promise<void>;
+    abstract appendQueue(items: FileEvent[], ctx?: unknown): Promise<void>;
+    abstract isWaiting(filename: FilePath): boolean;
+    abstract waitForIdle(): Promise<void>;
+    abstract restoreState(): Promise<void>;
+}

package/dist/interfaces/StorageEventManager.js

@@ -0,0 +1,5 @@
+class StorageEventManager {
+}
+export {
+  StorageEventManager
+};

package/dist/managers/ChangeManager.d.ts

@@ -0,0 +1,61 @@
+import { FallbackWeakRef } from "octagonal-wheels/common/polyfill";
+/**
+ * Options for configuring the ChangeManager.
+ */
+export interface ChangeManagerOptions {
+    /**
+     * The PouchDB database instance to monitor for changes.
+     */
+    database: PouchDB.Database<object>;
+}
+export type ChangeManagerCallback<T extends object = object> = (change: PouchDB.Core.ChangesResponseChange<T>) => void | Promise<void>;
+/**
+ * Manages and dispatches changes from a PouchDB database to registered callbacks.
+ *
+ * @template T The type of documents stored in the PouchDB database.
+ */
+export declare class ChangeManager<T extends object = object> {
+    /**
+     * The PouchDB database instance being monitored.
+     */
+    _database: PouchDB.Database<T>;
+    /**
+     * Creates a new instance of the ChangeManager.
+     *
+     * @param options - Configuration options for the ChangeManager.
+     */
+    constructor(options: ChangeManagerOptions);
+    /**
+     * A list of registered callbacks wrapped in WeakRefs to avoid memory leaks.
+     */
+    _callbacks: FallbackWeakRef<ChangeManagerCallback<T>>[];
+    /**
+     * Registers a new callback to be invoked when a change occurs.
+     *
+     * @param callback - The callback function to register.
+     */
+    addCallback(callback: ChangeManagerCallback<T>): () => void;
+    removeCallback(callback: ChangeManagerCallback<T>): void;
+    /**
+     * The PouchDB changes feed instance, if active.
+     */
+    _changes?: PouchDB.Core.Changes<T>;
+    /**
+     * Handles a change event from the PouchDB changes feed.
+     *
+     * @param changeResponse - The change response object from the PouchDB changes feed.
+     */
+    _onChange(changeResponse: PouchDB.Core.ChangesResponseChange<T>): Promise<void>;
+    /**
+     * Sets up the PouchDB changes feed listener to monitor for database changes.
+     */
+    setupListener(): void;
+    /**
+     * Tears down the PouchDB changes feed listener and cleans up resources.
+     */
+    teardown(): void;
+    /**
+     * Restarts the PouchDB changes feed listener.
+     */
+    restartWatch(): void;
+}

package/dist/managers/ChangeManager.js

@@ -0,0 +1,104 @@
+import { LOG_LEVEL_VERBOSE, Logger } from "../common/logger.js";
+import { FallbackWeakRef } from "octagonal-wheels/common/polyfill";
+class ChangeManager {
+  /**
+   * The PouchDB database instance being monitored.
+   */
+  _database;
+  /**
+   * Creates a new instance of the ChangeManager.
+   *
+   * @param options - Configuration options for the ChangeManager.
+   */
+  constructor(options) {
+    this._database = options.database;
+    this.setupListener();
+  }
+  /**
+   * A list of registered callbacks wrapped in WeakRefs to avoid memory leaks.
+   */
+  _callbacks = [];
+  /**
+   * Registers a new callback to be invoked when a change occurs.
+   *
+   * @param callback - The callback function to register.
+   */
+  addCallback(callback) {
+    const callbackHandler = new FallbackWeakRef(callback);
+    this._callbacks.push(callbackHandler);
+    return () => {
+      this._callbacks = this._callbacks.filter((cb) => cb !== callbackHandler);
+    };
+  }
+  removeCallback(callback) {
+    this._callbacks = this._callbacks.filter((cb) => cb.deref() !== callback);
+  }
+  /**
+   * The PouchDB changes feed instance, if active.
+   */
+  _changes;
+  /**
+   * Handles a change event from the PouchDB changes feed.
+   *
+   * @param changeResponse - The change response object from the PouchDB changes feed.
+   */
+  async _onChange(changeResponse) {
+    if (!this._callbacks.length) {
+      return;
+    }
+    this._callbacks = this._callbacks.filter((callback) => callback.deref() !== void 0);
+    for (const callback of this._callbacks) {
+      try {
+        const cb = callback.deref();
+        if (!cb) {
+          continue;
+        }
+        await Promise.resolve(cb(changeResponse));
+      } catch (err) {
+        this._changes?.emit("error", err);
+      }
+    }
+  }
+  /**
+   * Sets up the PouchDB changes feed listener to monitor for database changes.
+   */
+  setupListener() {
+    if (this._changes) {
+      const changes2 = this._changes;
+      this._changes = void 0;
+      void changes2.removeAllListeners();
+      changes2.cancel();
+    }
+    const changes = this._database.changes({
+      since: "now",
+      live: true,
+      include_docs: true
+    });
+    void changes.on("change", (change) => {
+      void this._onChange(change);
+    });
+    void changes.on("error", (err) => {
+      Logger("ChangeManager Error watching changes");
+      Logger(err, LOG_LEVEL_VERBOSE);
+    });
+    this._changes = changes;
+  }
+  /**
+   * Tears down the PouchDB changes feed listener and cleans up resources.
+   */
+  teardown() {
+    void this._changes?.removeAllListeners();
+    this._changes?.cancel();
+    this._changes = void 0;
+  }
+  /**
+   * Restarts the PouchDB changes feed listener.
+   */
+  restartWatch() {
+    void this.teardown();
+    void this.setupListener();
+  }
+}
+export {
+  ChangeManager
+};

package/dist/managers/ChunkDeliveryCoordinator.d.ts

@@ -0,0 +1,51 @@
+import type { ReactiveSource } from "octagonal-wheels/dataobject/reactive";
+import type { DocumentID } from "../common/types.js";
+/**
+ * A last-resort leak fuse for an accepted delivery claim which reports no
+ * observable progress. It releases logical ownership so a waiter, and an
+ * entered bounded activity with its Wake Lock and indicator, cannot be retained
+ * forever by a stalled transport or never-settling Promise.
+ *
+ * Five minutes is a conservative operational ceiling, not a normal
+ * chunk-arrival budget, evidence of remote absence, or a transport deadline.
+ * The transport contract cannot yet abort the underlying request when it fires.
+ */
+export declare const DEFAULT_CHUNK_DELIVERY_STALL_TIMEOUT_MS: number;
+export type ActivityCountSource = Pick<ReactiveSource<number>, "value" | "onChanged" | "offChanged">;
+export type ChunkDeliveryClaimOptions = {
+    stallTimeoutMs?: number;
+    onStalled?: (ids: readonly DocumentID[]) => void;
+};
+export type ChunkDeliveryChangeListener = (ids?: readonly DocumentID[]) => void;
+/** A finite claim that keeps chunk arrival waiters paused until every owned identifier settles. */
+export interface ChunkDeliveryClaim {
+    readonly done: Promise<void>;
+    readonly pendingIds: readonly DocumentID[];
+    release(): void;
+    settle(id: DocumentID): void;
+    touch(): void;
+}
+/**
+ * Coordinates on-demand chunk ownership with broader finite remote activity.
+ *
+ * `ChunkFetcher` owns claims. `ArrivalWaitLayer` observes only whether an
+ * identifier may still be delivered, so it does not depend on a replicator
+ * service or on fetch scheduling details.
+ */
+export declare class ChunkDeliveryCoordinator {
+    private readonly finiteReplicationActivity?;
+    private readonly activeClaimCounts;
+    private readonly claimReleases;
+    private readonly listeners;
+    private finiteActivityWasActive;
+    private readonly finiteActivityChanged;
+    private disposed;
+    constructor(finiteReplicationActivity?: ActivityCountSource);
+    claim(ids: readonly DocumentID[], options?: ChunkDeliveryClaimOptions): ChunkDeliveryClaim;
+    isActivityActiveFor(id: DocumentID): boolean;
+    isClaimActiveFor(id: DocumentID): boolean;
+    isFiniteReplicationActive(): boolean;
+    onChanged(listener: ChunkDeliveryChangeListener): () => void;
+    dispose(): void;
+    private notifyChanged;
+}

package/dist/managers/ChunkDeliveryCoordinator.js

@@ -0,0 +1,136 @@
+import { promiseWithResolvers } from "octagonal-wheels/promises";
+import { compatGlobal } from "../common/coreEnvFunctions.js";
+const DEFAULT_CHUNK_DELIVERY_STALL_TIMEOUT_MS = 5 * 60 * 1e3;
+class ChunkDeliveryCoordinator {
+  constructor(finiteReplicationActivity) {
+    this.finiteReplicationActivity = finiteReplicationActivity;
+    this.finiteActivityWasActive = (finiteReplicationActivity?.value ?? 0) > 0;
+    this.finiteReplicationActivity?.onChanged(this.finiteActivityChanged);
+  }
+  finiteReplicationActivity;
+  activeClaimCounts = /* @__PURE__ */ new Map();
+  claimReleases = /* @__PURE__ */ new Set();
+  listeners = /* @__PURE__ */ new Set();
+  finiteActivityWasActive = false;
+  finiteActivityChanged = () => {
+    const active = (this.finiteReplicationActivity?.value ?? 0) > 0;
+    if (active === this.finiteActivityWasActive) return;
+    this.finiteActivityWasActive = active;
+    this.notifyChanged();
+  };
+  disposed = false;
+  claim(ids, options = {}) {
+    if (this.disposed) {
+      throw new Error("Cannot claim chunk delivery activity after the coordinator has been disposed.");
+    }
+    const pending = new Set(ids);
+    const resolver = promiseWithResolvers();
+    if (pending.size === 0) {
+      resolver.resolve();
+      return {
+        done: resolver.promise,
+        pendingIds: [],
+        release: () => void 0,
+        settle: () => void 0,
+        touch: () => void 0
+      };
+    }
+    const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_CHUNK_DELIVERY_STALL_TIMEOUT_MS;
+    let timer;
+    let released = false;
+    const clearTimer = () => {
+      if (timer === void 0) return;
+      compatGlobal.clearTimeout(timer);
+      timer = void 0;
+    };
+    const removeActiveIds = (activeIds) => {
+      for (const id of activeIds) {
+        const count = this.activeClaimCounts.get(id) ?? 0;
+        if (count <= 1) {
+          this.activeClaimCounts.delete(id);
+        } else {
+          this.activeClaimCounts.set(id, count - 1);
+        }
+      }
+    };
+    const release = () => {
+      if (released) return;
+      released = true;
+      clearTimer();
+      const activeIds = [...pending];
+      pending.clear();
+      removeActiveIds(activeIds);
+      this.claimReleases.delete(release);
+      resolver.resolve();
+      if (activeIds.length > 0) {
+        this.notifyChanged(activeIds);
+      }
+    };
+    const armStallTimer = () => {
+      clearTimer();
+      if (released || pending.size === 0 || stallTimeoutMs <= 0) return;
+      timer = compatGlobal.setTimeout(() => {
+        timer = void 0;
+        const stalledIds = [...pending];
+        release();
+        options.onStalled?.(stalledIds);
+      }, stallTimeoutMs);
+    };
+    const settle = (id) => {
+      if (released || !pending.delete(id)) return;
+      removeActiveIds([id]);
+      this.notifyChanged([id]);
+      if (pending.size === 0) {
+        release();
+      } else {
+        armStallTimer();
+      }
+    };
+    for (const id of pending) {
+      this.activeClaimCounts.set(id, (this.activeClaimCounts.get(id) ?? 0) + 1);
+    }
+    this.claimReleases.add(release);
+    this.notifyChanged([...pending]);
+    armStallTimer();
+    return {
+      done: resolver.promise,
+      get pendingIds() {
+        return [...pending];
+      },
+      release,
+      settle,
+      touch: armStallTimer
+    };
+  }
+  isActivityActiveFor(id) {
+    return this.isClaimActiveFor(id) || this.isFiniteReplicationActive();
+  }
+  isClaimActiveFor(id) {
+    return this.activeClaimCounts.has(id);
+  }
+  isFiniteReplicationActive() {
+    return (this.finiteReplicationActivity?.value ?? 0) > 0;
+  }
+  onChanged(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.finiteReplicationActivity?.offChanged(this.finiteActivityChanged);
+    for (const release of [...this.claimReleases]) {
+      release();
+    }
+    this.listeners.clear();
+  }
+  notifyChanged(ids) {
+    for (const listener of this.listeners) {
+      listener(ids);
+    }
+  }
+}
+export {
+  ChunkDeliveryCoordinator,
+  DEFAULT_CHUNK_DELIVERY_STALL_TIMEOUT_MS
+};