@vrtmrz/livesync-commonlib 0.2.3 → 0.3.1

package/dist/platform/browser/UnicodeResolvingFileSystemAccessStorageAdapter.js

@@ -0,0 +1,169 @@
+import { getPathNormalizationVersion } from "../../common/pathNormalization.js";
+import { parseFilePath } from "../pathComparison.js";
+import { createStoragePathResolver } from "../storagePathResolution.js";
+import { FileSystemAccessStorageAdapter } from "./storage.js";
+class UnicodeResolvingFileSystemAccessStorageAdapter {
+  /**
+   * Bind a host-owned root and callbacks for each operation's comparison settings.
+   *
+   * @param rootHandle - Host-selected directory handle with the required permissions.
+   * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+   * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+   */
+  constructor(rootHandle, getPathNormalizationVersion2 = () => 0, isCaseInsensitive = () => false) {
+    this.getPathNormalizationVersion = getPathNormalizationVersion2;
+    this.isCaseInsensitive = isCaseInsensitive;
+    this.storage = new FileSystemAccessStorageAdapter(rootHandle);
+  }
+  getPathNormalizationVersion;
+  isCaseInsensitive;
+  storage;
+  /** Whether the current settings select NFC path resolution. */
+  get isUnicodePathNormalizationEnabled() {
+    return this.snapshotPolicy().pathNormalizationVersion === 1;
+  }
+  /**
+   * 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 policy = this.snapshotPolicy(caseInsensitive);
+    const logicalPath = parseFilePath(path);
+    if (policy.pathNormalizationVersion === 0) return logicalPath;
+    const resolver = this.createResolver(policy);
+    return allowMissing ? await resolver.resolveForWrite(logicalPath) : await resolver.resolveExisting(logicalPath);
+  }
+  /** Read metadata for a physical path without performing another logical lookup. */
+  async statExact(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.trystat(path);
+    return await this.storage.statResolved(path);
+  }
+  /** List a physical directory, rejecting equivalent child names in NFC mode. */
+  async listExact(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.list(path);
+    const entries = await this.createResolver(policy).listResolvedDirectory(path);
+    return this.groupStorageEntries(entries ?? []);
+  }
+  /** Check whether the logical path exists under the current Unicode policy. */
+  async exists(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.exists(path);
+    return await this.createResolver(policy).resolveExisting(parseFilePath(path)) !== null;
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async trystat(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.trystat(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    return resolved === null ? null : await this.storage.statResolved(resolved);
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async stat(path) {
+    return await this.trystat(path);
+  }
+  /** Create a directory at the resolved write target. */
+  async mkdir(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.mkdir(path);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.mkdirResolved(resolved);
+  }
+  /** Remove the entry at its resolved physical path. */
+  async remove(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.remove(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved !== null) await this.storage.removeResolved(resolved);
+  }
+  /** Read text from the resolved physical file. */
+  async read(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.read(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved === null) throw new Error(`File not found: ${path}`);
+    return await this.storage.readResolved(resolved);
+  }
+  /** Read bytes from the resolved physical file. */
+  async readBinary(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.readBinary(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved === null) throw new Error(`File not found: ${path}`);
+    return await this.storage.readBinaryResolved(resolved);
+  }
+  /** Write text at the resolved target while retaining existing physical spelling. */
+  async write(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.write(path, data, options);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.writeResolved(resolved, data, options);
+  }
+  /** Write bytes at the resolved target while retaining existing physical spelling. */
+  async writeBinary(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) {
+      return await this.storage.writeBinary(path, data, options);
+    }
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.writeBinaryResolved(resolved, data, options);
+  }
+  /** Append text at the resolved target using the host adapter semantics. */
+  async append(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.append(path, data, options);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.appendResolved(resolved, data, options);
+  }
+  /** List logical directory contents, checking equivalent child names in NFC mode. */
+  async list(basePath) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.list(basePath);
+    const resolver = this.createResolver(policy);
+    const resolved = await resolver.resolveExisting(parseFilePath(basePath));
+    if (resolved === null) return { files: [], folders: [] };
+    const entries = await resolver.listResolvedDirectory(resolved);
+    return this.groupStorageEntries(entries ?? []);
+  }
+  snapshotPolicy(caseInsensitive) {
+    const pathNormalizationVersion = getPathNormalizationVersion({
+      pathNormalizationVersion: this.getPathNormalizationVersion()
+    });
+    const isCaseInsensitive = caseInsensitive ?? this.isCaseInsensitive();
+    return Object.freeze({
+      pathNormalizationVersion,
+      handleFilenameCaseSensitive: !isCaseInsensitive
+    });
+  }
+  createResolver(policy) {
+    if (policy.pathNormalizationVersion !== 1) {
+      throw new Error("The storage path resolver requires NFC path normalisation");
+    }
+    return createStoragePathResolver({
+      readDirectory: (path) => this.storage.readDirectory(path),
+      policy: {
+        pathNormalizationVersion: 1,
+        handleFilenameCaseSensitive: policy.handleFilenameCaseSensitive
+      }
+    });
+  }
+  groupStorageEntries(entries) {
+    const files = [];
+    const folders = [];
+    for (const entry of entries) {
+      if (entry.kind === "file") files.push(entry.path);
+      else folders.push(entry.path);
+    }
+    return { files, folders };
+  }
+}
+export {
+  UnicodeResolvingFileSystemAccessStorageAdapter
+};

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

@@ -1 +1,2 @@
 export { FileSystemAccessStorageAdapter, createFileSystemAccessStorage, validateStoragePath, type CreateFileSystemAccessStorageOptions, type FileSystemAccessStorageStat, } from "./storage.js";
+export { UnicodeResolvingFileSystemAccessStorageAdapter } from "./UnicodeResolvingFileSystemAccessStorageAdapter.js";

package/dist/platform/browser/index.js

@@ -3,8 +3,10 @@ import {
   createFileSystemAccessStorage,
   validateStoragePath
 } from "./storage.js";
+import { UnicodeResolvingFileSystemAccessStorageAdapter } from "./UnicodeResolvingFileSystemAccessStorageAdapter.js";
 export {
   FileSystemAccessStorageAdapter,
+  UnicodeResolvingFileSystemAccessStorageAdapter,
   createFileSystemAccessStorage,
   validateStoragePath
 };

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

@@ -1,5 +1,6 @@
 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 FileSystemAccessStorageStat = UXStat;
 export interface CreateFileSystemAccessStorageOptions {
     /** A directory handle already selected and authorised by the host application. */
@@ -12,10 +13,32 @@ export declare class FileSystemAccessStorageAdapter implements IStorageAdapter<F
     private resolvePath;
     private getFileHandle;
     private getDirectoryHandle;
+    private getStrictDirectoryHandle;
+    private getStrictFileHandle;
+    private requireStrictFileHandle;
+    private getStrictWritableFileHandle;
     private resolveWritablePath;
     exists(path: string): Promise<boolean>;
     trystat(path: string): Promise<FileSystemAccessStorageStat | null>;
     stat(path: string): Promise<FileSystemAccessStorageStat | null>;
+    /** Enumerate one directory without converting permission or type errors into absence. */
+    readDirectory(path: StoragePath): Promise<readonly DirectoryEntry[] | null>;
+    /** Stat a path using its exact physical spelling and preserve non-missing errors. */
+    statResolved(path: StoragePath): Promise<FileSystemAccessStorageStat | null>;
+    /** Read an exact resolved file path while preserving missing, type, and permission errors. */
+    readResolved(path: StoragePath): Promise<string>;
+    /** Read an exact resolved file path as bytes while preserving host errors. */
+    readBinaryResolved(path: StoragePath): Promise<ArrayBuffer>;
+    /** Write an exact resolved file path, creating missing parent directories. */
+    writeResolved(path: StoragePath, data: string, _options?: UXDataWriteOptions): Promise<void>;
+    /** Write bytes to an exact resolved file path, creating missing parent directories. */
+    writeBinaryResolved(path: StoragePath, data: ArrayBuffer, _options?: UXDataWriteOptions): Promise<void>;
+    /** Append through strict reads and writes so denied reads cannot become truncating writes. */
+    appendResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Remove an exact resolved path, retaining the adapter's no-op behaviour when it is absent. */
+    removeResolved(path: StoragePath): Promise<void>;
+    /** Create an exact resolved directory path without hiding browser errors. */
+    mkdirResolved(path: StoragePath): Promise<void>;
     mkdir(path: string): Promise<void>;
     remove(path: string): Promise<void>;
     read(path: string): Promise<string>;

package/dist/platform/browser/storage.js

@@ -40,6 +40,47 @@ class FileSystemAccessStorageAdapter {
       return null;
     }
   }
+  async getStrictDirectoryHandle(path) {
+    validateStoragePath(path);
+    let currentHandle = this.rootHandle;
+    for (const part of path.split("/").filter((segment) => segment !== "")) {
+      try {
+        currentHandle = await currentHandle.getDirectoryHandle(part);
+      } catch (error) {
+        if (isNamedError(error, "NotFoundError")) return null;
+        throw error;
+      }
+    }
+    return currentHandle;
+  }
+  async getStrictFileHandle(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const dirHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!dirHandle) return null;
+    try {
+      return await dirHandle.getFileHandle(name);
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return null;
+      throw error;
+    }
+  }
+  async requireStrictFileHandle(path) {
+    const handle = await this.getStrictFileHandle(path);
+    if (!handle) throw new Error(`File not found: ${path}`);
+    return handle;
+  }
+  async getStrictWritableFileHandle(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const parentPath = parts.join("/");
+    await this.mkdir(parentPath);
+    const dirHandle = await this.getStrictDirectoryHandle(parentPath);
+    if (!dirHandle) throw new Error(`Invalid path: ${path}`);
+    return await dirHandle.getFileHandle(name, { create: true });
+  }
   async resolveWritablePath(path) {
     validateStoragePath(path, false);
     const parts = path.split("/").filter((part) => part !== "");
@@ -71,6 +112,100 @@ class FileSystemAccessStorageAdapter {
   async stat(path) {
     return await this.trystat(path);
   }
+  /** Enumerate one directory without converting permission or type errors into absence. */
+  async readDirectory(path) {
+    const dirHandle = await this.getStrictDirectoryHandle(path);
+    if (!dirHandle) return null;
+    const entries = [];
+    for await (const [name, entry] of dirHandle.entries()) {
+      if (entry.kind === "directory" || entry.kind === "file") {
+        entries.push({ name, kind: entry.kind });
+      }
+    }
+    return entries;
+  }
+  /** Stat a path using its exact physical spelling and preserve non-missing errors. */
+  async statResolved(path) {
+    validateStoragePath(path);
+    if (path === "") {
+      const now = Date.now();
+      return { size: 0, mtime: now, ctime: now, type: "folder" };
+    }
+    const parts = path.split("/");
+    const name = parts.pop();
+    const parentHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!parentHandle) return null;
+    let fileHandle;
+    try {
+      fileHandle = await parentHandle.getFileHandle(name);
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return null;
+      if (!isNamedError(error, "TypeMismatchError")) throw error;
+      try {
+        await parentHandle.getDirectoryHandle(name);
+      } catch (directoryError) {
+        if (isNamedError(directoryError, "NotFoundError")) return null;
+        throw directoryError;
+      }
+      const now = Date.now();
+      return { size: 0, mtime: now, ctime: now, type: "folder" };
+    }
+    const file = await fileHandle.getFile();
+    return {
+      size: file.size,
+      mtime: file.lastModified,
+      ctime: file.lastModified,
+      type: "file"
+    };
+  }
+  /** Read an exact resolved file path while preserving missing, type, and permission errors. */
+  async readResolved(path) {
+    const handle = await this.requireStrictFileHandle(path);
+    return await (await handle.getFile()).text();
+  }
+  /** Read an exact resolved file path as bytes while preserving host errors. */
+  async readBinaryResolved(path) {
+    const handle = await this.requireStrictFileHandle(path);
+    return await (await handle.getFile()).arrayBuffer();
+  }
+  /** Write an exact resolved file path, creating missing parent directories. */
+  async writeResolved(path, data, _options) {
+    const handle = await this.getStrictWritableFileHandle(path);
+    const writable = await handle.createWritable();
+    await writable.write(data);
+    await writable.close();
+  }
+  /** Write bytes to an exact resolved file path, creating missing parent directories. */
+  async writeBinaryResolved(path, data, _options) {
+    const handle = await this.getStrictWritableFileHandle(path);
+    const writable = await handle.createWritable();
+    await writable.write(data);
+    await writable.close();
+  }
+  /** Append through strict reads and writes so denied reads cannot become truncating writes. */
+  async appendResolved(path, data, options) {
+    const handle = await this.getStrictFileHandle(path);
+    const existing = handle ? await (await handle.getFile()).text() : "";
+    await this.writeResolved(path, existing + data, options);
+  }
+  /** Remove an exact resolved path, retaining the adapter's no-op behaviour when it is absent. */
+  async removeResolved(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const dirHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!dirHandle) return;
+    try {
+      await dirHandle.removeEntry(name, { recursive: true });
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return;
+      throw error;
+    }
+  }
+  /** Create an exact resolved directory path without hiding browser errors. */
+  async mkdirResolved(path) {
+    await this.mkdir(path);
+  }
   async mkdir(path) {
     validateStoragePath(path);
     let currentHandle = this.rootHandle;
@@ -131,6 +266,9 @@ function createFileSystemAccessStorage({
 }) {
   return new FileSystemAccessStorageAdapter(rootHandle);
 }
+function isNamedError(error, name) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === name;
+}
 import { validateStoragePath as validateStoragePath2 } from "../storagePath.js";
 export {
   FileSystemAccessStorageAdapter,

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

@@ -0,0 +1,79 @@
+import type { FilePath, StoragePath } from "../pathTypes.js";
+import { NodeStorageAdapter } from "./storage.js";
+/**
+ * Resolve NFC-equivalent logical paths against current Node directory names.
+ *
+ * @remarks
+ * Each operation snapshots Unicode and case settings. Version `0` delegates to
+ * the existing adapter; version `1` resolves names and rejects observed aliases
+ * before I/O. Physical spelling and the host adapter's mutation semantics remain
+ * unchanged. Resolution does not reserve paths against concurrent changes.
+ */
+export declare class UnicodeResolvingNodeStorageAdapter extends NodeStorageAdapter {
+    private readonly getPathNormalizationVersion;
+    private readonly isCaseInsensitive;
+    /**
+     * 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: string, getPathNormalizationVersion?: () => number, isCaseInsensitive?: () => boolean);
+    /** Whether the current settings select NFC path resolution. */
+    get isUnicodePathNormalizationEnabled(): boolean;
+    /** Read metadata for an entry already resolved or obtained from a storage listing. */
+    statExact(path: StoragePath): Promise<import("../../common/types.js").UXStat>;
+    /** Inspect a physical directory once before descending into its enumerated entries. */
+    listExact(path: StoragePath): Promise<{
+        files: StoragePath[];
+        folders: StoragePath[];
+    }>;
+    /**
+     * 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.
+     */
+    resolveLogicalPath(path: FilePath, caseInsensitive?: boolean, allowMissing?: boolean): Promise<StoragePath | null>;
+    /** Check whether the logical path exists under the current Unicode policy. */
+    exists(path: string, caseInsensitive?: boolean): Promise<boolean>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    trystat(path: string, caseInsensitive?: boolean): Promise<import("../../common/types.js").UXStat>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    stat(path: string, caseInsensitive?: boolean): Promise<import("../../common/types.js").UXStat>;
+    /** Create a directory at the resolved write target. */
+    mkdir(path: string, caseInsensitive?: boolean): Promise<void>;
+    /** Remove the entry at its resolved physical path. */
+    remove(path: string, caseInsensitive?: boolean): Promise<void>;
+    /** Read text from the resolved physical file. */
+    read(path: string, caseInsensitive?: boolean): Promise<string>;
+    /** Read bytes from the resolved physical file. */
+    readBinary(path: string, caseInsensitive?: boolean): Promise<ArrayBuffer>;
+    /** Write text at the resolved target while retaining existing physical spelling. */
+    write(path: string, data: string, options?: Parameters<NodeStorageAdapter["write"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Write bytes at the resolved target while retaining existing physical spelling. */
+    writeBinary(path: string, data: ArrayBuffer, options?: Parameters<NodeStorageAdapter["writeBinary"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Append text at the resolved target using the host adapter semantics. */
+    append(path: string, data: string, options?: Parameters<NodeStorageAdapter["append"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Resolve and perform an explicit rename, including a requested leaf spelling change. */
+    rename(sourcePath: string, targetPath: string, caseInsensitive?: boolean): Promise<void>;
+    /** List logical directory contents, checking equivalent child names in NFC mode. */
+    list(basePath: string, caseInsensitive?: boolean): Promise<{
+        files: string[];
+        folders: string[];
+    }>;
+    private statWithSettings;
+    private requireExistingPath;
+    private preflightRequestedPath;
+    private listPhysicalDirectory;
+    private createResolver;
+    private getSettings;
+    private getPathNormalizationVersionSnapshot;
+    private asStoragePath;
+    private missingPathError;
+}