@vrtmrz/livesync-commonlib 0.3.0 → 0.3.2

package/dist/platform/node/storage.js

@@ -59,15 +59,61 @@ class NodeStorageAdapter {
       return null;
     }
   }
+  /** Read metadata for an exact physical path, returning null only when it is absent. */
+  async statResolved(path) {
+    let stat;
+    try {
+      stat = await nodeFsPromises.stat(await this.resolvePath(path));
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    return {
+      size: stat.size,
+      mtime: Math.floor(stat.mtimeMs),
+      ctime: getNodeFileCreationTime(stat),
+      type: stat.isDirectory() ? "folder" : "file"
+    };
+  }
+  /** Enumerate immediate physical children, returning null only when the directory is absent. */
+  async readDirectory(path) {
+    let entries;
+    try {
+      entries = await nodeFsPromises.readdir(await this.resolvePath(path), { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    const directoryEntries = [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) directoryEntries.push({ name: entry.name, kind: "directory" });
+      else if (entry.isFile()) directoryEntries.push({ name: entry.name, kind: "file" });
+    }
+    return directoryEntries;
+  }
   async stat(path) {
     return await this.trystat(path);
   }
   async mkdir(path) {
+    await this.mkdirPath(path);
+  }
+  /** Create an exact resolved directory path. */
+  async mkdirResolved(path) {
+    await this.mkdirPath(path);
+  }
+  async mkdirPath(path) {
     const fullPath = await this.resolvePath(path);
     await nodeFsPromises.mkdir(fullPath, { recursive: true });
     await this.assertNoSymbolicLinks(fullPath);
   }
   async remove(path) {
+    await this.removePath(path);
+  }
+  /** Remove an exact resolved file or directory path. */
+  async removeResolved(path) {
+    await this.removePath(path);
+  }
+  async removePath(path) {
     const fullPath = await this.resolvePath(path, false);
     const stat = await nodeFsPromises.stat(fullPath);
     if (stat.isDirectory()) {
@@ -77,6 +123,13 @@ class NodeStorageAdapter {
     }
   }
   async read(path) {
+    return await this.readPath(path);
+  }
+  /** Read a file by its exact resolved physical path. */
+  async readResolved(path) {
+    return await this.readPath(path);
+  }
+  async readPath(path) {
     const handle = await nodeFsPromises.open(
       await this.resolvePath(path, false),
       nodeFsConstants.O_RDONLY | NO_FOLLOW
@@ -88,6 +141,13 @@ class NodeStorageAdapter {
     }
   }
   async readBinary(path) {
+    return await this.readBinaryPath(path);
+  }
+  /** Read bytes by their exact resolved physical path. */
+  async readBinaryResolved(path) {
+    return await this.readBinaryPath(path);
+  }
+  async readBinaryPath(path) {
     const handle = await nodeFsPromises.open(
       await this.resolvePath(path, false),
       nodeFsConstants.O_RDONLY | NO_FOLLOW
@@ -100,22 +160,50 @@ class NodeStorageAdapter {
     }
   }
   async write(path, data, options) {
+    await this.writePath(path, data, options);
+  }
+  /** Write text to an exact resolved physical path. */
+  async writeResolved(path, data, options) {
+    await this.writePath(path, data, options);
+  }
+  async writePath(path, data, options) {
     const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
     await this.writeFile(fullPath, data, options, false);
   }
   async writeBinary(path, data, options) {
+    await this.writeBinaryPath(path, data, options);
+  }
+  /** Write bytes to an exact resolved physical path. */
+  async writeBinaryResolved(path, data, options) {
+    await this.writeBinaryPath(path, data, options);
+  }
+  async writeBinaryPath(path, data, options) {
     const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
     await this.writeFile(fullPath, new Uint8Array(data), options, false);
   }
   async append(path, data, options) {
+    await this.appendPath(path, data, options);
+  }
+  /** Append text to an exact resolved physical path. */
+  async appendResolved(path, data, options) {
+    await this.appendPath(path, data, options);
+  }
+  async appendPath(path, data, options) {
     const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
     await this.writeFile(fullPath, data, options, true);
   }
   /** Atomically rename or move an entry without leaving the injected root. */
   async rename(sourcePath, targetPath) {
+    await this.renamePath(sourcePath, targetPath);
+  }
+  /** Rename or move exact resolved physical paths without leaving the injected root. */
+  async renameResolved(sourcePath, targetPath) {
+    await this.renamePath(sourcePath, targetPath);
+  }
+  async renamePath(sourcePath, targetPath) {
     const fullSourcePath = await this.resolvePath(sourcePath, false);
     const fullTargetPath = await this.resolvePath(targetPath, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullTargetPath), { recursive: true });

package/dist/platform/pathComparison.d.ts

@@ -0,0 +1,53 @@
+import type { DocumentPath, DocumentPathParts, FilePath, PathComparisonKey, PathComparisonSettings } from "./pathTypes.js";
+/**
+ * Validate raw storage input without changing its spelling.
+ *
+ * @param path - A slash-separated path relative to the host-selected root.
+ * @returns The original path branded as `FilePath`; the empty path denotes the root.
+ * @throws Rejects absolute, drive-qualified, backslash, and traversal-segment input.
+ * @remarks Does not normalise Unicode, resolve physical names, or check existence.
+ */
+export declare function parseFilePath(path: string): FilePath;
+/**
+ * Mark an original document path before routing its Metadata namespace.
+ *
+ * @param path - Original document-path text, optionally including one namespace.
+ * @returns The same text branded as `DocumentPath`.
+ * @throws Rejects a non-string value.
+ * @remarks Storage validation follows namespace routing. This function does not
+ * recover original spelling from a comparison key or validate a physical path.
+ */
+export declare function parseDocumentPath(path: string): DocumentPath;
+/**
+ * Split one recognised Metadata namespace from an original document path.
+ *
+ * @param path - Original document path; a further colon remains in the file path.
+ * @returns The namespace, or an empty prefix, and the original remaining spelling.
+ * @remarks Does not validate the resulting file path for storage access.
+ */
+export declare function splitDocumentPath(path: DocumentPath): DocumentPathParts;
+/**
+ * Join a routed namespace and its original file path without normalising either.
+ *
+ * @param parts - One recognised namespace and an original file path.
+ * @returns Their concatenation as an original document path.
+ */
+export declare function joinDocumentPath({ prefix, path }: DocumentPathParts): DocumentPath;
+/**
+ * Derive an identity key for a file path within one storage root.
+ *
+ * @param path - Original file path without a Metadata namespace.
+ * @param settings - Explicit Unicode and case comparison settings.
+ * @returns A storage-domain comparison key; retain the original path for I/O.
+ * @throws Rejects an unsupported path normalisation version.
+ */
+export declare function getStoragePathComparisonKey(path: FilePath, settings: PathComparisonSettings): PathComparisonKey<"storage">;
+/**
+ * Derive a document identity key while preserving its Metadata namespace.
+ *
+ * @param path - Original document path, optionally including one namespace.
+ * @param settings - Explicit Unicode and case comparison settings for the body.
+ * @returns A document-domain key which distinguishes namespaces with equal bodies.
+ * @throws Rejects an unsupported path normalisation version.
+ */
+export declare function getDocumentPathComparisonKey(path: DocumentPath, settings: PathComparisonSettings): PathComparisonKey<"document">;

package/dist/platform/pathComparison.js

@@ -0,0 +1,39 @@
+import { normalisePathForIdentity } from "../common/pathNormalization.js";
+import { splitPathNamespace } from "../common/pathNamespace.js";
+import { validateStoragePath } from "./storagePath.js";
+function parseFilePath(path) {
+  return validateStoragePath(path);
+}
+function parseDocumentPath(path) {
+  if (typeof path !== "string") throw new TypeError("A document path must be a string");
+  return path;
+}
+function splitDocumentPath(path) {
+  const [prefix, body] = splitPathNamespace(path);
+  return { prefix, path: body };
+}
+function joinDocumentPath({ prefix, path }) {
+  return prefix + path;
+}
+function normaliseFilePath(path) {
+  return normalisePathForIdentity(path, 1);
+}
+function comparisonPath(path, settings) {
+  const normalised = settings.pathNormalizationVersion === 1 ? normaliseFilePath(path) : normalisePathForIdentity(path, settings.pathNormalizationVersion);
+  return settings.handleFilenameCaseSensitive ? normalised : normalised.toLowerCase();
+}
+function getStoragePathComparisonKey(path, settings) {
+  return comparisonPath(path, settings);
+}
+function getDocumentPathComparisonKey(path, settings) {
+  const { prefix, path: body } = splitDocumentPath(path);
+  return prefix + comparisonPath(body, settings);
+}
+export {
+  getDocumentPathComparisonKey,
+  getStoragePathComparisonKey,
+  joinDocumentPath,
+  parseDocumentPath,
+  parseFilePath,
+  splitDocumentPath
+};

package/dist/platform/pathTypes.d.ts

@@ -0,0 +1,154 @@
+import type { TaggedType } from "octagonal-wheels/common/types";
+import type { FilePath, FilePathWithPrefix, FilePathWithPrefixLC } from "../common/models/db.type.js";
+import type { PathNormalizationVersion } from "../common/models/setting.type.js";
+import type { PathNamespace } from "../common/pathNamespace.js";
+/**
+ * An original file path without a Metadata namespace.
+ *
+ * @remarks
+ * This compatibility type does not establish NFC form, physical spelling, or
+ * existence. Validate raw storage input with `parseFilePath`.
+ */
+export type { FilePath };
+/**
+ * An original document path with an optional recognised Metadata namespace.
+ *
+ * @remarks
+ * Excludes the legacy comparison-key variant. Route the namespace before
+ * validating the remaining file path for storage access.
+ */
+export type DocumentPath = Exclude<FilePathWithPrefix, FilePathWithPrefixLC>;
+declare const unicodeForm: unique symbol;
+declare const storagePath: unique symbol;
+/**
+ * A file path in Unicode NFC form, without case conversion.
+ *
+ * @remarks
+ * NFC form alone does not establish physical storage spelling or existence.
+ * This refinement is used within normalisation helpers and is not re-exported
+ * by the focused storage entry point.
+ */
+export type NfcFilePath = FilePath & {
+    readonly [unicodeForm]: "NFC";
+};
+/**
+ * A root-relative storage target whose existing components use resolved spelling.
+ *
+ * @remarks
+ * Produced by resolution or supported physical enumeration. A write target may
+ * contain missing components; this type does not guarantee existence, entry
+ * kind, or protection against concurrent changes. The empty path denotes the
+ * root, subject to each operation's root rules.
+ */
+export type StoragePath = FilePath & {
+    readonly [storagePath]: true;
+};
+/**
+ * A path identity key produced by the configured Unicode and case comparison.
+ *
+ * @typeParam Domain - `storage` compares within one storage root; `document`
+ * retains the Metadata namespace so different document kinds remain distinct.
+ *
+ * @remarks
+ * Retain the original path separately. A comparison key cannot establish an
+ * original filename and must not be passed to storage or namespace operations.
+ */
+export type PathComparisonKey<Domain extends "storage" | "document"> = TaggedType<string, `PathComparisonKey:${Domain}`>;
+/** Unicode and case settings used to derive path comparison keys. */
+export type PathComparisonSettings = Readonly<{
+    /** `0` retains Legacy Unicode handling; `1` compares Unicode NFC forms. */
+    pathNormalizationVersion: PathNormalizationVersion;
+    /** Preserve letter case when true; otherwise apply the existing `toLowerCase()` rule. */
+    handleFilenameCaseSensitive: boolean;
+}>;
+/** The namespace and original file path obtained by splitting one document path. */
+export type DocumentPathParts = Readonly<{
+    /** One recognised Metadata namespace, or the empty string for an ordinary file. */
+    prefix: PathNamespace;
+    /** Original spelling after removing that one namespace. */
+    path: FilePath;
+}>;
+/** One immediate physical child returned by a strict directory reader. */
+export type DirectoryEntry = Readonly<{
+    /** Unmodified child name, rather than a relative path containing multiple components. */
+    name: string;
+    /** Entry kind reported by the storage host. */
+    kind: "file" | "directory";
+}>;
+/** A physical child path and its kind, ready for a storage scan to consume. */
+export type StorageEntry = Readonly<{
+    /** Root-relative path retaining the directory listing's actual spelling. */
+    path: StoragePath;
+    /** Entry kind from the same directory listing. */
+    kind: DirectoryEntry["kind"];
+}>;
+/**
+ * Read a directory's complete immediate children using actual names and kinds.
+ *
+ * @param physicalDirectory - Resolved directory path relative to the host's root.
+ * @returns The children, including an empty array for an empty directory, or
+ * `null` only when the directory is absent.
+ * @throws Propagates permission, non-directory, and other I/O failures instead
+ * of reporting absence or a successful partial listing.
+ */
+export type ReadDirectory = (physicalDirectory: StoragePath) => Promise<readonly DirectoryEntry[] | null>;
+/** Resolved paths for a rename which the storage host has yet to perform. */
+export type ResolvedRename = Readonly<{
+    /** Existing source spelling. */
+    source: StoragePath;
+    /** Resolved target, retaining a requested leaf spelling change where applicable. */
+    target: StoragePath;
+}>;
+/**
+ * Resolve NFC-equivalent names through strict directory reads under one policy.
+ *
+ * @remarks
+ * Operations reject ambiguous candidates even when an exact spelling exists,
+ * propagate reader failures, and perform no filesystem mutation. Resolution
+ * does not reserve a path against concurrent changes; hosts own that lifecycle.
+ */
+export interface StoragePathResolver {
+    /**
+     * Resolve an existing file or directory using its physical spelling.
+     *
+     * @param path - Original path relative to the selected storage root.
+     * @returns The resolved path, or `null` when a component is absent.
+     */
+    resolveExisting(path: FilePath): Promise<StoragePath | null>;
+    /**
+     * Resolve a write target while preserving any missing suffix as requested.
+     *
+     * @param path - Original target path relative to the selected storage root.
+     * @returns The resolved target; this operation creates no missing entries.
+     */
+    resolveForWrite(path: FilePath): Promise<StoragePath>;
+    /**
+     * Resolve both sides of an explicit rename, including a leaf spelling change.
+     *
+     * @param source - Original source entry path; the root is not an entry.
+     * @param target - Requested target entry path; the root is not an entry.
+     * @returns Both paths, or `null` when the source is absent. The host retains
+     * responsibility for performing the rename and handling replacement.
+     */
+    resolveRename(source: FilePath, target: FilePath): Promise<ResolvedRename | null>;
+    /**
+     * Enumerate an already resolved directory without resolving each child again.
+     *
+     * @param path - Physical directory path relative to the selected root.
+     * @returns Child paths and kinds, or `null` when the directory is absent.
+     * @throws Rejects equivalent child names as ambiguous before returning a listing.
+     */
+    listResolvedDirectory(path: StoragePath): Promise<readonly StorageEntry[] | null>;
+}
+/** Dependencies and comparison policy for constructing an NFC path resolver. */
+export type StoragePathResolverOptions = Readonly<{
+    /** Strict host enumeration; it must distinguish absence from I/O failure. */
+    readDirectory: ReadDirectory;
+    /** Policy copied at construction; construct a new resolver when settings change. */
+    policy: Readonly<{
+        /** The shared resolver accepts NFC mode only; Legacy hosts retain their existing paths. */
+        pathNormalizationVersion: 1;
+        /** Preserve letter case when true; otherwise compare using `toLowerCase()`. */
+        handleFilenameCaseSensitive: boolean;
+    }>;
+}>;

package/dist/platform/storagePathResolution.d.ts

@@ -0,0 +1,13 @@
+import type { StoragePathResolver as ResolverContract, StoragePathResolverOptions } from "./pathTypes.js";
+export type { DirectoryEntry, ReadDirectory, ResolvedRename, StorageEntry, StoragePathResolver, StoragePathResolverOptions, } from "./pathTypes.js";
+export { AmbiguousNormalisedPathError } from "./AmbiguousNormalisedPathError.js";
+/**
+ * Bind strict directory reads to a copied NFC resolution policy.
+ *
+ * @param options - Host enumeration and explicit NFC/case settings.
+ * @returns A resolver which reads current listings without retaining a directory cache.
+ * @throws Rejects a path version other than `1` or a non-boolean case setting.
+ * @remarks Construction performs no I/O. Resolution performs no mutation or
+ * atomic reservation; construct a new resolver when its comparison settings change.
+ */
+export declare function createStoragePathResolver(options: StoragePathResolverOptions): ResolverContract;

package/dist/platform/storagePathResolution.js

@@ -0,0 +1,9 @@
+import { StoragePathResolver } from "./StoragePathResolver.js";
+import { AmbiguousNormalisedPathError } from "./AmbiguousNormalisedPathError.js";
+function createStoragePathResolver(options) {
+  return new StoragePathResolver(options);
+}
+export {
+  AmbiguousNormalisedPathError,
+  createStoragePathResolver
+};

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/couchdb/LiveSyncReplicator.js

@@ -169,7 +169,8 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       value.enableCompression,
       value.pathNormalizationVersion,
       value.readChunksOnline,
-      value.useRequestAPI
+      value.useRequestAPI,
+      value.useCouchDBCacheControlHeadersOnly === true
     ]);
     const binding = identity(snapshot);
     let connection;
@@ -721,7 +722,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         if (cancellationRequested()) {
           return false;
         }
-        if (await this.ensurePBKDF2Salt(setting, showResult, !retrying) === false || cancellationRequested()) {
+        if (await this.ensurePBKDF2Salt(setting, showResult, false) === false || cancellationRequested()) {
           return false;
         }
         if (this.controller) {
@@ -1442,7 +1443,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       {
         ...connectionOptions,
         encryptionAlgorithm: settings.E2EEAlgorithm,
-        encryptInternalMetadata: usesEncryptedInternalMetadata(settings)
+        encryptInternalMetadata: usesEncryptedInternalMetadata(settings),
+        useCouchDBCacheControlHeadersOnly: settings.useCouchDBCacheControlHeadersOnly === true
       }
     );
   }

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
+};

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

@@ -1,10 +1,10 @@
 import { type EntryDoc, type SyncParameters, type BucketSyncSetting, type RemoteDBSettings } from "../../common/types.js";
 import type { ReplicationCallback, ReplicationStat } from "../LiveSyncAbstractReplicator.js";
 import { type SimpleStore } from "../../common/utils.js";
-import { type CheckPointInfo } from "./JournalSyncTypes.js";
+import { type CheckPointInfo, type StoppedJournal } from "./JournalSyncTypes.js";
 import type { LiveSyncJournalReplicatorEnv } from "./LiveSyncJournalReplicatorEnv.js";
 import { type IJournalStorage, type JournalStorageConditionalWriteResult, type JournalStorageReadResult } from "./objectstore/JournalStorageAdapter.js";
-type ProcessingEntry = PouchDB.Core.PutDocument<EntryDoc> & PouchDB.Core.GetMeta;
+import { type ProcessingEntry } from "./journalRecords.js";
 export declare class JournalSyncCore {
     _settings: BucketSyncSetting;
     storage: IJournalStorage;
@@ -17,6 +17,19 @@ export declare class JournalSyncCore {
     store: SimpleStore<CheckPointInfo>;
     requestedStop: boolean;
     private syncParamsHandler?;
+    private receiveTask?;
+    private stoppedJournal?;
+    private checkpointGeneration;
+    private receiveConfiguration;
+    private matchesStoppedContext;
+    /** Return the current failure for presentation before an explicit single-Journal skip. */
+    getStoppedJournal(): StoppedJournal | undefined;
+    /**
+     * Acknowledge only the exact failure presented to the user, then resume receipt.
+     * Stale snapshots, another active receive, and a later Stop request are rejected.
+     * Any subsequent Journal failure stops the resumed operation normally.
+     */
+    skipStoppedJournalAndResume(stopped: StoppedJournal, showMessage?: boolean): Promise<boolean>;
     getInitialSyncParameters(): Promise<SyncParameters>;
     getSyncParameters(): Promise<SyncParameters>;
     putSyncParameters(params: SyncParameters): Promise<boolean>;
@@ -65,13 +78,19 @@ export declare class JournalSyncCore {
     hasRemoteJournals(): Promise<boolean>;
     _getRemoteJournals(): Promise<string[]>;
     processDocuments(allDocs: ProcessingEntry[]): Promise<boolean>;
+    private processDocumentsForReceive;
     private _createReceiveReadableStream;
     private _createReceiveTransformStream;
     private _createReceiveWritableStream;
+    /** Receive until completion, a failure, or an explicit Stop request. */
     receiveRemoteJournal(showMessage?: boolean): Promise<boolean>;
+    private startReceive;
+    private prepareStoppedJournalSkip;
+    private recordReceiveFailure;
+    private receiveJournalFiles;
+    private performReceive;
     sync(showResult?: boolean): Promise<boolean>;
     requestStop(): void;
     /** Stop this Journal operation owner and release its storage transport. */
     dispose(): void;
 }
-export {};