@slopware/sloppy-darwin-arm64 0.1.0-alpha.0

package/stdlib/sloppy/fs.js

@@ -0,0 +1,795 @@
+import { isPlainObject } from "./internal/validation.js";
+import {
+    CancelledError,
+    InvalidDeadlineError,
+    Time,
+    TimeoutError,
+} from "./time.js";
+import { Text } from "./codec.js";
+
+const MAX_TIMEOUT_MS = 0xffffffff;
+
+function nativeFsBridge(operation) {
+    const bridge = globalThis.__sloppy?.fs ?? null;
+
+    if (bridge === null) {
+        throw new Error(`SLOPPY_E_UNAVAILABLE_RUNTIME_FEATURE: runtime feature stdlib.fs is inactive or unavailable
+
+Feature:
+  stdlib.fs
+
+Operation:
+  ${operation}
+
+Reason:
+  The active Sloppy Plan did not enable the __sloppy.fs V8 intrinsic namespace.`);
+    }
+
+    return bridge;
+}
+
+function validatePath(path, operationLabel) {
+    if (typeof path !== "string" || path.length === 0 || path.includes("\0")) {
+        throw new TypeError(`${operationLabel} path must be a non-empty string without NUL.`);
+    }
+    return path;
+}
+
+function validateBytes(value, operation) {
+    if (!(value instanceof Uint8Array)) {
+        throw new TypeError(`Sloppy File.${operation} bytes must be a Uint8Array.`);
+    }
+    return value;
+}
+
+function validateCopyMoveOptions(options) {
+    if (options === undefined) {
+        return Object.freeze({ overwrite: false });
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy File copy/move options must be a plain object.");
+    }
+    const overwrite = options.overwrite ?? false;
+    if (typeof overwrite !== "boolean") {
+        throw new TypeError("Sloppy File overwrite option must be boolean.");
+    }
+    return Object.freeze({ overwrite });
+}
+
+function validateRecursiveOptions(options) {
+    if (options === undefined) {
+        return Object.freeze({ recursive: false });
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy Directory options must be a plain object.");
+    }
+    const recursive = options.recursive ?? false;
+    if (typeof recursive !== "boolean") {
+        throw new TypeError("Sloppy Directory recursive option must be boolean.");
+    }
+    return Object.freeze({ recursive });
+}
+
+function validateOpenOptions(options) {
+    if (options === undefined) {
+        return Object.freeze({ access: "read", create: false });
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy File.open options must be a plain object.");
+    }
+    const access = options.access ?? "read";
+    const create = options.create ?? access !== "read";
+    if (!["read", "write", "readwrite", "append"].includes(access)) {
+        throw new TypeError("Sloppy File.open access must be read, write, readwrite, or append.");
+    }
+    if (typeof create !== "boolean") {
+        throw new TypeError("Sloppy File.open create option must be boolean.");
+    }
+    return Object.freeze({ access, create });
+}
+
+function validateWatchOptions(options, directory) {
+    if (options === undefined) {
+        return Object.freeze({ recursive: false, queueCapacity: 16, snapshotCapacity: directory ? 128 : 1 });
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy filesystem watch options must be a plain object.");
+    }
+    const recursive = options.recursive ?? false;
+    const queueCapacity = options.queueCapacity ?? 16;
+    const snapshotCapacity = options.snapshotCapacity ?? (directory ? 128 : 1);
+    if (typeof recursive !== "boolean") {
+        throw new TypeError("Sloppy filesystem watch recursive option must be boolean.");
+    }
+    if (!Number.isInteger(queueCapacity) || queueCapacity < 1 || queueCapacity > 256) {
+        throw new TypeError("Sloppy filesystem watch queueCapacity must be 1..256.");
+    }
+    if (!Number.isInteger(snapshotCapacity) || snapshotCapacity < 1 || snapshotCapacity > 1024) {
+        throw new TypeError("Sloppy filesystem watch snapshotCapacity must be 1..1024.");
+    }
+    return Object.freeze({ recursive, queueCapacity, snapshotCapacity });
+}
+
+function validateTempPrefix(options, operation) {
+    const prefix = options?.prefix ?? "sloppy-";
+    if (typeof prefix !== "string" || prefix.length === 0 || prefix.includes("\0")) {
+        throw new TypeError(`${operation} prefix must be a non-empty string without NUL.`);
+    }
+    return prefix;
+}
+
+function stringifyJson(value, options) {
+    if (options === undefined) {
+        return JSON.stringify(value);
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy File.writeJson options must be a plain object.");
+    }
+    const indent = options.indent ?? undefined;
+    if (
+        indent !== undefined
+        && (!Number.isInteger(indent) || indent < 0 || indent > 10)
+    ) {
+        throw new TypeError("Sloppy File.writeJson indent must be an integer from 0 to 10.");
+    }
+    return JSON.stringify(value, null, indent);
+}
+
+function shouldAtomic(options) {
+    if (options === undefined) {
+        return false;
+    }
+    if (!isPlainObject(options)) {
+        throw new TypeError("Sloppy File write options must be a plain object.");
+    }
+    const atomic = options.atomic ?? false;
+    if (typeof atomic !== "boolean") {
+        throw new TypeError("Sloppy File atomic option must be boolean.");
+    }
+    return atomic;
+}
+
+function isCancellationSignal(value) {
+    return (
+        value !== null &&
+        typeof value === "object" &&
+        typeof value.aborted === "boolean" &&
+        ("reason" in value || typeof value.addEventListener === "function")
+    );
+}
+
+function subscribeCancellation(signal, listener) {
+    if (!isCancellationSignal(signal)) {
+        return () => {};
+    }
+    if (signal.aborted) {
+        listener(signal.reason);
+        return () => {};
+    }
+    if (typeof signal._subscribe === "function") {
+        return signal._subscribe(listener);
+    }
+    if (typeof signal.addEventListener === "function") {
+        const wrapped = () => listener(signal.reason);
+        signal.addEventListener("abort", wrapped);
+        return () => signal.removeEventListener?.("abort", wrapped);
+    }
+    return () => {};
+}
+
+function cancelledError(reason = undefined) {
+    return reason instanceof CancelledError
+        ? reason
+        : new CancelledError("Sloppy filesystem operation was cancelled.", { reason });
+}
+
+function validateTimeoutMs(value, operation) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_TIMEOUT_MS) {
+        throw new InvalidDeadlineError(
+            `${operation} timeoutMs must be a finite non-negative number no greater than ${MAX_TIMEOUT_MS}.`,
+        );
+    }
+    return Math.ceil(value);
+}
+
+function createTimeoutBudgetOptions(options, operation) {
+    const timeoutMs = validateTimeoutMs(options?.timeoutMs, operation);
+    if (timeoutMs === undefined) {
+        return () => options;
+    }
+    const expiresAtMs = Date.now() + timeoutMs;
+    return () => ({
+        ...options,
+        timeoutMs: Math.max(0, expiresAtMs - Date.now()),
+    });
+}
+
+function isTimeTerminalError(error) {
+    return (
+        error instanceof CancelledError ||
+        error instanceof TimeoutError ||
+        error?.name === "AbortError" ||
+        error?.name === "CancelledError" ||
+        error?.name === "TimeoutError"
+    );
+}
+
+function deadlineRemainingMs(deadline) {
+    if (deadline === undefined || deadline === null) {
+        return Infinity;
+    }
+    if (typeof deadline.remainingMs !== "function") {
+        throw new InvalidDeadlineError(
+            "Filesystem operation deadline must come from Deadline.after, Deadline.at, or Deadline.never.",
+        );
+    }
+    return deadline.remainingMs();
+}
+
+function raceFilesystemCancellation(promise, signal) {
+    if (!isCancellationSignal(signal)) {
+        return promise;
+    }
+    if (signal.aborted) {
+        return Promise.reject(cancelledError(signal.reason));
+    }
+    return new Promise((resolve, reject) => {
+        const cleanup = subscribeCancellation(signal, (reason) => {
+            cleanup();
+            reject(cancelledError(reason));
+        });
+        promise.then(
+            (value) => {
+                cleanup();
+                resolve(value);
+            },
+            (error) => {
+                cleanup();
+                reject(error);
+            },
+        );
+    });
+}
+
+function validateTimeOptions(options, operation) {
+    if (options !== undefined && !isPlainObject(options)) {
+        throw new TypeError(`${operation} options must be a plain object.`);
+    }
+}
+
+function applyTimeOptions(createPromise, options, operation) {
+    validateTimeOptions(options, operation);
+    const signal = options?.signal;
+    const timeoutMs = validateTimeoutMs(options?.timeoutMs, operation);
+    const deadline = options?.deadline;
+    if (isCancellationSignal(signal) && signal.aborted) {
+        return Promise.reject(cancelledError(signal.reason));
+    }
+    const deadlineMs = deadlineRemainingMs(deadline);
+    if (timeoutMs === 0 || deadlineMs <= 0) {
+        return Time.timeout(Promise.resolve(), { afterMs: timeoutMs, deadline });
+    }
+    const promise = createPromise();
+    if (timeoutMs !== undefined || deadlineMs !== Infinity) {
+        return Time.timeout(Promise.resolve(promise), {
+            afterMs: timeoutMs,
+            deadline,
+            signal,
+        });
+    }
+    return raceFilesystemCancellation(Promise.resolve(promise), signal);
+}
+
+const File = Object.freeze({
+    readText(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("readText").readText(validatePath(path, "Sloppy File.readText")),
+            options,
+            "File.readText",
+        );
+    },
+
+    readBytes(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("readBytes").readBytes(validatePath(path, "Sloppy File.readBytes")),
+            options,
+            "File.readBytes",
+        );
+    },
+
+    async readJson(path, options) {
+        return JSON.parse(await File.readText(path, options));
+    },
+
+    writeText(path, text, options) {
+        if (typeof text !== "string") {
+            throw new TypeError("Sloppy File.writeText text must be a string.");
+        }
+        if (shouldAtomic(options)) {
+            return applyTimeOptions(
+                () => nativeFsBridge("atomicWriteText").atomicWriteText(validatePath(path, "Sloppy File.writeText"), text),
+                options,
+                "File.writeText",
+            );
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("writeText").writeText(validatePath(path, "Sloppy File.writeText"), text),
+            options,
+            "File.writeText",
+        );
+    },
+
+    writeBytes(path, bytes, options) {
+        const checked = validateBytes(bytes, "writeBytes");
+        if (shouldAtomic(options)) {
+            return applyTimeOptions(
+                () => nativeFsBridge("atomicWriteBytes").atomicWriteBytes(validatePath(path, "Sloppy File.writeBytes"), checked),
+                options,
+                "File.writeBytes",
+            );
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("writeBytes").writeBytes(
+                validatePath(path, "Sloppy File.writeBytes"),
+                checked,
+            ),
+            options,
+            "File.writeBytes",
+        );
+    },
+
+    writeJson(path, value, options) {
+        return File.writeText(path, stringifyJson(value, options), options);
+    },
+
+    appendText(path, text, options) {
+        if (typeof text !== "string") {
+            throw new TypeError("Sloppy File.appendText text must be a string.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("appendText").appendText(validatePath(path, "Sloppy File.appendText"), text),
+            options,
+            "File.appendText",
+        );
+    },
+
+    appendBytes(path, bytes, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("appendBytes").appendBytes(
+                validatePath(path, "Sloppy File.appendBytes"),
+                validateBytes(bytes, "appendBytes"),
+            ),
+            options,
+            "File.appendBytes",
+        );
+    },
+
+    exists(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("exists").exists(validatePath(path, "Sloppy File.exists")),
+            options,
+            "File.exists",
+        );
+    },
+
+    stat(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("stat").stat(validatePath(path, "Sloppy File.stat")),
+            options,
+            "File.stat",
+        );
+    },
+
+    copy(fromPath, toPath, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("copy").copy(
+                validatePath(fromPath, "Sloppy File.copy"),
+                validatePath(toPath, "Sloppy File.copy"),
+                validateCopyMoveOptions(options),
+            ),
+            options,
+            "File.copy",
+        );
+    },
+
+    move(fromPath, toPath, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("move").move(
+                validatePath(fromPath, "Sloppy File.move"),
+                validatePath(toPath, "Sloppy File.move"),
+                validateCopyMoveOptions(options),
+            ),
+            options,
+            "File.move",
+        );
+    },
+
+    delete(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("delete").delete(validatePath(path, "Sloppy File.delete")),
+            options,
+            "File.delete",
+        );
+    },
+
+    async open(path, options) {
+        const checked = validateOpenOptions(options);
+        const id = await applyTimeOptions(
+            () => nativeFsBridge("openHandle").openHandle(
+                validatePath(path, "Sloppy File.open"),
+                checked.access,
+                checked.create,
+            ),
+            options,
+            "File.open",
+        );
+        return new FileHandle(id);
+    },
+
+    async watch(path, options) {
+        const checked = validateWatchOptions(options, false);
+        const id = await applyTimeOptions(
+            () => nativeFsBridge("watch").watch(validatePath(path, "Sloppy File.watch"), false, checked),
+            options,
+            "File.watch",
+        );
+        return new FileWatcher(id);
+    },
+
+    createSymlink(targetPath, linkPath, options) {
+        const directory = options?.directory ?? false;
+        if (typeof directory !== "boolean") {
+            throw new TypeError("Sloppy File.createSymlink directory option must be boolean.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("symlink").symlink(
+                validatePath(targetPath, "Sloppy File.createSymlink"),
+                validatePath(linkPath, "Sloppy File.createSymlink"),
+                directory,
+            ),
+            options,
+            "File.createSymlink",
+        );
+    },
+
+    readLink(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("readLink").readLink(validatePath(path, "Sloppy File.readLink")),
+            options,
+            "File.readLink",
+        );
+    },
+
+    createTemp(directory, options) {
+        const prefix = validateTempPrefix(options, "Sloppy File.createTemp");
+        return applyTimeOptions(
+            () => nativeFsBridge("tempFile").tempFile(validatePath(directory, "Sloppy File.createTemp"), prefix),
+            options,
+            "File.createTemp",
+        );
+    },
+});
+
+async function isSymlink(path, options) {
+    try {
+        await File.readLink(path, options);
+        return true;
+    }
+    catch (error) {
+        if (isTimeTerminalError(error)) {
+            throw error;
+        }
+        return false;
+    }
+}
+
+const Directory = Object.freeze({
+    create(path, options) {
+        const checked = validateRecursiveOptions(options);
+        return applyTimeOptions(
+            () => nativeFsBridge("directoryCreate").directoryCreate(
+                validatePath(path, "Sloppy Directory.create"),
+                checked.recursive,
+            ),
+            options,
+            "Directory.create",
+        );
+    },
+
+    list(path, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("directoryList").directoryList(validatePath(path, "Sloppy Directory.list")),
+            options,
+            "Directory.list",
+        );
+    },
+
+    async *walk(path, options) {
+        const followSymlinks = options?.followSymlinks ?? false;
+        if (typeof followSymlinks !== "boolean") {
+            throw new TypeError("Sloppy Directory.walk followSymlinks option must be boolean.");
+        }
+        const optionsForStep = createTimeoutBudgetOptions(options, "Directory.walk");
+        for (const entry of await Directory.list(path, optionsForStep())) {
+            yield entry;
+            if (entry.kind === "directory") {
+                const child = `${path.replace(/[\\/]$/, "")}/${entry.name}`;
+                if (!followSymlinks && await isSymlink(child, optionsForStep())) {
+                    continue;
+                }
+                for await (const nested of Directory.walk(child, {
+                    ...optionsForStep(),
+                    followSymlinks,
+                })) {
+                    yield { ...nested, name: `${entry.name}/${nested.name}` };
+                }
+            }
+        }
+    },
+
+    delete(path, options) {
+        const checked = validateRecursiveOptions(options);
+        return applyTimeOptions(
+            () => nativeFsBridge("directoryDelete").directoryDelete(
+                validatePath(path, "Sloppy Directory.delete"),
+                checked.recursive,
+            ),
+            options,
+            "Directory.delete",
+        );
+    },
+
+    async exists(path, options) {
+        const stat = await File.stat(path, options);
+        return stat.exists && stat.kind === "directory";
+    },
+
+    createTemp(directory, options) {
+        const prefix = validateTempPrefix(options, "Sloppy Directory.createTemp");
+        return applyTimeOptions(
+            () => nativeFsBridge("tempDirectory").tempDirectory(
+                validatePath(directory, "Sloppy Directory.createTemp"),
+                prefix,
+            ),
+            options,
+            "Directory.createTemp",
+        );
+    },
+
+    async watch(path, options) {
+        const checked = validateWatchOptions(options, true);
+        const id = await applyTimeOptions(
+            () => nativeFsBridge("watch").watch(validatePath(path, "Sloppy Directory.watch"), true, checked),
+            options,
+            "Directory.watch",
+        );
+        return new FileWatcher(id);
+    },
+});
+
+const Path = Object.freeze({
+    classify(path) {
+        validatePath(path, "Sloppy Path.classify");
+        if (/^\.[\\/]/.test(path)) {
+            return "project-relative";
+        }
+        if (/^(?:[A-Za-z]:[\\/]|[\\/])/.test(path)) {
+            return "absolute";
+        }
+        if (/^[A-Za-z][A-Za-z0-9_.-]*:[\\/]/.test(path)) {
+            return "named-root";
+        }
+        return "invalid";
+    },
+});
+
+class FileHandle {
+    constructor(id) {
+        this._id = Object.freeze({ slot: id.slot, generation: id.generation });
+    }
+
+    readBytes(maxBytes = 64 * 1024, options) {
+        if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > 1024 * 1024) {
+            throw new TypeError("Sloppy FileHandle.readBytes maxBytes must be 1..1048576.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("handleRead").handleRead(this._id, maxBytes),
+            options,
+            "FileHandle.readBytes",
+        );
+    }
+
+    async readText(maxBytes, options) {
+        const bytes = await this.readBytes(maxBytes, options);
+        return Text.utf8.decode(bytes);
+    }
+
+    writeBytes(bytes, options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("handleWriteBytes").handleWriteBytes(
+                this._id,
+                validateBytes(bytes, "writeBytes"),
+            ),
+            options,
+            "FileHandle.writeBytes",
+        );
+    }
+
+    writeText(text, options) {
+        if (typeof text !== "string") {
+            throw new TypeError("Sloppy FileHandle.writeText text must be a string.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("handleWriteText").handleWriteText(this._id, text),
+            options,
+            "FileHandle.writeText",
+        );
+    }
+
+    seek(offset, origin = "start", options) {
+        if (!Number.isInteger(offset) || !["start", "current", "end"].includes(origin)) {
+            throw new TypeError("Sloppy FileHandle.seek requires an integer offset and valid origin.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("handleSeek").handleSeek(this._id, offset, origin),
+            options,
+            "FileHandle.seek",
+        );
+    }
+
+    truncate(size, options) {
+        if (!Number.isInteger(size) || size < 0) {
+            throw new TypeError("Sloppy FileHandle.truncate size must be a non-negative integer.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("handleTruncate").handleTruncate(this._id, size),
+            options,
+            "FileHandle.truncate",
+        );
+    }
+
+    flush(options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("handleFlush").handleFlush(this._id),
+            options,
+            "FileHandle.flush",
+        );
+    }
+
+    sync(options) {
+        return applyTimeOptions(
+            () => nativeFsBridge("handleSync").handleSync(this._id),
+            options,
+            "FileHandle.sync",
+        );
+    }
+
+    close() {
+        return nativeFsBridge("handleClose").handleClose(this._id);
+    }
+
+    async *readChunks(options) {
+        const chunkSize = options?.chunkSize ?? 64 * 1024;
+        const optionsForRead = createTimeoutBudgetOptions(options, "FileHandle.readChunks");
+        for (;;) {
+            const chunk = await this.readBytes(chunkSize, optionsForRead());
+            if (chunk.byteLength === 0) {
+                return;
+            }
+            yield chunk;
+        }
+    }
+
+    async *readLines(options) {
+        const decoder = Text.utf8.decoder();
+        const newline = options?.newline ?? "\n";
+        const maxLineLength = options?.maxLineLength ?? 1024 * 1024;
+        let buffered = "";
+        const limitError = () => {
+            const error = new Error(
+                "SLOPPY_E_LIMIT_EXCEEDED: filesystem line exceeds maxLineLength.",
+            );
+            error.code = "SLOPPY_E_LIMIT_EXCEEDED";
+            return error;
+        };
+        const shouldNormalizeCarriageReturn = newline === "\n" || newline === "\r\n";
+        const normalizeLine = (line) => shouldNormalizeCarriageReturn ? line.replace(/\r$/, "") : line;
+        const pendingDelimiterCarryLength = () => {
+            const maxCarry = Math.min(buffered.length, newline.length - 1);
+            for (let length = maxCarry; length > 0; length -= 1) {
+                if (buffered.endsWith(newline.slice(0, length))) {
+                    return length;
+                }
+            }
+            return 0;
+        };
+        const checkPendingLineLength = () => {
+            const carryLength = pendingDelimiterCarryLength();
+            const pendingLine = carryLength > 0
+                ? buffered.slice(0, buffered.length - carryLength)
+                : buffered;
+            if (normalizeLine(pendingLine).length > maxLineLength) {
+                throw limitError();
+            }
+        };
+        if (typeof newline !== "string" || newline.length === 0) {
+            throw new TypeError(
+                "Sloppy FileHandle.readLines newline must be a non-empty string.",
+            );
+        }
+        for await (const chunk of this.readChunks(options)) {
+            buffered += decoder.decode(chunk, { stream: true });
+            let index = buffered.indexOf(newline);
+            while (index !== -1) {
+                const line = normalizeLine(buffered.slice(0, index));
+                if (line.length > maxLineLength) {
+                    throw limitError();
+                }
+                yield line;
+                buffered = buffered.slice(index + newline.length);
+                index = buffered.indexOf(newline);
+            }
+            checkPendingLineLength();
+        }
+        buffered += decoder.finish();
+        const trailingLine = normalizeLine(buffered);
+        if (trailingLine.length > maxLineLength) {
+            throw limitError();
+        }
+        if (buffered.length !== 0) {
+            yield trailingLine;
+        }
+    }
+}
+
+class FileWatcher {
+    constructor(id) {
+        this._id = Object.freeze({ slot: id.slot, generation: id.generation });
+        this._closed = false;
+    }
+
+    async nextEvent(options) {
+        if (this._closed) {
+            return null;
+        }
+        if (options !== undefined && !isPlainObject(options)) {
+            throw new TypeError("Sloppy FileWatcher.nextEvent options must be a plain object.");
+        }
+        return applyTimeOptions(
+            () => nativeFsBridge("watchNext").watchNext(this._id),
+            options,
+            "FileWatcher.nextEvent",
+        );
+    }
+
+    async close() {
+        if (this._closed) {
+            return;
+        }
+        this._closed = true;
+        await nativeFsBridge("watchClose").watchClose(this._id);
+    }
+
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                while (!this._closed) {
+                    const event = await this.nextEvent();
+                    if (event !== null) {
+                        return { done: false, value: event };
+                    }
+                }
+                return { done: true, value: undefined };
+            },
+            return: async () => {
+                await this.close();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+}
+
+export { Directory, File, FileHandle, FileWatcher, Path };