@zenfs/core 2.5.6 → 2.5.7

package/dist/index.js

@@ -16,5 +16,4 @@ export { fs };
 export default fs;
 export * from './node/compat.js';
 export * as vfs from './vfs/index.js';
-import $pkg from '../package.json' with { type: 'json' };
-globalThis.__zenfs__ = Object.assign(Object.create(fs), { _version: $pkg.version });
+globalThis.__zenfs__ = Object.create(fs);

package/dist/node/compat.d.ts

@@ -2,3 +2,4 @@ export * from '../vfs/ioctl.js';
 export { chroot, mount, umount } from '../vfs/shared.js';
 export * as xattr from '../vfs/xattr.js';
 export * from './index.js';
+export declare const _version: string;

package/dist/node/compat.js

@@ -4,3 +4,5 @@ export * from '../vfs/ioctl.js';
 export { chroot, mount, umount } from '../vfs/shared.js';
 export * as xattr from '../vfs/xattr.js';
 export * from './index.js';
+import $pkg from '../../package.json' with { type: 'json' };
+export const _version = $pkg.version;

package/dist/node/promises.d.ts

@@ -2,6 +2,7 @@ import type { Abortable } from 'node:events';
 import type * as fs from 'node:fs';
 import type * as promises from 'node:fs/promises';
 import type { Stream } from 'node:stream';
+import type { ByteReadableStream, Transform, Writer } from 'node:stream/iter';
 import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
 import type { V_Context } from '../context.js';
 import type { StreamOptions } from '../internal/filesystem.js';
@@ -157,6 +158,20 @@ export declare class FileHandle implements promises.FileHandle {
      * @param options Options for the writeable stream.
      */
     createWriteStream(options?: promises.CreateWriteStreamOptions): WriteStream;
+    /**
+     * Return the file contents as an async iterable using the `node:stream/iter` pull model.
+     * Reads are performed in `chunkSize`-byte chunks (default 128 KiB).
+     * If transforms are provided, they are applied via `stream/iter`'s `pull()`.
+     * The handle is closed when iteration completes if `autoClose` is set.
+     * @experimental
+     */
+    pull(...transforms: Transform[]): ByteReadableStream;
+    pull(...args: [...transforms: Transform[], options: promises.PullOptions]): ByteReadableStream;
+    /**
+     * Return a `node:stream/iter` writer backed by this file handle.
+     * @experimental
+     */
+    writer(options?: promises.WriterOptions): Writer;
 }
 export declare function rename(this: V_Context, oldPath: fs.PathLike, newPath: fs.PathLike): Promise<void>;
 /**

package/dist/node/promises.js

@@ -69,6 +69,68 @@ import { createInterface } from './readline.js';
 import { BigIntStats, Stats } from './stats.js';
 import { ReadStream, WriteStream } from './streams.js';
 export * as constants from '../constants.js';
+/** Coerce a `stream/iter` transform result into a flat array of `Uint8Array` chunks. */
+async function* normalizeTransformResult(result) {
+    if (result == null)
+        return;
+    if (typeof result == 'string') {
+        yield encodeUTF8(result);
+        return;
+    }
+    if (result instanceof Uint8Array) {
+        yield result;
+        return;
+    }
+    if (ArrayBuffer.isView(result)) {
+        yield new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+        return;
+    }
+    if (result instanceof ArrayBuffer || (typeof SharedArrayBuffer != 'undefined' && result instanceof SharedArrayBuffer)) {
+        yield new Uint8Array(result);
+        return;
+    }
+    if (typeof result[Symbol.asyncIterator] == 'function'
+        || typeof result[Symbol.iterator] == 'function') {
+        for await (const part of result)
+            yield* normalizeTransformResult(part);
+        return;
+    }
+    throw new TypeError('Invalid transform result');
+}
+/** Ponyfill for `node:stream/iter`'s `pull()` transform application */
+async function* applyTransform(source, transform, signal) {
+    const options = { signal: signal };
+    if (typeof transform == 'function') {
+        for await (const chunks of source) {
+            signal?.throwIfAborted();
+            const out = [];
+            for await (const chunk of normalizeTransformResult(await transform(chunks, options)))
+                out.push(chunk);
+            if (out.length)
+                yield out;
+        }
+        const out = [];
+        for await (const chunk of normalizeTransformResult(await transform(null, options)))
+            out.push(chunk);
+        if (out.length)
+            yield out;
+        return;
+    }
+    // Stateful transform: feed it the source (with a trailing `null` to signal EOF).
+    async function* withFlush() {
+        for await (const chunks of source)
+            yield chunks;
+        yield null;
+    }
+    for await (const result of transform.transform(withFlush(), options)) {
+        signal?.throwIfAborted();
+        const out = [];
+        for await (const chunk of normalizeTransformResult(result))
+            out.push(chunk);
+        if (out.length)
+            yield out;
+    }
+}
 export class FileHandle {
     context;
     fd;
@@ -332,6 +394,122 @@ export class FileHandle {
             throw UV('EROFS', 'createWriteStream', this.vfs.path);
         return new WriteStream(options, this);
     }
+    pull(...args) {
+        if (this.vfs.isClosed || this.vfs.flag & constants.O_WRONLY)
+            throw UV('EBADF', 'read', this.vfs.path);
+        // A trailing plain object that is neither a transform function nor a stateful transform is the options bag.
+        const last = args.at(-1);
+        const hasOptions = last != null && typeof last == 'object' && typeof last.transform != 'function';
+        const options = hasOptions ? args.pop() : {};
+        const transforms = args;
+        const { autoClose, start, limit, chunkSize = 131072, signal } = options;
+        const handle = this;
+        async function* source() {
+            let position = typeof start == 'number' ? start : 0;
+            let remaining = typeof limit == 'number' ? limit : Infinity;
+            try {
+                while (remaining > 0) {
+                    signal?.throwIfAborted();
+                    const size = Math.min(chunkSize, remaining);
+                    const buffer = new Uint8Array(size);
+                    const bytesRead = await handle.vfs.read(buffer, 0, size, position);
+                    if (bytesRead <= 0)
+                        break;
+                    position += bytesRead;
+                    remaining -= bytesRead;
+                    yield [buffer.subarray(0, bytesRead)];
+                }
+            }
+            finally {
+                if (autoClose)
+                    await handle.close();
+            }
+        }
+        let stream = source();
+        for (const transform of transforms)
+            stream = applyTransform(stream, transform, signal);
+        return stream;
+    }
+    /**
+     * Return a `node:stream/iter` writer backed by this file handle.
+     * @experimental
+     */
+    writer(options = {}) {
+        if (this.vfs.isClosed)
+            throw UV('EBADF', 'write', this.vfs.path);
+        if (this.vfs.inode.flags & InodeFlags.Immutable)
+            throw UV('EPERM', 'write', this.vfs.path);
+        if (this.vfs.fs.attributes.has('readonly'))
+            throw UV('EROFS', 'write', this.vfs.path);
+        const { autoClose, start, limit, chunkSize = 131072 } = options;
+        const handle = this;
+        let position = typeof start == 'number' ? start : handle.vfs.position;
+        let written = 0;
+        let failed = false;
+        // Tracks whether the writer has been ended or failed, so disposal and `autoClose` don't double-close.
+        let done = false;
+        async function finish() {
+            if (done)
+                return;
+            done = true;
+            if (autoClose)
+                await handle.close();
+        }
+        const toBuffer = (chunk) => typeof chunk == 'string' ? Buffer.from(chunk, 'utf8') : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+        async function writeChunk(chunk) {
+            const buffer = toBuffer(chunk);
+            if (typeof limit == 'number' && written + buffer.byteLength > limit) {
+                throw new RangeError(`Writer limit of ${limit} bytes exceeded`);
+            }
+            const bytesWritten = await handle.vfs.write(buffer, 0, buffer.byteLength, position);
+            position += bytesWritten;
+            written += bytesWritten;
+            handle._emitChange();
+        }
+        return {
+            get desiredSize() {
+                if (failed)
+                    return null;
+                return typeof limit == 'number' ? Math.max(0, limit - written) : chunkSize;
+            },
+            async write(chunk, opts) {
+                opts?.signal?.throwIfAborted();
+                await writeChunk(chunk);
+            },
+            async writev(chunks, opts) {
+                opts?.signal?.throwIfAborted();
+                for (const chunk of chunks)
+                    await writeChunk(chunk);
+            },
+            writeSync() {
+                // Synchronous writes are not supported by the async handle.
+                throw UV('ENOSYS', 'writeSync', handle.vfs.path);
+            },
+            writevSync() {
+                throw UV('ENOSYS', 'writevSync', handle.vfs.path);
+            },
+            async end() {
+                await finish();
+                return written;
+            },
+            endSync() {
+                throw UV('ENOSYS', 'endSync', handle.vfs.path);
+            },
+            fail() {
+                failed = true;
+                void finish();
+            },
+            [Symbol.dispose]() {
+                // `using w = fh.writer()` fails the writer unconditionally.
+                failed = true;
+                void finish();
+            },
+            async [Symbol.asyncDispose]() {
+                // `await using w = fh.writer()` only finishes if still open.
+                await finish();
+            },
+        };
+    }
 }
 export async function rename(oldPath, newPath) {
     await _async.rename.call(this, oldPath, newPath);

package/dist/node/readline.d.ts

@@ -131,5 +131,5 @@ export declare function moveCursor(stream: NodeJS.WritableStream, dx: number, dy
  *
  * This is automatically called by any readline instance on its `input` if the `input` is a terminal. Closing the `readline` instance does not stop the `input` from emitting `'keypress'` events.
  */
-export declare function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface | readline.Interface): void;
+export declare function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: readline.Interface): void;
 export {};

package/dist/vfs/watchers.js

@@ -150,13 +150,15 @@ export function emitChange(context, eventType, filename) {
     if ($)
         filename = join($.root ?? '/', filename);
     filename = normalizePath(filename);
-    // Notify watchers, including ones on parent directories if they are watching recursively
-    for (let path = filename; path != '/'; path = dirname(path)) {
+    // Notify watchers, including ones on parent directories if they are watching recursively.
+    for (let path = filename;; path = dirname(path)) {
         const watchersForPath = watchers.get(path);
-        if (!watchersForPath)
-            continue;
-        for (const watcher of watchersForPath) {
-            watcher.emit('change', eventType, relative.call(watcher._context, path, filename) || basename(filename));
+        if (watchersForPath) {
+            for (const watcher of watchersForPath) {
+                watcher.emit('change', eventType, relative.call(watcher._context, path, filename) || basename(filename));
+            }
         }
+        if (path === '/')
+            break;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.5.6",
+	"version": "2.5.7",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -80,9 +80,10 @@
 		"utilium": "^3.0.0"
 	},
 	"devDependencies": {
+		"@eslint/js": "^10.0.1",
 		"@octokit/action": "^8.0.4",
-		"c8": "^10.1.3",
-		"eslint": "^9.15.0",
+		"c8": "^11.0.0",
+		"eslint": "^10.1.0",
 		"globals": "^17.3.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.1",

package/tests/common/handle-pull.test.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { promises } from '@zenfs/core';
+import assert from 'node:assert/strict';
+import type { FileHandle } from 'node:fs/promises';
+import { suite, test } from 'node:test';
+
+const content = 'hello';
+
+/** Decode a `ByteReadableStream` (`AsyncIterable<Uint8Array[]>`) into a string. */
+async function text(source: AsyncIterable<Uint8Array[]>): Promise<string> {
+	const decoder = new TextDecoder();
+	let out = '';
+	for await (const chunks of source) {
+		for (const chunk of chunks) out += decoder.decode(chunk, { stream: true });
+	}
+	return out + decoder.decode();
+}
+
+// The `asciiUpper` transform from the Node.js `node:stream/iter` docs.
+const asciiUpper = (chunks: Uint8Array[] | null): Uint8Array[] | null => {
+	if (chunks === null) return null;
+	return chunks.map(c => {
+		for (let i = 0; i < c.length; i++) {
+			c[i] -= (c[i] >= 97 && c[i] <= 122 ? 1 : 0) * 32;
+		}
+		return c;
+	});
+};
+
+const handle: FileHandle = await promises.open('./pull.txt', 'w+');
+await handle.writeFile(content);
+
+suite('FileHandle.pull', () => {
+	test('reads file contents', async () => {
+		assert.equal(await text(handle.pull()), content);
+	});
+
+	test('reads a range with start and limit', async () => {
+		assert.equal(await text(handle.pull({ start: 1, limit: 3 })), content.slice(1, 4));
+	});
+
+	test('respects a small chunkSize', async () => {
+		const chunks: number[] = [];
+		for await (const part of handle.pull({ chunkSize: 2 })) {
+			for (const c of part) chunks.push(c.length);
+		}
+		assert.deepEqual(chunks, [2, 2, 1]);
+	});
+
+	test('applies the asciiUpper transform from the Node.js docs', async () => {
+		assert.equal(await text(handle.pull(asciiUpper)), content.toUpperCase()); // 'HELLO'
+	});
+
+	test('autoClose closes the handle', async () => {
+		const fh = await promises.open('./pull-autoclose.txt', 'w+');
+		await fh.writeFile(content);
+		assert.equal(await text(fh.pull({ autoClose: true })), content);
+		await assert.rejects(fh.readFile('utf8'));
+	});
+});
+
+suite('FileHandle.writer', () => {
+	test('writes data backed by the handle', async () => {
+		const fh = await promises.open('./writer.txt', 'w+');
+		const w = fh.writer();
+		await w.write('Hello!');
+		assert.equal(await w.end(), 6);
+		assert.equal(await fh.readFile('utf8'), 'Hello!');
+		await fh.close();
+	});
+
+	test('limit rejects oversized writes', async () => {
+		const fh = await promises.open('./writer-limit.txt', 'w+');
+		const w = fh.writer({ limit: 4 });
+		await assert.rejects(w.write('too long'), RangeError);
+		await fh.close();
+	});
+
+	test('autoClose closes the handle on end', async () => {
+		const fh = await promises.open('./writer-autoclose.txt', 'w+');
+		using w = fh.writer({ autoClose: true });
+		await w.write('bye');
+		await w.end();
+		await assert.rejects(fh.readFile('utf8'));
+	});
+});

package/tests/fs/watch.test.ts

@@ -156,4 +156,23 @@ suite('Watch', () => {
 		await watcher.return!();
 		await promise;
 	});
+
+	test('watch("/") receives events for files under root #293', async () => {
+		// Regression: emitChange previously exited its parent-walk before
+		// checking watchers.get('/'), so a watcher registered on '/' never fired.
+		const { promise, resolve } = Promise.withResolvers<[string, string]>();
+
+		using watcher = fs.watch('/', (eventType, filename) => {
+			resolve([eventType, filename]);
+		});
+
+		await fs.promises.writeFile('/watch-root-file.txt', 'x');
+
+		const [eventType, filename] = await Promise.race([
+			promise,
+			new Promise<[string, string]>((_, reject) => setTimeout(() => reject(new Error('watch("/") timed out')), 1000)),
+		]);
+		assert.equal(eventType, 'change');
+		assert.equal(filename, 'watch-root-file.txt');
+	});
 });