@poe-platform/safe-fs 0.1.807 → 0.1.809

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

@@ -95,8 +95,8 @@ export class OverlayFileSystem {
             : readable.every((capability) => capability === false) ? false : undefined;
         const retainedRead = streamingRead;
         const streamingWrite = writable && this.#upper.capabilities.streamingWrite === true
-            && this.#upper.capabilities.streamingRead === true
-            && typeof this.#upper.writeStream === "function" && typeof this.#upper.readStream === "function"
+            && retainedReadCapabilities(this.#upper).retainedRead === true
+            && typeof this.#upper.writeStream === "function"
             ? readable.every((capability) => capability === true) ? true : undefined : false;
         const append = !writable || this.#upper.capabilities.append === false ? false
             : this.#upper.capabilities.append === true ? true : undefined;
@@ -117,8 +117,8 @@ export class OverlayFileSystem {
             ["rename", requireCapabilities(mutation, upper.rename, upper.write)],
             ["copy", requireCapabilities(mutation, upper.write)],
             ["exclusiveCopy", requireCapabilities(mutation, upper.exclusiveCreate)],
-            ["truncate", requireCapabilities(mutation, upper.truncate)],
-            ["streamingAppend", requireCapabilities(mutation, streamingWrite, upper.streamingAppend)],
+            ["truncate", requireCapabilities(mutation, streamingWrite)],
+            ["streamingAppend", requireCapabilities(mutation, streamingWrite)],
             ["randomAccessWrite", requireCapabilities(mutation, upper.randomAccessWrite)],
             ["explicitDirectories", requireCapabilities(upper.explicitDirectories, this.#lower.capabilities.explicitDirectories)],
         ].filter(([, value]) => value !== undefined));
@@ -554,7 +554,12 @@ export class OverlayFileSystem {
     async cleanup(options = {}) {
         return this.run(options, () => this.cleanGarbage(true));
     }
+    // Receipts describe overlay paths and identities, never backing-layer staging paths.
+    stagingOptions({ signal }) {
+        return signal === undefined ? {} : { signal };
+    }
     async staged(options, operation) {
+        options = this.stagingOptions(options);
         const root = `/.virtual-bash-overlay-${platform.randomUUID()}`;
         if (await this.maybeStat(this.#upper, root, options) || await this.maybeStat(this.#lower, root, options))
             fail("EEXIST", root);
@@ -570,6 +575,7 @@ export class OverlayFileSystem {
         }
     }
     async preserve(path, stat, options) {
+        options = this.stagingOptions(options);
         if (this.#upper.chmod)
             await this.#upper.chmod(path, stat.mode & 0o7777, options);
         else if (((await this.#upper.lstat(path, options)).mode & 0o7777) !== (stat.mode & 0o7777))
@@ -578,7 +584,8 @@ export class OverlayFileSystem {
             fail("ENOTSUP", path, "upper cannot preserve timestamps during copy-up");
         await this.#upper.utimes(path, stat.atimeMs, stat.mtimeMs, options);
     }
-    async clone(entry, destination, options, streaming = false) {
+    async clone(entry, destination, options) {
+        options = this.stagingOptions(options);
         if (entry.stat.type !== "directory" && ((entry.stat.nlink ?? 1) > 1
             || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined))) {
             fail("ENOTSUP", entry.path, "copy-up cannot preserve hardlink identity");
@@ -591,23 +598,14 @@ export class OverlayFileSystem {
         }
         if (entry.stat.type === "directory")
             await this.#upper.mkdir(destination, { ...options, mode: entry.stat.mode & 0o7777 });
-        else if (streaming && entry.backend.readStream && entry.backend.capabilities.streamingRead !== false && this.#upper.writeStream) {
+        else {
+            if (this.#upper.capabilities.streamingWrite !== true || !this.#upper.writeStream)
+                fail("ENOTSUP", destination, "copy-up requires a streaming upper");
             this.permission(entry, 4);
             if (entry.stat.size > this.maxBufferBytes)
                 fail("EFBIG", entry.path);
-            const handle = await this.pinRead(entry, options);
-            let failed = true;
-            try {
-                const source = this.bounded(this.handleBytes(handle, options), entry.path, options);
-                await this.streamToUpper(destination, source, { ...options, mode: 0o600, flag: "wx" });
-                failed = false;
-            }
-            finally {
-                await finishCleanup(() => handle.close(), failed);
-            }
+            await this.streamToUpper(destination, this.bounded(this.entryBytes(entry, options), entry.path, options), { ...options, mode: 0o600, flag: "wx" });
         }
-        else
-            await this.#upper.writeFile(destination, await this.bytes(entry, options), { ...options, mode: 0o600, flag: "wx" });
         await this.preserve(destination, entry.stat, options);
     }
     rememberLink(entry, destination) {
@@ -617,6 +615,7 @@ export class OverlayFileSystem {
         }
     }
     async ensureDirectory(path, options) {
+        options = this.stagingOptions(options);
         const entry = await this.lookup(path, options);
         if (!entry)
             fail("ENOENT", path);
@@ -627,6 +626,7 @@ export class OverlayFileSystem {
         await this.copyUp(entry, options);
     }
     async copyUp(entry, options) {
+        options = this.stagingOptions(options);
         if (entry.backend === this.#upper)
             return;
         if (entry.path === "/")
@@ -649,6 +649,7 @@ export class OverlayFileSystem {
         });
     }
     async parent(path, options) {
+        options = this.stagingOptions(options);
         const parent = await this.lookup(dirname(path), options);
         if (!parent)
             fail("ENOENT", dirname(path));
@@ -686,11 +687,11 @@ export class OverlayFileSystem {
         }
         return location;
     }
-    async replace(location, options, operation, streaming = false, commitGuard) {
+    async replace(location, options, operation, commitGuard) {
         await this.parent(location.path, options);
         await this.staged(options, async (temporary) => {
             if (location.entry)
-                await this.clone(location.entry, temporary, options, streaming);
+                await this.clone(location.entry, temporary, options);
             await operation(temporary);
             options.signal?.throwIfAborted();
             commitGuard?.();
@@ -769,6 +770,72 @@ export class OverlayFileSystem {
         const limit = directoryEntryLimit(options, path);
         return this.run(options, async () => this.listing(await this.required(path, options), options, limit), false);
     }
+    async *iterateDirectory(path, options = {}) {
+        const directory = await this.run(options, async () => {
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "directory")
+                fail("ENOTDIR", path);
+            this.permission(entry, 4);
+            return entry.path;
+        }, false);
+        const admit = async () => {
+            const current = await this.required(path, options);
+            if (current.path !== directory || current.stat.type !== "directory")
+                fail("EBUSY", path);
+            this.permission(current, 4);
+        };
+        for (const backend of [this.#upper, this.#lower]) {
+            const iterator = await this.run(options, async () => {
+                await admit();
+                if (backend === this.#lower && (!await this.lowerVisible(directory, options) || this.opaque.has(directory)))
+                    return undefined;
+                if ((await this.maybeStat(backend, directory, options))?.type !== "directory")
+                    return undefined;
+                if (!backend.iterateDirectory)
+                    fail("ENOTSUP", directory);
+                return backend.iterateDirectory(directory, options)[Symbol.asyncIterator]();
+            }, false);
+            if (!iterator)
+                continue;
+            let complete = false, failed = false;
+            try {
+                while (true) {
+                    const result = await this.run(options, async () => {
+                        await admit();
+                        if (backend === this.#lower && (!await this.lowerVisible(directory, options) || this.opaque.has(directory)))
+                            fail("EBUSY", path);
+                        const next = await iterator.next();
+                        options.signal?.throwIfAborted();
+                        if (next.done)
+                            return { done: true };
+                        const name = next.value.name;
+                        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
+                            fail("EIO", directory, "invalid backend directory entry");
+                        const child = await this.lookup(directory === "/" ? `/${name}` : `${directory}/${name}`, options);
+                        options.signal?.throwIfAborted();
+                        // A lower name shadowed by upper storage is skipped by lookup,
+                        // without retaining a directory-sized set of previously seen names.
+                        return { done: false, entry: child?.backend === backend ? { name, type: child.stat.type } : undefined };
+                    }, false);
+                    if (result.done) {
+                        complete = true;
+                        break;
+                    }
+                    if (result.entry)
+                        yield result.entry;
+                }
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                if (!complete)
+                    await finishCleanup(() => iterator.return?.(), failed);
+            }
+        }
+        options.signal?.throwIfAborted();
+    }
     async realpath(path, options = {}) {
         return this.run(options, async () => (await this.required(path, options)).path, false);
     }
@@ -983,9 +1050,10 @@ export class OverlayFileSystem {
                 }
             }
             await this.cleanGarbage(false);
-            const bytes = await this.bytes(original, options);
+            if (original.stat.size > this.maxBufferBytes)
+                fail("EFBIG", source);
             await this.replace(target, options, async (temporary) => {
-                await this.#upper.writeFile(temporary, bytes, { ...options, mode: original.stat.mode & 0o7777, flag: "w" });
+                await this.streamToUpper(temporary, this.entryBytes(original, options), { ...options, mode: original.stat.mode & 0o7777, flag: "w" });
                 if (this.#upper.chmod)
                     await this.#upper.chmod(temporary, original.stat.mode & 0o7777, options);
                 else if (((await this.#upper.lstat(temporary, options)).mode & 0o7777) !== (original.stat.mode & 0o7777))
@@ -1057,7 +1125,7 @@ export class OverlayFileSystem {
                     await this.#upper.chmod(entry.path, permissions, controls);
                 }
                 else {
-                    await this.replace({ path: entry.path, entry }, controls, temporary => this.#upper.chmod(temporary, permissions, controls), false, guard);
+                    await this.replace({ path: entry.path, entry }, controls, temporary => this.#upper.chmod(temporary, permissions, controls), guard);
                 }
             });
         }
@@ -1079,15 +1147,30 @@ export class OverlayFileSystem {
             if (entry.stat.type !== "file")
                 fail("EISDIR", path);
             this.permission(entry, 2);
-            await this.replace({ path: entry.path, entry }, options, async (temporary) => {
-                if (this.#upper.truncate)
-                    await this.#upper.truncate(temporary, length, options);
-                else {
-                    const previous = await this.#upper.readFile(temporary, { ...options, ...(this.maxBufferBytes === Infinity ? {} : { maxBytes: this.maxBufferBytes }) });
-                    const bytes = new Uint8Array(length);
-                    bytes.set(previous.subarray(0, length));
-                    await this.#upper.writeFile(temporary, bytes, options);
-                }
+            if ((entry.stat.nlink ?? 1) > 1 || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined)) {
+                fail("ENOTSUP", path, "copy-up cannot preserve hardlink identity");
+            }
+            await this.parent(entry.path, options);
+            await this.staged(options, async (temporary) => {
+                const prefix = this.entryBytes(entry, { ...options, endExclusive: length });
+                const source = async function* () {
+                    let written = 0;
+                    for await (const chunk of prefix) {
+                        written += chunk.byteLength;
+                        yield chunk;
+                    }
+                    while (written < length) {
+                        options.signal?.throwIfAborted();
+                        const zero = new Uint8Array(Math.min(64 * 1024, length - written));
+                        written += zero.byteLength;
+                        yield zero;
+                    }
+                };
+                await this.streamToUpper(temporary, source(), { ...options, mode: 0o600, flag: "wx" });
+                await this.preserve(temporary, entry.stat, options);
+                await this.#upper.utimes(temporary, entry.stat.atimeMs, Date.now(), options);
+                options.signal?.throwIfAborted();
+                await this.#upper.rename(temporary, entry.path, options);
             });
         });
     }
@@ -1130,7 +1213,7 @@ export class OverlayFileSystem {
         }
     }
     async streamToUpper(path, source, options) {
-        if (!this.#upper.writeStream)
+        if (!this.#upper.writeStream || this.#upper.capabilities.streamingWrite !== true)
             fail("ENOTSUP", path);
         const input = readBytes(source, options.signal);
         let failed = false;
@@ -1145,39 +1228,74 @@ export class OverlayFileSystem {
             await finishCleanup(() => input.return(undefined), failed);
         }
     }
+    async *entryBytes(entry, options) {
+        this.permission(entry, 4);
+        const handle = this.activeStages.has(dirname(entry.path)) && entry.backend === this.#upper
+            ? await openRetainedReadFile(this.#upper, entry.path, options) : await this.pinRead(entry, options);
+        let failed = true;
+        try {
+            if (compareIdentity(await handle.stat(options), entry.stat) !== "same")
+                fail("EAGAIN", entry.path);
+            yield* this.handleBytes(handle, options);
+            failed = false;
+        }
+        finally {
+            await finishCleanup(() => handle.close(), failed);
+        }
+    }
     async writeStream(path, source, options = {}) {
         options.signal?.throwIfAborted();
         this.writeOptions(path, options);
+        if (this.capabilities.streamingWrite === false)
+            fail("ENOTSUP", path, "streaming requires retained reads and a streaming upper");
         await this.run(options, () => this.writeLocation(path, options));
-        if (this.capabilities.streamingWrite !== false) {
-            await this.staged(options, async (incoming) => {
-                const bounded = this.bounded(source, path, options);
-                await this.streamToUpper(incoming, bounded, { ...options, flag: "wx", mode: 0o600 });
-                const size = (await this.#upper.stat(incoming, options)).size;
-                await this.run(options, async () => {
-                    const location = await this.writeLocation(path, options);
-                    const append = options.flag === "a" || options.flag === "ax";
-                    if (append && (location.entry?.stat.size ?? 0) + size > this.maxBufferBytes)
-                        fail("EFBIG", path);
-                    if (this.publication.supported() && location.entry?.backend === this.#upper) {
-                        const bytes = await this.#upper.readFile(incoming, options);
-                        const parent = await this.required(dirname(location.path), options);
-                        await this.publication.writeFile(location.path, bytes, {
-                            ...options, parent: this.publication.stat(parent.path, parent.stat),
-                            expected: this.publication.stat(location.path, location.entry.stat), append,
-                        }, this.maxBufferBytes);
+        await this.staged(options, async (incoming) => {
+            await this.streamToUpper(incoming, this.bounded(source, path, options), { ...options, flag: "wx", mode: 0o600 });
+            const incomingEntry = { path: incoming, backend: this.#upper, stat: await this.#upper.lstat(incoming, options) };
+            await this.run(options, async () => {
+                const location = await this.writeLocation(path, options);
+                const append = options.flag === "a" || options.flag === "ax";
+                if (append && (location.entry?.stat.size ?? 0) + incomingEntry.stat.size > this.maxBufferBytes)
+                    fail("EFBIG", path);
+                if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                    const parent = await this.required(dirname(location.path), options);
+                    const controls = { ...options, parent: this.publication.stat(parent.path, parent.stat),
+                        expected: this.publication.stat(location.path, location.entry.stat) };
+                    const guard = this.publication.prepareWrite(location.path, controls);
+                    if (append) {
+                        await this.staged(options, async (temporary) => {
+                            const previous = this.entryBytes(location.entry, options);
+                            const added = this.entryBytes(incomingEntry, options);
+                            await this.streamToUpper(temporary, (async function* () { yield* previous; yield* added; })(), { ...options, flag: "wx", mode: 0o600 });
+                            this.publication.replaceContents(temporary, location.path, guard);
+                        });
                     }
-                    else {
-                        await this.replace(location, options, async (temporary) => {
-                            await this.streamToUpper(temporary, this.#upper.readStream(incoming, options), { ...options, flag: append ? "a" : "w" });
-                        }, true);
+                    else
+                        this.publication.replaceContents(incoming, location.path, guard);
+                }
+                else {
+                    if (location.entry && ((location.entry.stat.nlink ?? 1) > 1
+                        || (location.entry.backend.capabilities.hardlinks === true && location.entry.stat.nlink === undefined))) {
+                        fail("ENOTSUP", path, "copy-up cannot preserve hardlink identity");
                     }
-                });
+                    await this.parent(location.path, options);
+                    await this.staged(options, async (temporary) => {
+                        const previous = append && location.entry ? this.entryBytes(location.entry, options) : undefined;
+                        const added = this.entryBytes(incomingEntry, options);
+                        await this.streamToUpper(temporary, (async function* () { if (previous)
+                            yield* previous; yield* added; })(), { ...options, flag: "wx", mode: location.entry ? 0o600 : options.mode ?? 0o666 });
+                        if (location.entry) {
+                            await this.preserve(temporary, location.entry.stat, options);
+                            await this.#upper.utimes(temporary, location.entry.stat.atimeMs, Date.now(), options);
+                        }
+                        options.signal?.throwIfAborted();
+                        await this.#upper.rename(temporary, location.path, options);
+                        this.linkMetadata.delete(location.path);
+                        this.linkOrigins.delete(location.path);
+                    });
+                }
             });
-            return;
-        }
-        const bytes = await collectBytes(source, { ...(this.maxBufferBytes === Infinity ? {} : { maxBytes: this.maxBufferBytes }), ...(options.signal ? { signal: options.signal } : {}) });
-        await this.writeFile(path, bytes, options);
+        });
     }
 }
 export function createOverlayFileSystem(options) {

package/dist/safe-fs/fs/overlay/memory-publication.d.ts

@@ -29,6 +29,7 @@ export declare class OverlayMemoryPublication {
     private check;
     prepareChmod(path: string, options: ChmodOptions): (() => true) | undefined;
     prepareWrite(path: string, options: ConditionalWriteFileOptions): () => true;
+    replaceContents(source: string, destination: string, guard: () => true): void;
     writeFile(path: string, data: Uint8Array, options: ConditionalWriteFileOptions, maxBytes: number, guard?: () => void): Promise<FileStat>;
     removeFile(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions, guard?: () => void): Promise<FileStat>;

package/dist/safe-fs/fs/overlay/memory-publication.js

@@ -203,6 +203,11 @@ export class OverlayMemoryPublication {
             return true;
         };
     }
+    replaceContents(source, destination, guard) {
+        const { upper } = this.stores();
+        guard();
+        upper.replaceContents(source, destination);
+    }
     async writeFile(path, data, options, maxBytes, guard) {
         const check = this.prepareWrite(path, options);
         check();
@@ -371,6 +376,24 @@ export class OverlayMemoryPublication {
         const owned = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
         const staging = Object.freeze({
             parent: owned.parent, directory: owned.directory, file: owned.file,
+            ...(owned.writer ? { writer: Object.freeze({
+                    write: async (bytes, controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        await owned.writer.write(bytes, controls);
+                    },
+                    finish: async (controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        const stat = await owned.writer.finish(controls);
+                        this.stages.set(staging.directory, { ...owned, file: { ...owned.file, stat } });
+                        return stat;
+                    },
+                }) } : {}),
             ...(owned.cleanup ? { cleanup: createStagingCleanup(directory, controls => this.cleanup(staging, controls, true), () => owned.cleanup.close()) } : {}),
         });
         this.stages.set(staging.directory, owned);
@@ -379,6 +402,8 @@ export class OverlayMemoryPublication {
         return staging;
     }
     async publish(staging, path, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path });
         options.signal?.throwIfAborted();
         this.path(path);
         const owned = this.stages.get(staging.directory);

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

@@ -1,5 +1,6 @@
 import { FsError } from "../../contracts/errors.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
+import { readBytes } from "../../contracts/io.js";
 import { openRetainedReadFile, openRetainedResizeFile, quotaCapabilities, retainedReadCapabilities, retainedResizeCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries } from "../directory-admission.js";
 import { forwardFileDescriptor, openFileDescriptor } from "../descriptor.js";
@@ -485,12 +486,16 @@ export function withFileSystemQuota(fs, options) {
         },
         writeStream(path, source, writeOptions) {
             return mutate(async () => {
+                if (fs.capabilities.streamingAppend !== true || !fs.writeStream)
+                    throw new FsError("ENOTSUP", { syscall: "writeStream", path });
                 const append = writeOptions?.flag === "a" || writeOptions?.flag === "ax";
                 if (!append)
                     await fs.writeFile(path, new Uint8Array(), writeOptions);
-                for await (const chunk of source) {
+                else
+                    await fs.writeStream(path, (async function* () { })(), writeOptions);
+                for await (const chunk of readBytes(source, writeOptions?.signal)) {
                     await assertDelta(path, await existingBytes(fs, path, writeOptions) + chunk.length, writeOptions);
-                    await fs.appendFile(path, chunk, writeOptions);
+                    await fs.writeStream(path, (async function* () { yield chunk; })(), { ...writeOptions, flag: "a" });
                 }
             });
         },
@@ -502,11 +507,11 @@ export function withFileSystemQuota(fs, options) {
             if (property === "publishStagedFileSet" || property === "prepareStagingResolution" || property === "prepareDirectoryAncestry" || property === "publishFileConditional" || property === "removeEntryConditional" || property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
                 return undefined;
             if (property === "capabilities")
-                return quotaCapabilities({ ...retainedResizeCapabilities(fs, retainedReadCapabilities(fs)), ...(typeof fs.open === "function" ? {} : { open: false }) });
+                return quotaCapabilities({ ...retainedResizeCapabilities(fs, retainedReadCapabilities(fs)), ...(typeof fs.open === "function" ? {} : { open: false }), ...(typeof fs.writeStream === "function" ? {} : { streamingAppend: false }) });
             if (property === "capabilitiesFor")
                 return async (path, fsOptions) => {
                     const capabilities = await fs.capabilitiesFor?.(path, fsOptions) ?? fs.capabilities;
-                    return quotaCapabilities({ ...retainedResizeCapabilities(fs, retainedReadCapabilities(fs, capabilities)), ...(typeof fs.open === "function" ? {} : { open: false }) });
+                    return quotaCapabilities({ ...retainedResizeCapabilities(fs, retainedReadCapabilities(fs, capabilities)), ...(typeof fs.open === "function" ? {} : { open: false }), ...(typeof fs.writeStream === "function" ? {} : { streamingAppend: false }) });
                 };
             if (property === "openReadFile")
                 return (path, fsOptions = {}) => openRetainedReadFile(fs, path, fsOptions);

package/dist/safe-fs/fs/read-file-stream.d.ts

@@ -0,0 +1,7 @@
+import type { FileSystem, ReadStreamOptions } from "../contracts/filesystem.js";
+/** Sequential payload access without a whole-file fallback. The injected backend
+ * must supply streaming reads or retained range reads; no private storage is used.
+ * Chunks are borrowed until the consumer advances the iterator. */
+export declare function readFileStream(fs: FileSystem, path: string, options?: ReadStreamOptions & {
+    readonly skipStream?: boolean;
+}): AsyncGenerator<Uint8Array>;

package/dist/safe-fs/fs/read-file-stream.js

@@ -0,0 +1,103 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+import { openRetainedReadFile } from "./capabilities.js";
+const byteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+const byteKind = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag).get;
+/** Sequential payload access without a whole-file fallback. The injected backend
+ * must supply streaming reads or retained range reads; no private storage is used.
+ * Chunks are borrowed until the consumer advances the iterator. */
+export function readFileStream(fs, path, options = {}) {
+    let activeCleanup;
+    const generator = (async function* () {
+        const { signal } = options;
+        signal?.throwIfAborted();
+        const chunkSize = options.chunkSize ?? 65536;
+        let position = options.start ?? 0;
+        const end = options.endExclusive ?? Number.MAX_SAFE_INTEGER;
+        if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0 || !Number.isSafeInteger(position) || position < 0
+            || !Number.isSafeInteger(end) || end < position)
+            throw new FsError("EINVAL", { path, syscall: "readStream" });
+        const capabilities = await fs.capabilitiesFor?.(path, options) ?? fs.capabilities;
+        signal?.throwIfAborted();
+        if (!options.skipStream && fs.readStream && fs.capabilities?.streamingRead !== false && capabilities?.streamingRead !== false) {
+            let emitted = false;
+            let reading = true;
+            try {
+                const source = fs.readStream(path, { ...options, chunkSize });
+                const iterator = source[Symbol.asyncIterator]();
+                let done = false, failed = true;
+                let returned;
+                const closeIterator = () => returned ??= Promise.resolve().then(() => iterator.return?.());
+                activeCleanup = () => done ? Promise.resolve() : closeIterator();
+                try {
+                    while (true) {
+                        signal?.throwIfAborted();
+                        const item = await iterator.next();
+                        signal?.throwIfAborted();
+                        if (item.done) {
+                            done = true;
+                            break;
+                        }
+                        reading = false;
+                        if (byteLength.call(item.value))
+                            emitted = true;
+                        yield item.value;
+                        reading = true;
+                    }
+                    failed = false;
+                }
+                finally {
+                    activeCleanup = undefined;
+                    if (!done)
+                        await finishCleanup(closeIterator, failed);
+                }
+                return;
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                if (!reading || emitted || !(error instanceof FsError) || error.code !== "ENOTSUP")
+                    throw error;
+            }
+        }
+        const handle = await openRetainedReadFile(fs, path, options);
+        let failed = true;
+        let closed;
+        const closeHandle = () => closed ??= Promise.resolve().then(() => handle.close());
+        activeCleanup = closeHandle;
+        try {
+            while (position < end) {
+                signal?.throwIfAborted();
+                const maximum = Math.min(chunkSize, end - position);
+                const bytes = await handle.read(position, maximum, options);
+                signal?.throwIfAborted();
+                if (byteKind.call(bytes) !== "Uint8Array" || byteLength.call(bytes) > maximum)
+                    throw new FsError("EIO", { path, syscall: "read" });
+                const length = byteLength.call(bytes);
+                if (!length)
+                    break;
+                position += length;
+                yield bytes;
+            }
+            failed = false;
+        }
+        finally {
+            activeCleanup = undefined;
+            await finishCleanup(closeHandle, failed);
+        }
+    })();
+    const originalReturn = generator.return.bind(generator);
+    generator.return = async (value) => {
+        let cleanupError;
+        try {
+            await activeCleanup?.();
+        }
+        catch (reason) {
+            cleanupError = { reason };
+        }
+        const result = await originalReturn(value);
+        if (cleanupError)
+            throw cleanupError.reason;
+        return result;
+    };
+    return generator;
+}

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

@@ -13,6 +13,7 @@ export declare class ReadOnlyFileSystem implements FileSystem {
     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>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     realpath(path: string, options?: FsOptions): Promise<string>;
     access(path: string, mode?: number, options?: FsOptions): Promise<void>;

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

@@ -122,6 +122,16 @@ export class ReadOnlyFileSystem {
     compareEntry(path, peer, peerPath, options = {}) {
         return compareEntries(this, path, peer, peerPath, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        for await (const entry of this.#filesystem.iterateDirectory(path, options)) {
+            options.signal?.throwIfAborted();
+            yield { name: entry.name, type: entry.type };
+        }
+        options.signal?.throwIfAborted();
+    }
     async readdir(path, options) {
         const limit = options?.maxEntries === undefined ? undefined : directoryEntryLimit(options, path);
         const entries = await this.#filesystem.readdir(path, options);

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

@@ -81,6 +81,7 @@ export declare class RealFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;

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

@@ -413,6 +413,8 @@ export class RealFileSystem {
             throw new FsError("EAGAIN");
     }
     async publishStagedFile(staging, destination, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path: destination });
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
             options.signal?.throwIfAborted();
             if (options.ancestors !== undefined || options.commitGuard !== undefined)
@@ -638,6 +640,33 @@ export class RealFileSystem {
             return fileStat(await native.lstat(target, { bigint: true }));
         });
     }
+    async *iterateDirectory(path, options = {}) {
+        let handle, failed = false;
+        try {
+            // Preserve the acquired handle even if cancellation arrives during open:
+            // the following read admission will observe it and finally will close it.
+            handle = await this.operation("iterateDirectory", path, options, async () => {
+                const target = await this.path(path, options);
+                options.signal?.throwIfAborted();
+                return native.opendir(target, { bufferSize: 1 });
+            }, undefined, true);
+            while (true) {
+                const entry = await this.operation("iterateDirectory", path, options, () => handle.read());
+                if (entry === null)
+                    break;
+                yield { name: entry.name, type: fileType(entry) };
+            }
+        }
+        catch (error) {
+            failed = true;
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            if (handle)
+                await finishCleanup(() => handle.close(), failed);
+        }
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         return this.operation("readdir", path, options, async () => {