@poe-platform/safe-fs 0.1.500 → 0.1.502

package/dist/safe-fs/bridge/stats.js

@@ -4,7 +4,7 @@ function predicates(type) {
         isDirectory: () => type === "directory",
         isSymbolicLink: () => type === "symlink",
         isBlockDevice: () => false,
-        isCharacterDevice: () => false,
+        isCharacterDevice: () => type === "character",
         isFIFO: () => false,
         isSocket: () => false,
     };
@@ -13,7 +13,7 @@ export function bridgeStats(stat) {
     return {
         dev: stat.dev ?? 0,
         ino: stat.ino ?? 0,
-        mode: (stat.mode & 0o7777) | (stat.type === "directory" ? 0o040000 : stat.type === "symlink" ? 0o120000 : 0o100000),
+        mode: (stat.mode & 0o7777) | (stat.type === "directory" ? 0o040000 : stat.type === "symlink" ? 0o120000 : stat.type === "character" ? 0o020000 : 0o100000),
         nlink: stat.nlink ?? 1,
         uid: stat.uid ?? 0,
         gid: stat.gid ?? 0,

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -1,5 +1,5 @@
 import type { ByteSource } from "./io.js";
-export type FileType = "file" | "directory" | "symlink";
+export type FileType = "file" | "directory" | "symlink" | "character";
 export type EntryComparison = "same" | "distinct" | "unknown";
 export interface FileStat {
     readonly type: FileType;

package/dist/safe-fs/core.d.ts

@@ -4,6 +4,7 @@ export * from "./contracts/io.js";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
 export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
 export * from "./fs/memory/index.js";
+export * from "./fs/devices/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";

package/dist/safe-fs/core.js

@@ -4,6 +4,7 @@ export * from "./contracts/io.js";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
 export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
 export * from "./fs/memory/index.js";
+export * from "./fs/devices/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";

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

@@ -0,0 +1,33 @@
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+export declare class DeviceFileSystem implements FileSystem {
+    #private;
+    readonly capabilities: FileSystemCapabilities;
+    constructor(filesystem: FileSystem);
+    canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
+    capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    openReadFile(path: string, options?: FsOptions): Promise<FileReadHandle>;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rename(source: string, destination: string, options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    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>;
+}
+export declare function createDeviceFileSystem(filesystem: FileSystem): DeviceFileSystem;

package/dist/safe-fs/fs/devices/index.js

@@ -0,0 +1,373 @@
+import { FsError, isFsError } from "../../contracts/errors.js";
+import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
+import { compareEntries, registerEntryView } from "../mount/comparison.js";
+import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
+import { deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
+const views = new WeakMap();
+const deviceCapabilities = Object.freeze({
+    readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
+    write: true, append: true, exclusiveCreate: true, streamingRead: true, retainedRead: true,
+    streamingWrite: true, streamingAppend: true, copy: true, exclusiveCopy: true,
+    remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
+    mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
+    permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
+    atomicRename: false, descriptorWriteStream: true,
+});
+function globalCapabilities(filesystem) {
+    const capabilities = { readOnly: false };
+    const optional = {
+        streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
+        streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"],
+        symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"],
+        timestamps: ["utimes"], readlink: ["readlink"], truncate: ["truncate"], removeDirectory: ["rmdir"],
+    };
+    for (const key of new Set([...Object.keys(filesystem.capabilities), ...Object.keys(deviceCapabilities)])) {
+        if (key === "readOnly")
+            continue;
+        Object.defineProperty(capabilities, key, { enumerable: true, get() {
+                if (key === "copy" || key === "exclusiveCopy")
+                    return undefined;
+                let declared = filesystem.capabilities[key];
+                if (declared === true && optional[key]?.some(method => typeof filesystem[method] !== "function"))
+                    declared = false;
+                if (key === "descriptorWriteStream" && filesystem.capabilities.streamingWrite === false)
+                    declared = false;
+                return declared === deviceCapabilities[key] ? declared : undefined;
+            } });
+    }
+    return Object.freeze(capabilities);
+}
+function reserved(path) { return path === "/" || path === deviceDirectory || path === nullPath; }
+function nonnegative(value, path) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+        throw new FsError("EINVAL", { path });
+}
+export class DeviceFileSystem {
+    #filesystem;
+    capabilities;
+    #nullStat;
+    #directoryStat;
+    constructor(filesystem) {
+        this.#filesystem = filesystem;
+        this.capabilities = globalCapabilities(filesystem);
+        const identityScope = Object.freeze({});
+        this.#nullStat = Object.freeze({ type: "character", mode: 0o020666, size: 0, allocatedBytes: 0,
+            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 1, dev: 0, nlink: 1 });
+        this.#directoryStat = Object.freeze({ ...this.#nullStat, type: "directory", mode: 0o040755, ino: 2 });
+        const methods = new Map();
+        const view = new Proxy(this, {
+            set: (_target, property, value) => Reflect.set(filesystem, property, value, filesystem),
+            get(target, property) {
+                const value = Reflect.get(target, property, target);
+                if (typeof value !== "function" || property === "constructor")
+                    return value;
+                const backing = Reflect.get(filesystem, property, filesystem);
+                const cached = methods.get(property);
+                if (cached && cached.backing === backing)
+                    return cached.bound;
+                const bound = value.bind(target);
+                methods.set(property, { backing, bound });
+                return bound;
+            },
+        });
+        for (const identity of [this, view])
+            registerEntryView(identity, async (path, options) => {
+                const resolved = await this.#resolve(path, options);
+                if (resolved === nullPath || resolved === deviceDirectory)
+                    return { filesystem: this, path: resolved,
+                        stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
+                return { filesystem, path };
+            });
+        return view;
+    }
+    #resolve(path, options, followFinal = true) {
+        return resolveDevicePath(this.#filesystem, path, options, followFinal);
+    }
+    async #mutable(path, options, followFinal = true) {
+        if (reserved(await this.#resolve(path, options, followFinal)))
+            throw new FsError("EBUSY", { path });
+    }
+    async #writeTarget(path, options) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath) {
+            if (options.flag === "wx" || options.flag === "ax")
+                throw new FsError("EEXIST", { path });
+            if (options.flag !== undefined && options.flag !== "w" && options.flag !== "a")
+                throw new FsError("EINVAL", { path });
+            return true;
+        }
+        if (resolved === "/" || resolved === deviceDirectory)
+            throw new FsError("EISDIR", { path });
+        return false;
+    }
+    canonicalizeMissingTarget(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const resolved = lexicalDevicePath(path);
+        return reserved(resolved) ? resolved : this.#filesystem.canonicalizeMissingTarget?.(path, options);
+    }
+    async capabilitiesFor(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            return deviceCapabilities;
+        if (resolved === deviceDirectory)
+            return { ...deviceCapabilities, readdir: true, write: false, append: false,
+                exclusiveCreate: false, streamingWrite: false, streamingAppend: false, descriptorWriteStream: false,
+                retainedRead: false, streamingRead: false, copy: false, exclusiveCopy: false };
+        const capabilities = await this.#filesystem.capabilitiesFor?.(path, options) ?? this.#filesystem.capabilities;
+        const unavailable = {};
+        if (typeof this.#filesystem.readStream !== "function")
+            unavailable.streamingRead = false;
+        if (typeof this.#filesystem.writeStream !== "function") {
+            unavailable.streamingWrite = false;
+            unavailable.streamingAppend = false;
+            unavailable.descriptorWriteStream = false;
+        }
+        if (typeof this.#filesystem.openReadFile !== "function")
+            unavailable.retainedRead = false;
+        return Object.keys(unavailable).some(key => capabilities[key] !== false)
+            ? { ...capabilities, ...unavailable } : capabilities;
+    }
+    async stat(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            return { ...this.#nullStat };
+        if (resolved === deviceDirectory)
+            return { ...this.#directoryStat };
+        return this.#filesystem.stat(path, options);
+    }
+    async lstat(path, options = {}) {
+        const resolved = await this.#resolve(path, options, false);
+        if (resolved === nullPath)
+            return { ...this.#nullStat };
+        if (resolved === deviceDirectory)
+            return { ...this.#directoryStat };
+        return this.#filesystem.lstat(path, options);
+    }
+    compareEntry(path, peer, peerPath, options = {}) {
+        return compareEntries(this, path, peer, peerPath, options);
+    }
+    async realpath(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        return reserved(resolved) ? resolved : this.#filesystem.realpath(path, options);
+    }
+    async readFile(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath) {
+            nonnegative(options.maxBytes, path);
+            return new Uint8Array();
+        }
+        if (resolved === deviceDirectory)
+            throw new FsError("EISDIR", { path });
+        return this.#filesystem.readFile(path, options);
+    }
+    readStream(path, options = {}) {
+        return deviceReadStream(async () => {
+            const resolved = await this.#resolve(path, options);
+            if (resolved === nullPath) {
+                nonnegative(options.start, path);
+                nonnegative(options.endExclusive, path);
+                nonnegative(options.chunkSize, path);
+                if (options.chunkSize === 0 || (options.endExclusive !== undefined && options.endExclusive < (options.start ?? 0)))
+                    throw new FsError("EINVAL", { path });
+                return { [Symbol.asyncIterator]: () => ({ next: async () => ({ done: true, value: undefined }) }) };
+            }
+            if (resolved === deviceDirectory)
+                throw new FsError("EISDIR", { path });
+            if (!this.#filesystem.readStream)
+                throw new FsError("ENOTSUP", { path });
+            return this.#filesystem.readStream(path, options);
+        });
+    }
+    async openReadFile(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved !== nullPath) {
+            if (resolved === deviceDirectory)
+                throw new FsError("EISDIR", { path });
+            if (!this.#filesystem.openReadFile)
+                throw new FsError("ENOTSUP", { path });
+            return this.#filesystem.openReadFile(path, options);
+        }
+        const stat = this.#nullStat;
+        let closed = false;
+        const check = (settings) => { settings.signal?.throwIfAborted(); if (closed)
+            throw new FsError("EBADF", { path }); };
+        return {
+            async stat(settings = {}) { check(settings); return { ...stat }; },
+            async read(position, maxBytes, settings = {}) { check(settings); nonnegative(position, path); nonnegative(maxBytes, path); return new Uint8Array(); },
+            async close() { closed = true; },
+        };
+    }
+    async writeFile(path, data, options = {}) {
+        if (await this.#writeTarget(path, options)) {
+            if (!(data instanceof Uint8Array))
+                throw new TypeError("File data must be Uint8Array");
+            return;
+        }
+        await this.#filesystem.writeFile(path, data, options);
+    }
+    async appendFile(path, data, options = {}) {
+        if (await this.#writeTarget(path, options)) {
+            if (!(data instanceof Uint8Array))
+                throw new TypeError("File data must be Uint8Array");
+            return;
+        }
+        await this.#filesystem.appendFile(path, data, options);
+    }
+    async writeStream(path, source, options = {}) {
+        if (await this.#writeTarget(path, options))
+            return drainDeviceInput(source, options.signal);
+        if (!this.#filesystem.writeStream)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.writeStream(path, source, options);
+    }
+    async readdir(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { path });
+        if (resolved !== "/" && resolved !== deviceDirectory)
+            return this.#filesystem.readdir(path, options);
+        const limit = directoryEntryLimit(options, path);
+        let entries;
+        try {
+            entries = await this.#filesystem.readdir(resolved, options);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!isFsError(error, "ENOENT") && !isFsError(error, "ENOTDIR"))
+                throw error;
+            entries = [];
+        }
+        options.signal?.throwIfAborted();
+        const merged = new Map();
+        for (const entry of entries) {
+            if (entry.name === "." || entry.name === "..")
+                continue;
+            if (!entry.name || entry.name.includes("/") || entry.name.includes("\0"))
+                throw new FsError("EIO", { path, message: "invalid directory entry" });
+            merged.set(entry.name, { name: entry.name, type: entry.type });
+            admitDirectoryEntries(merged.size, limit, path);
+        }
+        const name = resolved === "/" ? "dev" : "null";
+        merged.set(name, { name, type: resolved === "/" ? "directory" : "character" });
+        admitDirectoryEntries(merged.size, limit, path);
+        return [...merged.values()];
+    }
+    async mkdir(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (reserved(resolved)) {
+            if (resolved !== nullPath && options.recursive)
+                return;
+            throw new FsError("EEXIST", { path });
+        }
+        await this.#filesystem.mkdir(path, options);
+    }
+    async rm(path, options = {}) {
+        await this.#mutable(path, options, false);
+        await this.#filesystem.rm(path, options);
+    }
+    async rmdir(path, options = {}) {
+        const resolved = await this.#resolve(path, options, false);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { path });
+        if (reserved(resolved))
+            throw new FsError("EBUSY", { path });
+        if (!this.#filesystem.rmdir)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.rmdir(path, options);
+    }
+    async rename(source, destination, options = {}) {
+        await this.#mutable(source, options, false);
+        await this.#mutable(destination, options, false);
+        await this.#filesystem.rename(source, destination, options);
+    }
+    async copyFile(source, destination, options = {}) {
+        const target = await this.#resolve(destination, options);
+        if (target === nullPath && options.exclusive)
+            throw new FsError("EEXIST", { path: destination });
+        const origin = await this.#resolve(source, options);
+        if (target !== nullPath && origin !== nullPath) {
+            if (target === "/" || target === deviceDirectory)
+                throw new FsError("EISDIR", { path: destination });
+            await this.#filesystem.copyFile(source, destination, options);
+            return;
+        }
+        if (target === nullPath) {
+            if (origin === nullPath)
+                return;
+            if (origin === "/" || origin === deviceDirectory)
+                throw new FsError("EISDIR", { path: source });
+            const capabilities = await this.capabilitiesFor(source, options);
+            if (this.#filesystem.readStream && capabilities.streamingRead !== false) {
+                await drainDeviceInput(this.#filesystem.readStream(source, options), options.signal);
+            }
+            else if (this.#filesystem.openReadFile && capabilities.retainedRead !== false) {
+                await drainDeviceFile(await this.#filesystem.openReadFile(source, options), options.signal);
+            }
+            else
+                throw new FsError("ENOTSUP", { path: source });
+            return;
+        }
+        if (reserved(target))
+            throw new FsError("EISDIR", { path: destination });
+        await this.#filesystem.writeFile(destination, new Uint8Array(), { ...options, flag: options.exclusive ? "wx" : "w" });
+    }
+    async access(path, mode = 0, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath || resolved === deviceDirectory) {
+            if (!Number.isInteger(mode) || mode < 0 || mode > 7)
+                throw new FsError("EINVAL", { path });
+            if ((resolved === nullPath && (mode & 1)) || (resolved === deviceDirectory && (mode & 2)))
+                throw new FsError("EACCES", { path });
+            return;
+        }
+        await this.#filesystem.access(path, mode, options);
+    }
+    async readlink(path, options = {}) {
+        if (reserved(await this.#resolve(path, options, false)))
+            throw new FsError("EINVAL", { path });
+        if (!this.#filesystem.readlink)
+            throw new FsError("ENOTSUP", { path });
+        return this.#filesystem.readlink(path, options);
+    }
+    async symlink(target, path, options = {}) {
+        await this.#mutable(path, options, false);
+        if (!this.#filesystem.symlink)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.symlink(target, path, options);
+    }
+    async link(existingPath, newPath, options = {}) {
+        await this.#mutable(existingPath, options, false);
+        await this.#mutable(newPath, options, false);
+        if (!this.#filesystem.link)
+            throw new FsError("ENOTSUP", { path: newPath });
+        await this.#filesystem.link(existingPath, newPath, options);
+    }
+    async chmod(path, mode, options = {}) {
+        await this.#mutable(path, options);
+        if (!this.#filesystem.chmod)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.chmod(path, mode, options);
+    }
+    async utimes(path, atimeMs, mtimeMs, options = {}) {
+        await this.#mutable(path, options);
+        if (!this.#filesystem.utimes)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.utimes(path, atimeMs, mtimeMs, options);
+    }
+    async truncate(path, length, options = {}) {
+        await this.#mutable(path, options);
+        if (!this.#filesystem.truncate)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.truncate(path, length, options);
+    }
+}
+export function createDeviceFileSystem(filesystem) {
+    if (filesystem instanceof DeviceFileSystem)
+        return filesystem;
+    let view = views.get(filesystem);
+    if (!view) {
+        view = new DeviceFileSystem(filesystem);
+        views.set(filesystem, view);
+    }
+    return view;
+}

package/dist/safe-fs/fs/devices/path.d.ts

@@ -0,0 +1,5 @@
+import type { FileSystem, FsOptions } from "../../contracts/filesystem.js";
+export declare const nullPath = "/dev/null";
+export declare const deviceDirectory = "/dev";
+export declare function lexicalDevicePath(path: string): string;
+export declare function resolveDevicePath(filesystem: FileSystem, path: string, options: FsOptions, followFinal?: boolean): Promise<string>;

package/dist/safe-fs/fs/devices/path.js

@@ -0,0 +1,87 @@
+import { FsError, isFsError } from "../../contracts/errors.js";
+import { validatePath } from "../../contracts/virtual-path.js";
+export const nullPath = "/dev/null";
+export const deviceDirectory = "/dev";
+export function lexicalDevicePath(path) {
+    validatePath(path);
+    const parts = [];
+    for (const component of path.split("/")) {
+        if (`/${parts.join("/")}` === nullPath)
+            throw new FsError("ENOTDIR", { path });
+        if (component === "..")
+            parts.pop();
+        else if (component && component !== ".")
+            parts.push(component);
+    }
+    return `/${parts.join("/")}`;
+}
+export async function resolveDevicePath(filesystem, path, options, followFinal = true) {
+    options.signal?.throwIfAborted();
+    const lexical = lexicalDevicePath(path);
+    const aliases = typeof filesystem.lstat === "function";
+    if (!aliases && lexical !== nullPath && lexical !== deviceDirectory && lexical !== "/")
+        return lexical;
+    const pending = path.split("/");
+    const parts = [];
+    let links = 0;
+    let expanded = path.length;
+    let absolute = path.startsWith("/");
+    let traversalFailure;
+    while (pending.length) {
+        options.signal?.throwIfAborted();
+        if (`/${parts.join("/")}` === nullPath)
+            throw new FsError("ENOTDIR", { path });
+        const component = pending.shift();
+        if (!component || component === ".")
+            continue;
+        if (component === "..") {
+            parts.pop();
+            continue;
+        }
+        const candidate = `/${[...parts, component].join("/")}`;
+        if (candidate !== deviceDirectory && candidate !== nullPath && ((followFinal && aliases) || pending.length)) {
+            const lookup = absolute ? candidate : candidate.slice(1);
+            let stat;
+            try {
+                if (typeof filesystem.lstat !== "function")
+                    throw new FsError("ENOTSUP", { path });
+                stat = await filesystem.lstat(lookup, options);
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                if (isFsError(error, "ENOTSUP") && links === 0 && lexical !== nullPath && lexical !== deviceDirectory && lexical !== "/")
+                    return lexical;
+                if (!isFsError(error, "ENOENT"))
+                    throw error;
+                if (pending.length)
+                    traversalFailure ??= error;
+            }
+            options.signal?.throwIfAborted();
+            if (stat?.type === "symlink") {
+                if (typeof filesystem.readlink !== "function")
+                    throw new FsError("ENOTSUP", { path });
+                if (++links > 40)
+                    throw new FsError("ELOOP", { path });
+                const target = await filesystem.readlink(lookup, options);
+                options.signal?.throwIfAborted();
+                validatePath(target);
+                expanded += target.length;
+                if (expanded > 65536)
+                    throw new FsError("ENAMETOOLONG", { path });
+                if (target.startsWith("/")) {
+                    parts.length = 0;
+                    absolute = true;
+                }
+                pending.unshift(...target.split("/"));
+                continue;
+            }
+            if (stat && pending.length && stat.type !== "directory")
+                traversalFailure ??= new FsError("ENOTDIR", { path });
+        }
+        parts.push(component);
+    }
+    const resolved = `/${parts.join("/")}`;
+    if (traversalFailure && (resolved === nullPath || resolved === deviceDirectory || resolved === "/"))
+        throw traversalFailure;
+    return resolved;
+}

package/dist/safe-fs/fs/devices/stream.d.ts

@@ -0,0 +1,5 @@
+import type { ByteSource } from "../../contracts/io.js";
+import type { FileReadHandle } from "../../contracts/filesystem.js";
+export declare function deviceReadStream(open: () => Promise<ByteSource>): ByteSource;
+export declare function drainDeviceFile(handle: FileReadHandle, signal?: AbortSignal): Promise<void>;
+export declare function drainDeviceInput(source: ByteSource, signal?: AbortSignal): Promise<void>;

package/dist/safe-fs/fs/devices/stream.js

@@ -0,0 +1,116 @@
+import { finishCleanup } from "../../contracts/cleanup.js";
+export function deviceReadStream(open) {
+    return { [Symbol.asyncIterator]() {
+            let opened;
+            let closing;
+            const iterator = () => opened ??= open().then(source => source[Symbol.asyncIterator]());
+            const close = () => closing ??= iterator().then(async (source) => source.return ? source.return() : { done: true, value: undefined });
+            return {
+                async next() {
+                    if (closing) {
+                        await closing;
+                        return { done: true, value: undefined };
+                    }
+                    try {
+                        return await (await iterator()).next();
+                    }
+                    catch (error) {
+                        await finishCleanup(close, true);
+                        throw error;
+                    }
+                },
+                return: close,
+            };
+        } };
+}
+export async function drainDeviceFile(handle, signal) {
+    let failed = false;
+    let position = 0;
+    try {
+        await drainDeviceInput({ [Symbol.asyncIterator]: () => ({ async next() {
+                    const value = await handle.read(position, 65536, signal ? { signal } : {});
+                    if (!(value instanceof Uint8Array) || value.byteLength > 65536)
+                        throw new TypeError("Retained reads must return bounded Uint8Array chunks");
+                    position += value.byteLength;
+                    if (!Number.isSafeInteger(position))
+                        throw new RangeError("Retained read position exceeds safe integer range");
+                    return { done: value.byteLength === 0, value };
+                } }) }, signal);
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        await finishCleanup(async () => {
+            try {
+                await handle.close();
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                throw error;
+            }
+        }, failed);
+    }
+    signal?.throwIfAborted();
+}
+function nextChunk(iterator, signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const aborted = () => { signal?.removeEventListener("abort", aborted); reject(signal?.reason); };
+        signal?.addEventListener("abort", aborted, { once: true });
+        try {
+            Promise.resolve(iterator.next()).then(result => {
+                signal?.removeEventListener("abort", aborted);
+                if (signal?.aborted)
+                    reject(signal.reason);
+                else
+                    resolve(result);
+            }, error => { signal?.removeEventListener("abort", aborted); reject(signal?.aborted ? signal.reason : error); });
+        }
+        catch (error) {
+            signal?.removeEventListener("abort", aborted);
+            reject(signal?.aborted ? signal.reason : error);
+        }
+    });
+}
+export async function drainDeviceInput(source, signal) {
+    signal?.throwIfAborted();
+    const iterator = source[Symbol.asyncIterator]();
+    let failed = false;
+    let bytes = 0;
+    let pulls = 0;
+    try {
+        for (;;) {
+            const result = await nextChunk(iterator, signal);
+            signal?.throwIfAborted();
+            if (result.done)
+                break;
+            if (!(result.value instanceof Uint8Array))
+                throw new TypeError("Byte sources must yield Uint8Array chunks");
+            bytes += result.value.byteLength;
+            if (++pulls >= 64 || bytes >= 65536) {
+                await new Promise(resolve => setTimeout(resolve, 0));
+                signal?.throwIfAborted();
+                bytes = 0;
+                pulls = 0;
+            }
+        }
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        await finishCleanup(async () => {
+            try {
+                await iterator.return?.();
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                throw error;
+            }
+        }, failed);
+    }
+    signal?.throwIfAborted();
+}

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

@@ -1,5 +1,6 @@
 export * from "./contracts/index.js";
 export * from "./fs/memory/index.js";
+export * from "./fs/devices/index.js";
 export * from "./fs/real/index.js";
 export * from "./fs/s3/index.js";
 export type { S3StreamGetInput, S3StreamGetOutput, S3StreamPutInput } from "./fs/s3/transport.js";

package/dist/safe-fs/index.js

@@ -1,5 +1,6 @@
 export * from "./contracts/index.js";
 export * from "./fs/memory/index.js";
+export * from "./fs/devices/index.js";
 export * from "./fs/real/index.js";
 export * from "./fs/s3/index.js";
 export * from "./fs/s3/http/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.500",
+  "version": "0.1.502",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",