@poe-platform/safe-fs 0.1.0

package/dist/safe-fs/fs/mount/comparison.js

@@ -0,0 +1,118 @@
+import { comparisonContext, platform } from "#safe-fs-platform";
+import { FsError } from "../../contracts/errors.js";
+import { compareIdentity } from "./identity.js";
+const resolvers = new WeakMap();
+const authorities = new WeakMap();
+export function assertCallbackAuthorityAllowed() {
+    if (!platform.callbackAuthorities)
+        throw new FsError("ENOTSUP", { message: "custom comparison authorities require Node context" });
+}
+export function registerEntryView(filesystem, resolver) {
+    if (resolvers.has(filesystem))
+        throw new TypeError("entry view already registered");
+    resolvers.set(filesystem, resolver);
+}
+export function registerEntryAuthority(filesystem, authority) {
+    if (authorities.has(filesystem))
+        throw new TypeError("entry authority already registered");
+    authorities.set(filesystem, authority);
+}
+export async function resolveEntryView(filesystem, path, options = {}) {
+    let location = { filesystem, path };
+    let readOnly = false;
+    const visited = new Set();
+    for (;;) {
+        options.signal?.throwIfAborted();
+        if (visited.has(location.filesystem))
+            throw new FsError("EIO", { path, message: "cyclic entry view" });
+        visited.add(location.filesystem);
+        readOnly ||= location.readOnly === true || location.filesystem.capabilities.readOnly === true;
+        if (location.stat)
+            return { filesystem: location.filesystem, path: location.path, stat: location.stat, readOnly };
+        const resolve = resolvers.get(location.filesystem);
+        if (!resolve) {
+            let stat;
+            let followedPath;
+            try {
+                followedPath = await location.filesystem.realpath(location.path, options);
+                options.signal?.throwIfAborted();
+                stat = await location.filesystem.lstat(followedPath, options);
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                throw error;
+            }
+            options.signal?.throwIfAborted();
+            if (stat.type === "symlink")
+                throw new FsError("EIO", { path, message: "followed entry changed during observation" });
+            return { filesystem: location.filesystem, path: followedPath, stat, readOnly };
+        }
+        let next;
+        try {
+            next = await resolve(location.path, options);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (next.filesystem === location.filesystem && next.stat) {
+            return { filesystem: next.filesystem, path: next.path, stat: next.stat, readOnly: readOnly || next.readOnly === true };
+        }
+        location = next;
+    }
+}
+export async function compareResolvedEntries(own, peer, options = {}) {
+    options.signal?.throwIfAborted();
+    if (comparisonContext.active(options))
+        return "unknown";
+    const identity = compareIdentity(own.stat, peer.stat);
+    if (identity !== "unknown")
+        return identity;
+    return comparisonContext.run(options, async (options) => {
+        const queried = new Set();
+        let result = "unknown";
+        for (const [left, right] of [[own, peer], [peer, own]]) {
+            options.signal?.throwIfAborted();
+            const authority = authorities.get(left.filesystem);
+            const key = authority ?? left.filesystem;
+            if (queried.has(key))
+                continue;
+            queried.add(key);
+            let answer;
+            try {
+                if (authority)
+                    answer = await authority(left, right, options);
+                else if (left.filesystem.compareEntry) {
+                    assertCallbackAuthorityAllowed();
+                    answer = await left.filesystem.compareEntry(left.path, right.filesystem, right.path, options);
+                }
+                else
+                    continue;
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                throw error;
+            }
+            options.signal?.throwIfAborted();
+            if (answer !== "same" && answer !== "distinct" && answer !== "unknown") {
+                throw new FsError("EIO", { path: own.path, dest: peer.path, message: "invalid entry comparison answer" });
+            }
+            if (answer === "unknown")
+                continue;
+            if (result !== "unknown" && result !== answer) {
+                throw new FsError("EIO", { path: own.path, dest: peer.path, message: "conflicting entry comparison answers" });
+            }
+            result = answer;
+        }
+        return result;
+    });
+}
+export async function compareEntries(filesystem, path, peer, peerPath, options = {}) {
+    options.signal?.throwIfAborted();
+    if (comparisonContext.active(options))
+        return "unknown";
+    const own = await resolveEntryView(filesystem, path, options);
+    const other = await resolveEntryView(peer, peerPath, options);
+    return compareResolvedEntries(own, other, options);
+}

package/dist/safe-fs/fs/mount/identity.d.ts

@@ -0,0 +1,2 @@
+import type { FileStat } from "../../contracts/filesystem.js";
+export declare function compareIdentity(left: FileStat | undefined, right: FileStat | undefined): "same" | "distinct" | "unknown";

package/dist/safe-fs/fs/mount/identity.js

@@ -0,0 +1,12 @@
+function complete(stat) {
+    const { identityScope, dev, ino } = stat;
+    return ((typeof identityScope === "object" && identityScope !== null) || typeof identityScope === "symbol")
+        && typeof dev === "number" && Number.isSafeInteger(dev) && dev >= 0
+        && typeof ino === "number" && Number.isSafeInteger(ino) && ino >= 0;
+}
+export function compareIdentity(left, right) {
+    if (!left || !right || !complete(left) || !complete(right))
+        return "unknown";
+    return left.identityScope === right.identityScope && left.dev === right.dev && left.ino === right.ino
+        ? "same" : "distinct";
+}

package/dist/safe-fs/fs/mount/index.d.ts

@@ -0,0 +1,44 @@
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+export interface MountFileSystemOptions {
+    readonly root: FileSystem;
+    readonly mounts?: Readonly<Record<string, FileSystem>>;
+}
+export declare class MountFileSystem implements FileSystem {
+    readonly capabilities: FileSystemCapabilities;
+    private readonly mounts;
+    constructor(options: MountFileSystemOptions);
+    private select;
+    private protected;
+    private error;
+    private operation;
+    private components;
+    private lookup;
+    private resolve;
+    private mutable;
+    private entryPath;
+    private optional;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    rename(source: string, destination: string, options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string, options?: FsOptions): Promise<string>;
+    symlink(target: string, path: string, options?: FsOptions): Promise<void>;
+    link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
+    utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+}
+export declare function createMountFileSystem(options: MountFileSystemOptions): MountFileSystem;