@zenfs/core 2.7.1 → 2.7.3-newstreams.0

package/README.md

@@ -43,6 +43,9 @@ Your financial support would go a long way toward improving ZenFS and its commun
 
 ## Usage
 
+> [!IMPORTANT]
+> **[Check out the ZenFS docs!](https://zenfs.dev/start/usage/)**
+
 ```js
 import { fs } from '@zenfs/core'; // You can also use the default export
 
@@ -52,15 +55,9 @@ const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
 ```
 
-#### Using different and/or multiple backends
-
-A single `InMemory` backend is created by default, mounted on `/`.
-
-You can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using the `configure` function.
-
-You can use multiple backends by passing an object to `configure` which maps paths to file systems.
-
-The following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB to `/home`. Note that `/` has the default in-memory backend.
+A single `InMemory` backend is created by default, mounted on `/`. To use different backends, and to
+mount more than one, configure ZenFS with `configure`. This mounts a zip file to `/mnt/zip`,
+in-memory storage to `/tmp`, and IndexedDB to `/home`:
 
 ```js
 import { configure, InMemory } from '@zenfs/core';
@@ -78,110 +75,16 @@ await configure({
 });
 ```
 
-Note that while you aren't required to use absolute paths for the keys of `mounts`, it is a good practice to do so.
-
-> [!TIP]
-> When configuring a mount point, you can pass in
->
-> 1. A `Backend` object, if the backend has no required options
-> 2. An object that has the options accepted by the backend and a `backend` property which is a `Backend` object
-> 3. A `FileSystem` instance
-
-Here is an example that mounts the `WebStorage` backend from `@zenfs/dom` on `/`:
-
-```js
-import { configureSingle, fs } from '@zenfs/core';
-import { WebStorage } from '@zenfs/dom';
-
-await configureSingle({ backend: WebStorage });
-
-if (!fs.existsSync('/test.txt')) {
-	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
-}
-
-const contents = fs.readFileSync('/test.txt', 'utf-8');
-console.log(contents);
-```
-
-#### FS Promises
-
-The FS promises API is exposed as `promises`.
-
-```js
-import { configureSingle } from '@zenfs/core';
-import { exists, writeFile } from '@zenfs/core/promises';
-import { IndexedDB } from '@zenfs/dom';
-
-await configureSingle({ backend: IndexedDB });
-
-const exists = await exists('/myfile.txt');
-if (!exists) {
-	await writeFile('/myfile.txt', 'Lots of persistent data');
-}
-```
-
-> [!NOTE]
-> You can import the promises API using:
->
-> 1. Exports from `@zenfs/core/promises`
-> 2. The `promises` export from `@zenfs/core`
-> 3. `fs.promises` on the exported `fs` from `@zenfs/core`.
+The `fs/promises` API is available from `@zenfs/core/promises`, as the `promises` export, or as
+`fs.promises`.
 
-#### Mounting and unmounting, creating backends
-
-If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `resolveMountConfig` with it.
-
-You can then mount and unmount the backend instance by using `mount` and `umount`.
-
-```js
-import { configure, resolveMountConfig, InMemory } from '@zenfs/core';
-import { IndexedDB } from '@zenfs/dom';
-import { Zip } from '@zenfs/archives';
-
-await configure({
-	mounts: {
-		'/tmp': InMemory,
-		'/home': IndexedDB,
-	},
-});
-
-fs.mkdirSync('/mnt/zip', { recursive: true });
-
-const res = await fetch('mydata.zip');
-const zipfs = await resolveMountConfig({ backend: Zip, data: await res.arrayBuffer() });
-fs.mount('/mnt/zip', zipfs);
-
-// do stuff with the mounted zip
-
-fs.umount('/mnt/zip'); // finished using the zip
-```
-
-> [!CAUTION]
-> Instances of backends follow the _internal_ API. You should never use a backend's methods unless you are extending a backend.
-
-### Devices and device files
-
-ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out the [Devices and Device Drivers](https://zenfs.dev/core/documents/Devices_and_Device_Drivers) documentation for more information.
-
-## `node:*` emulation
-
-ZenFS also includes emulation of some other `node:` modules for various reasons, importable from `@zenfs/core/<name>`:
-
-- `node:path`
-- `node:readline`
-
-For example:
-
-```ts
-import * as path from '@zenfs/core/path';
-```
+For the full usage guide, see **[the documentation](https://zenfs.dev/start/usage/)**.
+This includes mounting at runtime, contexts and permissions, devices, and the `node:*`module emulation.
 
 ## Bundling
 
 ZenFS exports a drop-in for Node's `fs` module, so you can use it for your bundler of preference using the default export.
-
-> [!IMPORTANT]
-> See [COPYING.md](./COPYING.md)
+See [COPYING.md](./COPYING.md) for more info.
 
 ## Sponsors
 

package/dist/backends/fetch.d.ts

@@ -47,6 +47,8 @@ export declare class FetchFS extends IndexFS {
     protected _async(p: Promise<unknown>): void;
     constructor(index: Index, baseUrl: string, requestInit?: RequestInit, remoteWrite?: boolean | undefined);
     protected resize(path: string, inode: Inode, oldSize: number): Promise<void> | void;
+    protected _create(path: string, inode: Inode): Promise<void>;
+    protected _createSync(path: string, inode: Inode): void;
     touch(path: string, metadata: InodeLike): Promise<void>;
     touchSync(path: string, metadata: InodeLike): void;
     protected remove(path: string): Promise<void>;

package/dist/backends/fetch.js

@@ -63,6 +63,14 @@ export class FetchFS extends IndexFS {
         if (this.remoteWrite)
             return requests.set(url, zeroes, { offset: oldSize, warn }, this.requestInit).catch(parseError);
     }
+    async _create(path, inode) {
+        await requests
+            .set(this.baseUrl + path, new Uint8Array(inode.size), { warn, cacheOnly: !this.remoteWrite, method: 'PUT' }, this.requestInit)
+            .catch(parseError);
+    }
+    _createSync(path, inode) {
+        this._async(this._create(path, inode));
+    }
     async touch(path, metadata) {
         const inode = this.index.get(path) ?? _throw(withErrno('ENOENT'));
         const oldSize = inode.size;
@@ -81,7 +89,7 @@ export class FetchFS extends IndexFS {
         await requests.remove(this.baseUrl + path, { warn, cacheOnly: !this.remoteWrite }, this.requestInit);
     }
     removeSync(path) {
-        this._async(requests.remove(this.baseUrl + path, { warn, cacheOnly: !this.remoteWrite }, this.requestInit));
+        this._async(this.remove(path));
     }
     async read(path, buffer, offset = 0, end) {
         const inode = this.index.get(path);

package/dist/config.d.ts

@@ -56,6 +56,8 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
     /**
      * Whether to automatically add normal Linux devices
      * @default false
+     * @deprecated Use `@zenfs/linux`!
+     * @todo [breaking] remove
      */
     addDevices: boolean;
     /**
@@ -97,6 +99,8 @@ export declare function configureSingle<T extends Backend>(configuration: MountC
 export declare function configureSingleSync<T extends Backend>(configuration: MountConfiguration<T>): void;
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare function addDevice(driver: DeviceDriver, options?: object): Device;
 /**

package/dist/config.js

@@ -189,6 +189,8 @@ function mountWithMkdirSync(path, fs) {
 }
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export function addDevice(driver, options) {
     const devfs = defaultContext.mounts.get('/dev');

package/dist/context.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { UV } from 'kerium';
 import { bindFunctions } from 'utilium';
-import { contextOf, createChildContext } from './internal/contexts.js';
+import { contextOf, createChildContext, defaultContext } from './internal/contexts.js';
 import * as fs from './node/index.js';
 import * as path from './path.js';
 import * as xattr from './vfs/xattr.js';
@@ -17,9 +17,9 @@ export const boundContexts = new Map();
  * @category Contexts
  */
 export function bindContext(init = {}) {
-    const $ = contextOf(this);
-    if (!fs.statSync.call(this, $.root).isDirectory())
-        throw UV('ENOTDIR', { syscall: 'chroot', path: $.root });
+    const $ = contextOf(this), parent = $.parent || defaultContext;
+    if (!fs.statSync.call(parent, parent.root).isDirectory())
+        throw UV('ENOTDIR', { syscall: 'chroot', path: parent.root });
     const ctx = createChildContext($, init);
     const bound = Object.assign(ctx, {
         fs: {

package/dist/internal/contexts.js

@@ -46,7 +46,7 @@ let _nextId = 2;
  */
 export function createChildContext(parent, init = {}) {
     assertContext(parent);
-    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts = Object.fromEntries(parent.mounts), } = init;
+    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts } = init;
     const ctx = {
         [kIsContext]: true,
         id: _nextId++,
@@ -56,7 +56,7 @@ export function createChildContext(parent, init = {}) {
         descriptors: new Map(),
         parent: parent,
         children: [],
-        mounts: new Map(Object.entries(mounts)),
+        mounts: mounts ? new Map(Object.entries(mounts)) : parent.mounts,
     };
     Object.defineProperties(ctx, {
         id: { configurable: false, writable: false },

package/dist/internal/devices.d.ts

@@ -4,10 +4,11 @@ import type { CreationOptions } from './filesystem.js';
 import { Inode, type InodeLike } from './inode.js';
 /**
  * A device
- * @todo Maybe add some other device information, like a UUID?
  * @category Internals
  * @privateRemarks
  * UUIDs were considered, however they don't make sense without an easy mechanism for persistence
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface Device<TData = any> {
     /**
@@ -34,6 +35,8 @@ export interface Device<TData = any> {
 }
 /**
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceInit<TData = any> {
     data?: TData;
@@ -45,6 +48,8 @@ export interface DeviceInit<TData = any> {
 /**
  * A device driver
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceDriver<TData = any> {
     /**
@@ -88,6 +93,8 @@ export interface DeviceDriver<TData = any> {
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
     protected readonly devices: Map<string, Device<any>>;
@@ -132,6 +139,8 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const nullDevice: DeviceDriver;
 /**
@@ -144,6 +153,8 @@ export declare const nullDevice: DeviceDriver;
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const zeroDevice: DeviceDriver;
 /**
@@ -152,6 +163,8 @@ export declare const zeroDevice: DeviceDriver;
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const fullDevice: DeviceDriver;
 /**
@@ -160,12 +173,16 @@ export declare const fullDevice: DeviceDriver;
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const randomDevice: DeviceDriver;
 /**
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const devices: {
     null: DeviceDriver<any>;

package/dist/internal/devices.js

@@ -13,6 +13,8 @@ import { Inode } from './inode.js';
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export class DeviceFS extends StoreFS {
     devices = new Map();
@@ -231,6 +233,8 @@ const emptyBuffer = new Uint8Array();
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const nullDevice = {
     name: 'null',
@@ -255,6 +259,8 @@ export const nullDevice = {
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const zeroDevice = {
     name: 'zero',
@@ -275,6 +281,8 @@ export const zeroDevice = {
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const fullDevice = {
     name: 'full',
@@ -295,6 +303,8 @@ export const fullDevice = {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const randomDevice = {
     name: 'random',
@@ -315,6 +325,8 @@ export const randomDevice = {
  * Simulates the `/dev/console` device.
  * @category Internals
  * @experimental @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 const consoleDevice = {
     name: 'console',
@@ -334,6 +346,8 @@ const consoleDevice = {
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const devices = {
     null: nullDevice,

package/dist/internal/filesystem.d.ts

@@ -117,6 +117,7 @@ export interface StreamOptions {
     start?: number;
     end?: number;
     autoClose?: boolean;
+    chunkSize?: number;
 }
 /**
  * Provides a consistent and easy to use internal API.

package/dist/internal/filesystem.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { withErrno } from 'kerium';
 import { ioctl_default_ops_async, ioctl_default_ops_sync } from './ioctl.js';
-const _chunkSize = 0x1000;
+/** Default bytes per chunk for streamed reads, matching Node's default stream `highWaterMark` */
+const defaultChunkSize = 0x10000;
 /**
  * Provides a consistent and easy to use internal API.
  * Default implementations for `exists` and `existsSync` are included.
@@ -97,17 +98,22 @@ export class FileSystem {
      * @privateRemarks The default implementation of `streamRead` uses "chunked" `read`s
      */
     streamRead(path, options) {
+        const { chunkSize = defaultChunkSize } = options;
+        let offset = options.start ?? 0;
+        let end = options.end;
         return new ReadableStream({
-            start: async (controller) => {
-                const { size } = await this.stat(path);
-                const { start = 0, end = size } = options;
-                for (let offset = start; offset < end; offset += _chunkSize) {
-                    const bytesRead = offset + _chunkSize > end ? end - offset : _chunkSize;
-                    const buffer = new Uint8Array(bytesRead);
-                    await this.read(path, buffer, offset, offset + bytesRead).catch(controller.error.bind(controller));
-                    controller.enqueue(buffer);
+            pull: async (controller) => {
+                end ??= (await this.stat(path)).size;
+                if (offset >= end) {
+                    controller.close();
+                    return;
                 }
-                controller.close();
+                const buffer = new Uint8Array(Math.min(chunkSize, end - offset));
+                await this.read(path, buffer, offset, offset + buffer.byteLength);
+                offset += buffer.byteLength;
+                controller.enqueue(buffer);
+                if (offset >= end)
+                    controller.close();
             },
             type: 'bytes',
         });

package/dist/internal/index_fs.d.ts

@@ -5,6 +5,8 @@ import { Inode, type InodeLike } from './inode.js';
  * A file system that uses an `Index` for metadata.
  * @category Internals
  * @internal
+ *
+ * @todo [breaking] replace the three method `create` system with something more intuitive, e.g. requiring subclasses to implement `createFile`, with this just exposing `create` for convenience.
  */
 export declare abstract class IndexFS extends FileSystem {
     readonly index: Index;
@@ -27,6 +29,10 @@ export declare abstract class IndexFS extends FileSystem {
     unlinkSync(path: string): void;
     rmdir(path: string): Promise<void>;
     rmdirSync(path: string): void;
+    /** Create a new file in the underlying backend */
+    protected _create?(path: string, inode: Inode): Promise<void>;
+    /** Create a new file in the underlying backend */
+    protected _createSync?(path: string, inode: Inode): void;
     protected create(path: string, options: CreationOptions): Inode;
     createFile(path: string, options: CreationOptions): Promise<Inode>;
     createFileSync(path: string, options: CreationOptions): Inode;

package/dist/internal/index_fs.js

@@ -11,6 +11,8 @@ import { Inode } from './inode.js';
  * A file system that uses an `Index` for metadata.
  * @category Internals
  * @internal
+ *
+ * @todo [breaking] replace the three method `create` system with something more intuitive, e.g. requiring subclasses to implement `createFile`, with this just exposing `create` for convenience.
  */
 export class IndexFS extends FileSystem {
     index;
@@ -165,10 +167,26 @@ export class IndexFS extends FileSystem {
         return inode;
     }
     async createFile(path, options) {
-        return this.create(path, { ...options, mode: options.mode | S_IFREG });
+        const inode = this.create(path, { ...options, mode: options.mode | S_IFREG });
+        try {
+            await this._create?.(path, inode);
+            return inode;
+        }
+        catch (e) {
+            this.index.delete(path);
+            throw e;
+        }
     }
     createFileSync(path, options) {
-        return this.create(path, { ...options, mode: options.mode | S_IFREG });
+        const inode = this.create(path, { ...options, mode: options.mode | S_IFREG });
+        try {
+            this._createSync?.(path, inode);
+            return inode;
+        }
+        catch (e) {
+            this.index.delete(path);
+            throw e;
+        }
     }
     async mkdir(path, options) {
         options = { ...options, mode: options.mode | S_IFDIR };

package/dist/mixins/async.d.ts

@@ -1,3 +1,4 @@
+import type { Semaphore } from 'kerium/locks';
 import type { FileSystem } from '../internal/filesystem.js';
 import { type _SyncFSKeys, type AsyncFSMethods, type Mixin } from './shared.js';
 /**
@@ -12,13 +13,11 @@ export type AsyncOperation = {
  * @category Internals
  */
 export interface AsyncMixin extends Pick<FileSystem, Exclude<_SyncFSKeys, 'existsSync'>> {
-    /**
-     * @internal @protected
-     */
+    /** @internal @protected */
     _sync?: FileSystem;
-    /**
-     * @deprecated Use {@link sync | `sync`} instead
-     */
+    /** Restrict how many files can be copied across at once @internal @protected */
+    _crossCopySemaphore?: Semaphore;
+    /** @deprecated Use {@link sync | `sync`} instead */
     queueDone(): Promise<void>;
     ready(): Promise<void>;
     sync(): Promise<void>;

package/dist/mixins/async.js

@@ -1,3 +1,55 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { withErrno } from 'kerium';
 import { crit, debug, err } from 'kerium/log';
@@ -164,19 +216,30 @@ export function Async(FS) {
                 },
             });
         }
-        /**
-         * @internal
-         */
+        /** @internal @protected */
+        _crossCopySemaphore;
+        /** @internal */
         async crossCopy(path) {
             this.checkSync();
             const stats = await this.stat(path);
             if (!isDirectory(stats)) {
-                this._sync.createFileSync(path, stats);
-                const buffer = new Uint8Array(stats.size);
-                await this.read(path, buffer, 0, stats.size);
-                this._sync.writeSync(path, buffer, 0);
-                this._sync.touchSync(path, stats);
-                return;
+                const env_1 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const _ = __addDisposableResource(env_1, (await this._crossCopySemaphore?.get()) || { [Symbol.dispose]() { } }, false);
+                    this._sync.createFileSync(path, stats);
+                    const buffer = new Uint8Array(stats.size);
+                    await this.read(path, buffer, 0, stats.size);
+                    this._sync.writeSync(path, buffer, 0);
+                    this._sync.touchSync(path, stats);
+                    return;
+                }
+                catch (e_1) {
+                    env_1.error = e_1;
+                    env_1.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_1);
+                }
             }
             if (path !== '/') {
                 this._sync.mkdirSync(path, stats);

package/dist/node/streams.d.ts

@@ -1,10 +1,10 @@
-/// <reference path="../../types/readable-stream.d.ts" preserve="true" />
 import type { Abortable } from 'node:events';
 import type * as fs from 'node:fs';
 import type { CreateReadStreamOptions, CreateWriteStreamOptions } from 'node:fs/promises';
 import type { Callback } from '../utils.js';
 import type { FileHandle } from './promises.js';
-import { Readable, Writable } from 'readable-stream';
+import { Readable } from '@zenfs/streams/readable';
+import { Writable } from '@zenfs/streams/writable';
 interface FSImplementation {
     open?: (...args: unknown[]) => unknown;
     close?: (...args: unknown[]) => unknown;

package/dist/node/streams.js

@@ -1,6 +1,8 @@
+import { eos } from '@zenfs/streams/end-of-stream';
+import { Readable } from '@zenfs/streams/readable';
+import { Writable } from '@zenfs/streams/writable';
 import { Errno, Exception, UV } from 'kerium';
 import { warn } from 'kerium/log';
-import { finished, Readable, Writable } from 'readable-stream';
 /**
  * A ReadStream implementation that wraps an underlying global ReadableStream.
  */
@@ -16,7 +18,11 @@ export class ReadStream extends Readable {
             .then(handle => {
             this._path = handle['vfs'].path;
             // `end` is inclusive for streams, but the internal range is not
-            const internal = handle.readableWebStream({ start: opts.start, end: opts.end === undefined ? undefined : opts.end + 1 });
+            const internal = handle.readableWebStream({
+                start: opts.start,
+                end: opts.end === undefined ? undefined : opts.end + 1,
+                chunkSize: opts.highWaterMark,
+            });
             this.reader = internal.getReader();
             this.pending = false;
         })
@@ -46,7 +52,7 @@ export class ReadStream extends Readable {
      * Closing before the stream has finished reports `ERR_STREAM_PREMATURE_CLOSE`.
      */
     close(callback = () => null) {
-        finished(this, error => callback(error ?? null));
+        eos(this, error => callback(error ?? null));
         this.destroy();
     }
     get path() {

package/dist/node/sync.d.ts

@@ -1,3 +1,4 @@
+import type { BufferView } from 'node:buffer';
 import type * as fs from 'node:fs';
 import type { V_Context } from '../context.js';
 import type { FileContents } from '../vfs/shared.js';
@@ -72,14 +73,14 @@ export declare function lopenSync(this: V_Context, path: fs.PathLike, flag: stri
  * Synchronously reads the entire contents of a file.
  * @option encoding The string encoding for the file contents. Defaults to `null`.
  * @option flag Defaults to `'r'`.
+ * @option buffer A view (or a factory taking the file size) the contents are read into,
+ * instead of allocating a new buffer. It must be large enough to hold the entire file.
  * @returns file contents
  */
-export declare function readFileSync(this: V_Context, path: fs.PathOrFileDescriptor, options?: {
-    flag?: string;
-} | null): NonSharedBuffer;
-export declare function readFileSync(this: V_Context, path: fs.PathOrFileDescriptor, options?: (fs.EncodingOption & {
-    flag?: string;
-}) | BufferEncoding | null): string;
+export declare function readFileSync<T extends NodeJS.ArrayBufferView>(this: V_Context, path: fs.PathOrFileDescriptor, options: fs.ReadFileSyncOptionsWithBuffer<T>): BufferView<T>;
+export declare function readFileSync(this: V_Context, path: fs.PathOrFileDescriptor, options?: fs.ReadFileSyncOptionsWithBufferEncoding | null): NonSharedBuffer;
+export declare function readFileSync(this: V_Context, path: fs.PathOrFileDescriptor, options: fs.ReadFileSyncOptionsWithStringEncoding | BufferEncoding): string;
+export declare function readFileSync(this: V_Context, path: fs.PathOrFileDescriptor, options: fs.ReadFileSyncOptions): string | NonSharedBuffer;
 /**
  * Synchronously writes data to a file, replacing the file if it already exists.
  *

package/dist/node/sync.js

@@ -175,6 +175,22 @@ openSync;
 export function lopenSync(path, flag, mode) {
     return toFD(_sync.open(this, path, { flag, mode, preserveSymlinks: true }));
 }
+/**
+ * Resolves the `buffer` option of `readFileSync` into a buffer covering the first `size` bytes of the view.
+ * @hidden
+ */
+function intoBuffer(into, size) {
+    const isFn = typeof into == 'function';
+    const view = isFn ? into(size) : into;
+    const name = isFn ? 'options.buffer()' : 'options.buffer';
+    if (!ArrayBuffer.isView(view))
+        throw Object.assign(new TypeError(`The "options.buffer" property must be of type function or an instance of Buffer, TypedArray, or DataView. Received ${typeof view}`), { code: 'ERR_INVALID_ARG_TYPE' });
+    if (view.byteLength < size)
+        throw Object.assign(new TypeError(`The property '${name}.byteLength' is smaller than the file size of ${size} bytes. Received ${view.byteLength}`), {
+            code: 'ERR_INVALID_ARG_VALUE',
+        });
+    return Buffer.from(view.buffer, view.byteOffset, size);
+}
 export function readFileSync(path, _options = {}) {
     const env_3 = { stack: [], error: void 0, hasError: false };
     try {
@@ -186,7 +202,8 @@ export function readFileSync(path, _options = {}) {
             ? fromFD(this, path)
             : _sync.open(this, path.toString(), { flag: options.flag, mode: 0o644, preserveSymlinks: false }), false);
         const { size } = file.stat();
-        const data = Buffer.alloc(size);
+        const into = typeof _options == 'object' && _options !== null ? _options.buffer : undefined;
+        const data = into === undefined ? Buffer.alloc(size) : intoBuffer(into, size);
         file.readSync(data, 0, size, 0);
         return options.encoding ? data.toString(options.encoding) : data;
     }
@@ -584,7 +601,7 @@ export function copyFileSync(source, destination, flags) {
     destination = normalizePath.call(this, destination);
     if (flags && flags & constants.COPYFILE_EXCL && existsSync.call(this, destination))
         throw UV('EEXIST', 'copyFile', destination);
-    writeFileSync.call(this, destination, readFileSync.call(this, source));
+    writeFileSync.call(this, destination, readFileSync.call(this, source, {}));
     emitChange(this, 'rename', destination.toString());
 }
 copyFileSync;

package/dist/vfs/file.js

@@ -93,8 +93,8 @@ import { _chown, InodeFlags, isBlockDevice, isCharacterDevice } from '../interna
 import '../polyfills.js';
 import { validateFD } from '../utils.js';
 import { cacheOf } from './vcache.js';
-/** The chunk size used when streaming reads and writes */
-const streamChunkSize = 0x1000;
+/** Default bytes per chunk for streamed reads, matching Node's default stream `highWaterMark` */
+const streamChunkSize = 0x10000;
 /**
  * @internal
  */
@@ -608,19 +608,25 @@ let Handle = (() => {
             if (this.closed)
                 throw UV('EBADF', 'streamRead', this.path);
             const { vnode } = this;
+            const { chunkSize = streamChunkSize } = options;
+            let offset = options.start ?? 0;
+            let end = options.end;
             return new ReadableStream({
-                async start(controller) {
+                async pull(controller) {
                     const env_15 = { stack: [], error: void 0, hasError: false };
                     try {
                         const _ = __addDisposableResource(env_15, await vnode.lock('ro'), false);
-                        const { start = 0, end = vnode.inode.size } = options;
-                        for (let offset = start; offset < end; offset += streamChunkSize) {
-                            const bytesRead = offset + streamChunkSize > end ? end - offset : streamChunkSize;
-                            const buffer = new Uint8Array(bytesRead);
-                            await vnode.read(buffer, offset, offset + bytesRead).catch(controller.error.bind(controller));
-                            controller.enqueue(buffer);
+                        end ??= vnode.inode.size;
+                        if (offset >= end) {
+                            controller.close();
+                            return;
                         }
-                        controller.close();
+                        const buffer = new Uint8Array(Math.min(chunkSize, end - offset));
+                        await vnode.read(buffer, offset, offset + buffer.byteLength);
+                        offset += buffer.byteLength;
+                        controller.enqueue(buffer);
+                        if (offset >= end)
+                            controller.close();
                     }
                     catch (e_15) {
                         env_15.error = e_15;

package/dist/vfs/shared.js

@@ -128,7 +128,7 @@ export function chroot(path) {
             throw UV('EBUSY', 'chroot', handle.path);
         handle.path = handle.path.slice($.root.length);
     }
-    if (newRoot.length > $.root.length)
+    if (newRoot.length < $.root.length)
         throw withErrno('EPERM', 'Can not chroot() outside of current root');
     $.root = newRoot;
 }

package/dist/vfs/vnode.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { RwLockable } from 'kerium/locks';
-import { Resource } from 'utilium/cache';
+import { addRange, Resource } from 'utilium/cache';
 import { InodeFlags, isBlockDevice, isCharacterDevice } from '../internal/inode.js';
 /**
  * A VFS-level node, roughly equivalent to Linux's in-memory `struct inode`.
@@ -57,17 +57,7 @@ export class VNode extends RwLockable {
     }
     /** Add a range to `dirtyRanges`, merging overlapping and adjacent ranges */
     markDirty(start, end) {
-        this.dirtyRanges.push({ start, end });
-        this.dirtyRanges.sort((a, b) => a.start - b.start);
-        const merged = [];
-        for (const range of this.dirtyRanges) {
-            const last = merged.at(-1);
-            if (last && range.start <= last.end)
-                last.end = Math.max(last.end, range.end);
-            else
-                merged.push(range);
-        }
-        this.dirtyRanges = merged;
+        addRange(this.dirtyRanges, start, end);
     }
     /**
      * Copy `[start, end)` from the cache into `buffer`.
@@ -75,12 +65,10 @@ export class VNode extends RwLockable {
      */
     copyFromCache(buffer, start, end) {
         let pos = start;
-        for (const region of this.data.regions) {
+        for (const region of this.data.regionsIn(start, end)) {
             const regionEnd = region.offset + region.data.byteLength;
             if (regionEnd <= pos)
                 continue;
-            if (region.offset >= end)
-                break;
             if (region.offset > pos) {
                 buffer.fill(0, pos - start, region.offset - start);
                 pos = region.offset;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.7.1",
+	"version": "2.7.3-newstreams.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -69,19 +69,18 @@
 		"lint": "eslint src tests",
 		"test": "npx -s zenfs-test --clean; npx -s zenfs-test -abcpn; tests/fetch/run.sh; npx -s zenfs-test --report-only",
 		"test:native": "npx -s zenfs-test tests/native-setup.ts --verbose",
-		"build": "tsc -p tsconfig.json",
-		"build:docs": "typedoc",
-		"dev": "tsc -p tsconfig.json --watch",
+		"build": "tsc --build",
+		"dev": "tsc --build --watch",
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
 		"@types/node": "^26.0.0",
+		"@zenfs/streams": "^0.0.1",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
-		"kerium": "^1.4.2",
+		"kerium": "^1.5.0",
 		"memium": "^1.0.0",
-		"readable-stream": "^4.5.2",
-		"utilium": "^3.0.0"
+		"utilium": "^3.7.0"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",

package/tests/common/context.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-import { bindContext, configure, fs, InMemory } from '@zenfs/core';
+import { bindContext, configure, fs, InMemory, type BoundContext } from '@zenfs/core';
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
 import { canary } from 'utilium';
@@ -124,4 +124,14 @@ suite('Context', () => {
 		assert.equal(ctx.readFileSync('/copy.txt', 'utf-8'), 'not in real root!');
 		assert(fs.readdirSync('/ctx').includes('copy.txt'));
 	});
+
+	test('bindContext should resolve root relative to the parent context', () => {
+		fs.mkdirSync('/secure');
+		const ctx = bindContext({ root: '/secure', credentials: { uid: 333, gid: 333 } });
+
+		const plain = bindContext({ credentials: { uid: 1, gid: 1 } });
+		console.log('child of / context: ok, root =', plain.root);
+
+		assert.doesNotThrow(() => ctx.bind({ credentials: { uid: 500, gid: 500 } }));
+	});
 });

package/tests/fs/streams.test.ts

@@ -141,4 +141,64 @@ suite('Streams', config('streams'), () => {
 		// Closing invalidates the descriptor, so it fails range validation
 		assert.throws(() => fileHandle.createWriteStream(), { code: 'ERR_OUT_OF_RANGE' });
 	});
+
+	// A file large enough to span several chunks, so the read path has to stitch
+	// them back together and the vnode cache has to grow to hold them.
+	const large = Buffer.alloc(200 * 1024);
+	for (let i = 0; i < large.length; i++) large[i] = (i * 31 + 7) & 0xff;
+
+	test('createReadStream reads a multi-chunk file byte for byte', async () => {
+		await fs.promises.writeFile('large.bin', large);
+
+		const chunks: Uint8Array[] = [];
+		for await (const chunk of fs.createReadStream('large.bin')) chunks.push(chunk as Uint8Array);
+
+		assert.deepEqual(Buffer.concat(chunks), large);
+	});
+
+	test('createReadStream honors highWaterMark as the chunk size', async () => {
+		await fs.promises.writeFile('large.bin', large);
+
+		const highWaterMark = 64 * 1024;
+		const sizes: number[] = [];
+		for await (const chunk of fs.createReadStream('large.bin', { highWaterMark })) sizes.push((chunk as Uint8Array).byteLength);
+
+		// Every chunk but the last is a full highWaterMark, and they sum to the file
+		assert.deepEqual(sizes.slice(0, -1), Array(sizes.length - 1).fill(highWaterMark));
+		assert.equal(
+			sizes.reduce((a, b) => a + b, 0),
+			large.length
+		);
+	});
+
+	test('createReadStream with start and end spanning chunks', async () => {
+		await fs.promises.writeFile('large.bin', large);
+
+		// `end` is inclusive, and this range deliberately starts and stops mid-chunk
+		const start = 1000;
+		const end = 150_000;
+		const chunks: Uint8Array[] = [];
+		for await (const chunk of fs.createReadStream('large.bin', { start, end, highWaterMark: 8192 })) chunks.push(chunk as Uint8Array);
+
+		assert.deepEqual(Buffer.concat(chunks), large.subarray(start, end + 1));
+	});
+
+	test('a read stream does not read past the end of the file', async () => {
+		await fs.promises.writeFile('small.bin', large.subarray(0, 10));
+
+		const chunks: Uint8Array[] = [];
+		for await (const chunk of fs.createReadStream('small.bin', { highWaterMark: 64 * 1024 })) chunks.push(chunk as Uint8Array);
+
+		assert.equal(chunks.length, 1);
+		assert.deepEqual(chunks[0], large.subarray(0, 10));
+	});
+
+	test('a read stream over an empty file ends without a chunk', async () => {
+		await fs.promises.writeFile('empty.bin', '');
+
+		const chunks: unknown[] = [];
+		for await (const chunk of fs.createReadStream('empty.bin')) chunks.push(chunk);
+
+		assert.deepEqual(chunks, []);
+	});
 });

package/tests/setup.ts

@@ -8,7 +8,7 @@ export const data = join(import.meta.dirname, 'data');
 
 export const tmp = join(import.meta.dirname, 'tmp');
 
-if (!existsSync(tmp)) mkdirSync(tmp);
+if (!existsSync(tmp)) mkdirSync(tmp, { recursive: true });
 
 export async function copyAsync(_path: string, fs: NodeFS = _fs): Promise<void> {
 	const path = relative(data, _path) || '/';

package/types/README.md

@@ -1 +0,0 @@
-This directory contains declaration files. Due to numerous TypeScript shenanigans, placing them into `src` is a really bad idea. Instead, we put them here.

package/types/readable-stream.d.ts

@@ -1,18 +0,0 @@
-/*
-@types/readable-stream has *many* problems:
-https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/71923
-https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/71307
-https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/71083
-https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/66049
-... and many more
-
-This allows us to bypass those problems.
-
-Warning: Do not install @types/readable-stream alongside this package!
-*/
-
-/// <reference types="node" preserve="true" />
-declare module 'readable-stream' {
-	import { finished, Readable, Writable } from 'node:stream';
-	export { finished, Readable, Writable };
-}