@vrtmrz/livesync-commonlib 0.2.3 → 0.3.1

package/dist/platform/node/UnicodeResolvingNodeStorageAdapter.js

@@ -0,0 +1,218 @@
+import { getPathNormalizationVersion as getSupportedPathNormalizationVersion } from "../../common/pathNormalization.js";
+import { createStoragePathResolver } from "../storagePathResolution.js";
+import { parseFilePath } from "../pathComparison.js";
+import { NodeStorageAdapter } from "./storage.js";
+class UnicodeResolvingNodeStorageAdapter extends NodeStorageAdapter {
+  /**
+   * Bind a host-owned root and callbacks for each operation's comparison settings.
+   *
+   * @param rootPath - Host-selected storage directory.
+   * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+   * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+   */
+  constructor(rootPath, getPathNormalizationVersion = () => 0, isCaseInsensitive = () => false) {
+    super(rootPath);
+    this.getPathNormalizationVersion = getPathNormalizationVersion;
+    this.isCaseInsensitive = isCaseInsensitive;
+  }
+  getPathNormalizationVersion;
+  isCaseInsensitive;
+  /** Whether the current settings select NFC path resolution. */
+  get isUnicodePathNormalizationEnabled() {
+    return this.getPathNormalizationVersionSnapshot() === 1;
+  }
+  /** Read metadata for an entry already resolved or obtained from a storage listing. */
+  async statExact(path) {
+    const settings = this.getSettings();
+    if (settings.pathNormalizationVersion === 0) return await super.trystat(path);
+    return await super.statResolved(this.asStoragePath(path));
+  }
+  /** Inspect a physical directory once before descending into its enumerated entries. */
+  async listExact(path) {
+    const settings = this.getSettings();
+    if (settings.pathNormalizationVersion === 0) {
+      const entries = await super.list(path);
+      return {
+        files: entries.files.map((entry) => this.asStoragePath(entry)),
+        folders: entries.folders.map((entry) => this.asStoragePath(entry))
+      };
+    }
+    return await this.listPhysicalDirectory(this.asStoragePath(path), settings);
+  }
+  /**
+   * Resolve a logical path under one snapshot of the current settings.
+   *
+   * @param path - Original root-relative file path.
+   * @param caseInsensitive - Override this lookup's case rule without changing settings.
+   * @param allowMissing - Keep a missing write suffix when true; defaults to true.
+   * @returns The physical target, or `null` for an absent path when `allowMissing`
+   * is false in NFC mode. Legacy mode returns the validated original path.
+   * @throws Propagates NFC ambiguity and reader failures, and rejects invalid input.
+   */
+  async resolveLogicalPath(path, caseInsensitive, allowMissing = true) {
+    const settings = this.getSettings(caseInsensitive);
+    const filePath = parseFilePath(path);
+    if (settings.pathNormalizationVersion === 0) return filePath;
+    await this.preflightRequestedPath(filePath);
+    const resolver = this.createResolver(settings);
+    return allowMissing ? await resolver.resolveForWrite(filePath) : await resolver.resolveExisting(filePath);
+  }
+  /** Check whether the logical path exists under the current Unicode policy. */
+  async exists(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.exists(path);
+    await this.preflightRequestedPath(path);
+    const resolver = this.createResolver(settings);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) return false;
+    return await super.statResolved(resolvedPath) !== null;
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async trystat(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    return await this.statWithSettings(path, settings);
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async stat(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    return await this.statWithSettings(path, settings);
+  }
+  /** Create a directory at the resolved write target. */
+  async mkdir(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.mkdir(path);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.mkdirResolved(resolvedPath);
+  }
+  /** Remove the entry at its resolved physical path. */
+  async remove(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.remove(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    await super.removeResolved(resolvedPath);
+  }
+  /** Read text from the resolved physical file. */
+  async read(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.read(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    return await super.readResolved(resolvedPath);
+  }
+  /** Read bytes from the resolved physical file. */
+  async readBinary(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.readBinary(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    return await super.readBinaryResolved(resolvedPath);
+  }
+  /** Write text at the resolved target while retaining existing physical spelling. */
+  async write(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.write(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.writeResolved(resolvedPath, data, options);
+  }
+  /** Write bytes at the resolved target while retaining existing physical spelling. */
+  async writeBinary(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.writeBinary(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.writeBinaryResolved(resolvedPath, data, options);
+  }
+  /** Append text at the resolved target using the host adapter semantics. */
+  async append(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.append(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.appendResolved(resolvedPath, data, options);
+  }
+  /** Resolve and perform an explicit rename, including a requested leaf spelling change. */
+  async rename(sourcePath, targetPath, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.rename(sourcePath, targetPath);
+    await this.preflightRequestedPath(sourcePath, false);
+    await this.preflightRequestedPath(targetPath, false);
+    const resolver = this.createResolver(settings);
+    const resolved = await resolver.resolveRename(parseFilePath(sourcePath), parseFilePath(targetPath));
+    if (resolved === null) throw this.missingPathError(sourcePath);
+    await super.renameResolved(resolved.source, resolved.target);
+  }
+  /** List logical directory contents, checking equivalent child names in NFC mode. */
+  async list(basePath, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.list(basePath);
+    await this.preflightRequestedPath(basePath);
+    const resolver = this.createResolver(settings);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(basePath));
+    if (resolvedPath === null) return { files: [], folders: [] };
+    return await this.listPhysicalDirectory(resolvedPath, settings, resolver);
+  }
+  async statWithSettings(path, settings) {
+    if (settings.pathNormalizationVersion === 0) return await super.trystat(path);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) return null;
+    return await super.statResolved(resolvedPath);
+  }
+  async requireExistingPath(path, resolver) {
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) throw this.missingPathError(path);
+    return resolvedPath;
+  }
+  async preflightRequestedPath(path, allowRoot = true) {
+    try {
+      await this.resolvePath(path, allowRoot);
+    } catch (error) {
+      if (error.code === "ENOTDIR") return;
+      throw error;
+    }
+  }
+  async listPhysicalDirectory(path, settings, resolver = this.createResolver(settings)) {
+    const entries = await resolver.listResolvedDirectory(path);
+    const files = [];
+    const folders = [];
+    for (const entry of entries ?? []) {
+      if (entry.kind === "directory") folders.push(entry.path);
+      else files.push(entry.path);
+    }
+    return { files, folders };
+  }
+  createResolver(settings) {
+    return createStoragePathResolver({
+      readDirectory: async (path) => await super.readDirectory(path),
+      policy: {
+        pathNormalizationVersion: 1,
+        handleFilenameCaseSensitive: !settings.caseInsensitive
+      }
+    });
+  }
+  getSettings(caseInsensitive) {
+    const pathNormalizationVersion = this.getPathNormalizationVersionSnapshot();
+    return {
+      pathNormalizationVersion,
+      caseInsensitive: caseInsensitive ?? this.isCaseInsensitive()
+    };
+  }
+  getPathNormalizationVersionSnapshot() {
+    return getSupportedPathNormalizationVersion({
+      pathNormalizationVersion: this.getPathNormalizationVersion()
+    });
+  }
+  asStoragePath(path) {
+    return parseFilePath(path);
+  }
+  missingPathError(path) {
+    const error = new Error("ENOENT: no such file or directory, " + path);
+    error.code = "ENOENT";
+    error.path = path;
+    return error;
+  }
+}
+export {
+  UnicodeResolvingNodeStorageAdapter
+};

package/dist/platform/node/index.d.ts

@@ -20,5 +20,6 @@ export declare const readline: typeof nodeReadlinePromises;
 export declare const builtinModules: readonly string[];
 /** Returns whether a module specifier refers to a Node built-in. */
 export declare const isBuiltin: typeof nodeIsBuiltin;
+export { UnicodeResolvingNodeStorageAdapter } from "./UnicodeResolvingNodeStorageAdapter.js";
 export { NodeStorageAdapter, createNodeStorage, getNodeFileCreationTime, validateStoragePath, type CreateNodeStorageOptions, type NodeStorageStat, } from "./storage.js";
 export { createNodeStandardIo, type CreateNodeStandardIoOptions, type NodeStandardInput, type NodeStandardOutput, } from "./standardIo.js";

package/dist/platform/node/index.js

@@ -12,6 +12,7 @@ const os = nodeOs;
 const readline = nodeReadlinePromises;
 const builtinModules = nodeBuiltinModules;
 const isBuiltin = nodeIsBuiltin;
+import { UnicodeResolvingNodeStorageAdapter } from "./UnicodeResolvingNodeStorageAdapter.js";
 import {
   NodeStorageAdapter,
   createNodeStorage,
@@ -23,6 +24,7 @@ import {
 } from "./standardIo.js";
 export {
   NodeStorageAdapter,
+  UnicodeResolvingNodeStorageAdapter,
   builtinModules,
   createNodeStandardIo,
   createNodeStorage,

package/dist/platform/node/storage.d.ts

@@ -1,6 +1,7 @@
 import type { Stats } from "node:fs";
 import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
+import type { DirectoryEntry, StoragePath } from "../pathTypes.js";
 export type NodeStorageStat = UXStat;
 /** Read creation time in integer milliseconds, using change time when birth time is unavailable. */
 export declare function getNodeFileCreationTime(stat: Pick<Stats, "birthtimeMs" | "ctimeMs">): number;
@@ -17,20 +18,48 @@ export interface CreateNodeStorageOptions {
 export declare class NodeStorageAdapter implements IStorageAdapter<NodeStorageStat> {
     private readonly rootPath;
     constructor(rootPath: string);
-    private resolvePath;
+    protected resolvePath(path: string, allowRoot?: boolean): Promise<string>;
     private assertNoSymbolicLinks;
     exists(path: string): Promise<boolean>;
     trystat(path: string): Promise<NodeStorageStat | null>;
+    /** Read metadata for an exact physical path, returning null only when it is absent. */
+    statResolved(path: StoragePath): Promise<NodeStorageStat | null>;
+    /** Enumerate immediate physical children, returning null only when the directory is absent. */
+    readDirectory(path: StoragePath): Promise<readonly DirectoryEntry[] | null>;
     stat(path: string): Promise<NodeStorageStat | null>;
     mkdir(path: string): Promise<void>;
+    /** Create an exact resolved directory path. */
+    mkdirResolved(path: StoragePath): Promise<void>;
+    private mkdirPath;
     remove(path: string): Promise<void>;
+    /** Remove an exact resolved file or directory path. */
+    removeResolved(path: StoragePath): Promise<void>;
+    private removePath;
     read(path: string): Promise<string>;
+    /** Read a file by its exact resolved physical path. */
+    readResolved(path: StoragePath): Promise<string>;
+    private readPath;
     readBinary(path: string): Promise<ArrayBuffer>;
+    /** Read bytes by their exact resolved physical path. */
+    readBinaryResolved(path: StoragePath): Promise<ArrayBuffer>;
+    private readBinaryPath;
     write(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Write text to an exact resolved physical path. */
+    writeResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    private writePath;
     writeBinary(path: string, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
+    /** Write bytes to an exact resolved physical path. */
+    writeBinaryResolved(path: StoragePath, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
+    private writeBinaryPath;
     append(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Append text to an exact resolved physical path. */
+    appendResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    private appendPath;
     /** Atomically rename or move an entry without leaving the injected root. */
     rename(sourcePath: string, targetPath: string): Promise<void>;
+    /** Rename or move exact resolved physical paths without leaving the injected root. */
+    renameResolved(sourcePath: StoragePath, targetPath: StoragePath): Promise<void>;
+    private renamePath;
     list(basePath: string): Promise<{
         files: string[];
         folders: string[];

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