@zenfs/core 1.2.6 → 1.2.8

package/dist/backends/backend.d.ts

@@ -12,8 +12,9 @@ export type OptionsConfig<T> = {
         type: OptionType | readonly OptionType[];
         /**
          * Description of the option. Used in error messages and documentation.
+         * @deprecated
          */
-        description: string;
+        description?: string;
         /**
          * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
          */

package/dist/backends/fetch.d.ts

@@ -6,6 +6,10 @@ import type { IndexData } from './file_index.js';
  * Configuration options for FetchFS.
  */
 export interface FetchOptions {
+    /**
+     * Options to pass through to fetch calls
+     */
+    requestInit?: RequestInit;
     /**
      * URL to a file index as a JSON file or the file index object itself.
      * Defaults to `index.json`.
@@ -37,8 +41,9 @@ export interface FetchOptions {
  */
 export declare class FetchFS extends IndexFS {
     readonly baseUrl: string;
+    readonly requestInit?: RequestInit;
     ready(): Promise<void>;
-    constructor({ index, baseUrl }: FetchOptions);
+    constructor({ index, baseUrl, requestInit }: FetchOptions);
     metadata(): FileSystemMetadata;
     /**
      * Preload the `path` into the index.
@@ -56,12 +61,14 @@ declare const _Fetch: {
         readonly index: {
             readonly type: readonly ["string", "object"];
             readonly required: false;
-            readonly description: "URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.";
         };
         readonly baseUrl: {
             readonly type: "string";
             readonly required: false;
-            readonly description: "Used as the URL prefix for fetched files. Default: Fetch files relative to the index.";
+        };
+        readonly requestInit: {
+            readonly type: "object";
+            readonly required: false;
         };
     };
     readonly isAvailable: () => boolean;

package/dist/backends/fetch.js

@@ -1,7 +1,7 @@
 import { Errno, ErrnoError } from '../error.js';
 import { IndexFS } from './file_index.js';
-async function fetchFile(path, type) {
-    const response = await fetch(path).catch((e) => {
+async function fetchFile(path, type, init) {
+    const response = await fetch(path, init).catch((e) => {
         throw new ErrnoError(Errno.EIO, e.message, path);
     });
     if (!response.ok) {
@@ -57,13 +57,14 @@ export class FetchFS extends IndexFS {
             await this.getData(path, stats);
         }
     }
-    constructor({ index = 'index.json', baseUrl = '' }) {
+    constructor({ index = 'index.json', baseUrl = '', requestInit }) {
         // prefix url must end in a directory separator.
         if (baseUrl.at(-1) != '/') {
             baseUrl += '/';
         }
-        super(typeof index != 'string' ? index : fetchFile(baseUrl + index, 'json'));
+        super(typeof index != 'string' ? index : fetchFile(baseUrl + index, 'json', requestInit));
         this.baseUrl = baseUrl;
+        this.requestInit = requestInit;
     }
     metadata() {
         return {
@@ -93,7 +94,7 @@ export class FetchFS extends IndexFS {
         if (stats.fileData) {
             return stats.fileData;
         }
-        const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer');
+        const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer', this.requestInit);
         stats.fileData = data;
         return data;
     }
@@ -107,16 +108,9 @@ export class FetchFS extends IndexFS {
 const _Fetch = {
     name: 'Fetch',
     options: {
-        index: {
-            type: ['string', 'object'],
-            required: false,
-            description: 'URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.',
-        },
-        baseUrl: {
-            type: 'string',
-            required: false,
-            description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
-        },
+        index: { type: ['string', 'object'], required: false },
+        baseUrl: { type: 'string', required: false },
+        requestInit: { type: 'object', required: false },
     },
     isAvailable() {
         return typeof globalThis.fetch == 'function';

package/dist/backends/memory.d.ts

@@ -22,7 +22,6 @@ declare const _InMemory: {
         readonly name: {
             readonly type: "string";
             readonly required: false;
-            readonly description: "The name of the store";
         };
     };
     readonly create: ({ name }: {

package/dist/backends/memory.js

@@ -26,11 +26,7 @@ const _InMemory = {
         return true;
     },
     options: {
-        name: {
-            type: 'string',
-            required: false,
-            description: 'The name of the store',
-        },
+        name: { type: 'string', required: false },
     },
     create({ name }) {
         const fs = new StoreFS(new InMemoryStore(name));

package/dist/backends/port/fs.d.ts

@@ -110,13 +110,11 @@ declare const _Port: {
         port: {
             type: "object";
             required: true;
-            description: string;
             validator(port: RPC.Port): void;
         };
         timeout: {
             type: "number";
             required: false;
-            description: string;
         };
     };
     isAvailable(): boolean;

package/dist/backends/port/fs.js

@@ -214,7 +214,6 @@ const _Port = {
         port: {
             type: 'object',
             required: true,
-            description: 'The target port that you want to connect to',
             validator(port) {
                 // Check for a `postMessage` function.
                 if (typeof port?.postMessage != 'function') {
@@ -225,7 +224,6 @@ const _Port = {
         timeout: {
             type: 'number',
             required: false,
-            description: 'How long to wait before the request times out',
         },
     },
     isAvailable() {

package/dist/config.js

@@ -70,8 +70,8 @@ export async function configure(configuration) {
     Object.assign(credentials, { uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
     cache.setEnabled(configuration.cacheStats ?? false);
     config.checkAccess = !configuration.disableAccessChecks;
-    config.syncOnRead = !configuration.onlySyncOnClose || !configuration.disableUpdateOnRead;
-    config.syncOnWrite = !configuration.onlySyncOnClose;
+    config.updateOnRead = !configuration.disableUpdateOnRead;
+    config.syncImmediately = !configuration.onlySyncOnClose;
     if (configuration.addDevices) {
         const devfs = new DeviceFS();
         devfs.createDevice('/null', nullDevice);

package/dist/devices.d.ts

@@ -8,9 +8,10 @@ import type { Ino } from './inode.js';
 /**
  * A device
  * @todo Maybe add major/minor number or some other device information, like a UUID?
- * @experimental
+ * @privateRemarks
+ * UUIDs were considered, however they don't make sense without an easy mechanism for persistance
  */
-export interface Device {
+export interface Device<TData = any> {
     /**
      * The device's driver
      */
@@ -19,34 +20,64 @@ export interface Device {
      * Which inode the device is assigned
      */
     ino: Ino;
+    /**
+     * Data associated with a device.
+     * This is meant to be used by device drivers.
+     * @experimental
+     */
+    data: TData;
+    /**
+     * Major device number
+     * @experimental
+     */
+    major: number;
+    /**
+     * Minor device number
+     * @experimental
+     */
+    minor: number;
 }
 /**
  * A device driver
- * @experimental
  */
-export interface DeviceDriver {
+export interface DeviceDriver<TData = any> {
     /**
      * The name of the device driver
      */
     name: string;
     /**
      * Whether the device is buffered (a "block" device) or unbuffered (a "character" device)
+     * @default false
+     */
+    isBuffered?: boolean;
+    /**
+     * Initializes a new device.
+     * @returns `Device.data`
+     * @experimental
      */
-    isBuffered: boolean;
+    init?(ino: Ino): {
+        data?: TData;
+        minor?: number;
+        major?: number;
+    };
     /**
      * Synchronously read from the device
+     * @group File operations
      */
     read(file: DeviceFile, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
      * Synchronously write to the device
+     * @group File operations
      */
     write(file: DeviceFile, buffer: Uint8Array, offset: number, length: number, position?: number): number;
     /**
      * Sync the device
+     * @group File operations
      */
     sync?(file: DeviceFile): void;
     /**
      * Close the device
+     * @group File operations
      */
     close?(file: DeviceFile): void;
 }
@@ -55,7 +86,6 @@ export interface DeviceDriver {
  * This class only does some simple things:
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
- * @experimental
  */
 export declare class DeviceFile extends File {
     fs: DeviceFS;
@@ -86,11 +116,14 @@ export declare class DeviceFile extends File {
     _setTypeSync(): void;
 }
 /**
- * @experimental
+ * A temporary file system that manages and interfaces with devices
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
-    protected readonly devices: Map<string, Device>;
-    createDevice(path: string, driver: DeviceDriver): Device;
+    protected readonly devices: Map<string, Device<any>>;
+    /**
+     * Creates a new device at `path` relative to the `DeviceFS` root.
+     */
+    createDevice<TData = any>(path: string, driver: DeviceDriver<TData>): Device<TData | Record<string, never>>;
     constructor();
     rename(oldPath: string, newPath: string): Promise<void>;
     renameSync(oldPath: string, newPath: string): void;
@@ -150,9 +183,9 @@ export declare const randomDevice: DeviceDriver;
  * @experimental
  */
 declare const _default: {
-    null: DeviceDriver;
-    zero: DeviceDriver;
-    full: DeviceDriver;
-    random: DeviceDriver;
+    null: DeviceDriver<any>;
+    zero: DeviceDriver<any>;
+    full: DeviceDriver<any>;
+    random: DeviceDriver<any>;
 };
 export default _default;

package/dist/devices.js

@@ -1,3 +1,6 @@
+/*
+This is a great resource: https://www.kernel.org/doc/html/latest/admin-guide/devices.html
+*/
 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.");
@@ -57,7 +60,6 @@ import { basename, dirname } from './emulation/path.js';
  * This class only does some simple things:
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
- * @experimental
  */
 export class DeviceFile extends File {
     constructor(fs, path, device) {
@@ -142,9 +144,12 @@ export class DeviceFile extends File {
     }
 }
 /**
- * @experimental
+ * A temporary file system that manages and interfaces with devices
  */
 export class DeviceFS extends StoreFS {
+    /**
+     * Creates a new device at `path` relative to the `DeviceFS` root.
+     */
     createDevice(path, driver) {
         if (this.existsSync(path)) {
             throw ErrnoError.With('EEXIST', path, 'mknod');
@@ -155,6 +160,10 @@ export class DeviceFS extends StoreFS {
         const dev = {
             driver,
             ino,
+            data: {},
+            minor: 0,
+            major: 0,
+            ...driver.init?.(ino),
         };
         this.devices.set(path, dev);
         return dev;
@@ -332,7 +341,9 @@ function defaultWrite(file, buffer, offset, length) {
  */
 export const nullDevice = {
     name: 'null',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 3 };
+    },
     read() {
         return 0;
     },
@@ -350,7 +361,9 @@ export const nullDevice = {
  */
 export const zeroDevice = {
     name: 'zero',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 5 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {
@@ -369,7 +382,9 @@ export const zeroDevice = {
  */
 export const fullDevice = {
     name: 'full',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 7 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {
@@ -390,7 +405,9 @@ export const fullDevice = {
  */
 export const randomDevice = {
     name: 'random',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 8 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {

package/dist/emulation/config.d.ts

@@ -4,13 +4,13 @@ export declare const config: {
      */
     checkAccess: boolean;
     /**
-     * Whether to sync atime updates immediately when reading from a file
+     * Whether to mark a file as dirty after updating its `atime` when read from
      */
-    syncOnRead: boolean;
+    updateOnRead: boolean;
     /**
-     * Whether to immediately sync when files are written to
+     * Whether to immediately sync when files are changed
      */
-    syncOnWrite: boolean;
+    syncImmediately: boolean;
     /**
      * If a file's buffer is not large enough to store content when writing and the buffer can't be resized, reuse the buffer passed to write()
      */

package/dist/emulation/config.js

@@ -4,13 +4,13 @@ export const config = {
      */
     checkAccess: true,
     /**
-     * Whether to sync atime updates immediately when reading from a file
+     * Whether to mark a file as dirty after updating its `atime` when read from
      */
-    syncOnRead: true,
+    updateOnRead: true,
     /**
-     * Whether to immediately sync when files are written to
+     * Whether to immediately sync when files are changed
      */
-    syncOnWrite: true,
+    syncImmediately: true,
     /**
      * If a file's buffer is not large enough to store content when writing and the buffer can't be resized, reuse the buffer passed to write()
      */

package/dist/emulation/shared.d.ts

@@ -21,7 +21,7 @@ export declare function mount(mountPoint: string, fs: FileSystem): void;
  */
 export declare function umount(mountPoint: string): void;
 /**
- * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root
  */
 export declare function resolveMount(path: string): {
     fs: FileSystem;

package/dist/emulation/shared.js

@@ -43,7 +43,7 @@ export function mount(mountPoint, fs) {
  */
 export function umount(mountPoint) {
     if (mountPoint[0] !== '/') {
-        mountPoint = `/${mountPoint}`;
+        mountPoint = '/' + mountPoint;
     }
     mountPoint = resolve(mountPoint);
     if (!mounts.has(mountPoint)) {
@@ -52,11 +52,10 @@ export function umount(mountPoint) {
     mounts.delete(mountPoint);
 }
 /**
- * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root
  */
 export function resolveMount(path) {
     path = normalizePath(path);
-    // Maybe do something for devices here
     const sortedMounts = [...mounts].sort((a, b) => (a[0].length > b[0].length ? -1 : 1)); // descending order of the string length
     for (const [mountPoint, fs] of sortedMounts) {
         // We know path is normalized, so it would be a substring of the mount point.

package/dist/file.js

@@ -289,12 +289,12 @@ export class PreloadFile extends File {
     }
     async truncate(length) {
         this._truncate(length);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             await this.sync();
     }
     truncateSync(length) {
         this._truncate(length);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             this.syncSync();
     }
     _write(buffer, offset = 0, length = this.stats.size, position = this.position) {
@@ -339,7 +339,7 @@ export class PreloadFile extends File {
      */
     async write(buffer, offset, length, position) {
         const bytesWritten = this._write(buffer, offset, length, position);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             await this.sync();
         return bytesWritten;
     }
@@ -354,7 +354,7 @@ export class PreloadFile extends File {
      */
     writeSync(buffer, offset = 0, length = this.stats.size, position = this.position) {
         const bytesWritten = this._write(buffer, offset, length, position);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             this.syncSync();
         return bytesWritten;
     }
@@ -365,7 +365,9 @@ export class PreloadFile extends File {
         if (!isReadable(this.flag)) {
             throw new ErrnoError(Errno.EPERM, 'File not opened with a readable mode.');
         }
-        this.dirty = true;
+        if (config.updateOnRead) {
+            this.dirty = true;
+        }
         this.stats.atimeMs = Date.now();
         position ?? (position = this.position);
         let end = position + length;
@@ -391,7 +393,7 @@ export class PreloadFile extends File {
      */
     async read(buffer, offset, length, position) {
         const bytesRead = this._read(buffer, offset, length, position);
-        if (config.syncOnRead)
+        if (config.syncImmediately)
             await this.sync();
         return { bytesRead, buffer };
     }
@@ -406,7 +408,7 @@ export class PreloadFile extends File {
      */
     readSync(buffer, offset, length, position) {
         const bytesRead = this._read(buffer, offset, length, position);
-        if (config.syncOnRead)
+        if (config.syncImmediately)
             this.syncSync();
         return bytesRead;
     }
@@ -416,7 +418,7 @@ export class PreloadFile extends File {
         }
         this.dirty = true;
         this.stats.chmod(mode);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             await this.sync();
     }
     chmodSync(mode) {
@@ -425,7 +427,7 @@ export class PreloadFile extends File {
         }
         this.dirty = true;
         this.stats.chmod(mode);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             this.syncSync();
     }
     async chown(uid, gid) {
@@ -434,7 +436,7 @@ export class PreloadFile extends File {
         }
         this.dirty = true;
         this.stats.chown(uid, gid);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             await this.sync();
     }
     chownSync(uid, gid) {
@@ -443,7 +445,7 @@ export class PreloadFile extends File {
         }
         this.dirty = true;
         this.stats.chown(uid, gid);
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             this.syncSync();
     }
     async utimes(atime, mtime) {
@@ -453,7 +455,7 @@ export class PreloadFile extends File {
         this.dirty = true;
         this.stats.atime = atime;
         this.stats.mtime = mtime;
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             await this.sync();
     }
     utimesSync(atime, mtime) {
@@ -463,7 +465,7 @@ export class PreloadFile extends File {
         this.dirty = true;
         this.stats.atime = atime;
         this.stats.mtime = mtime;
-        if (config.syncOnWrite)
+        if (config.syncImmediately)
             this.syncSync();
     }
     async _setType(type) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.2.6",
+	"version": "1.2.8",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",

package/readme.md

@@ -201,6 +201,10 @@ If you would like to see a more intuitive way adding custom devices (e.g. `fs.mk
 
 ZenFS exports a drop-in for Node's `fs` module (up to the version of `@types/node` in package.json), so you can use it for your bundler of preference using the default export.
 
+## Sponsors
+
+A huge thank you to [![Deco.cx logo](https://avatars.githubusercontent.com/deco-cx?size=20) Deco.cx](https://github.com/deco-cx) for sponsoring ZenFS and helping to make this possible.
+
 ## Building
 
 -   Make sure you have Node and NPM installed. You must have Node v18 or newer.

package/src/backends/backend.ts

@@ -17,8 +17,9 @@ export type OptionsConfig<T> = {
 
 		/**
 		 * Description of the option. Used in error messages and documentation.
+		 * @deprecated
 		 */
-		description: string;
+		description?: string;
 
 		/**
 		 * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.

package/src/backends/fetch.ts

@@ -12,11 +12,11 @@ import type { IndexData } from './file_index.js';
  * constants.
  * @hidden
  */
-async function fetchFile(path: string, type: 'buffer'): Promise<Uint8Array>;
-async function fetchFile<T extends object>(path: string, type: 'json'): Promise<T>;
-async function fetchFile<T extends object>(path: string, type: 'buffer' | 'json'): Promise<T | Uint8Array>;
-async function fetchFile<T extends object>(path: string, type: string): Promise<T | Uint8Array> {
-	const response = await fetch(path).catch((e: Error) => {
+async function fetchFile(path: string, type: 'buffer', init?: RequestInit): Promise<Uint8Array>;
+async function fetchFile<T extends object>(path: string, type: 'json', init?: RequestInit): Promise<T>;
+async function fetchFile<T extends object>(path: string, type: 'buffer' | 'json', init?: RequestInit): Promise<T | Uint8Array>;
+async function fetchFile<T extends object>(path: string, type: string, init?: RequestInit): Promise<T | Uint8Array> {
+	const response = await fetch(path, init).catch((e: Error) => {
 		throw new ErrnoError(Errno.EIO, e.message, path);
 	});
 	if (!response.ok) {
@@ -42,6 +42,11 @@ async function fetchFile<T extends object>(path: string, type: string): Promise<
  * Configuration options for FetchFS.
  */
 export interface FetchOptions {
+	/**
+	 * Options to pass through to fetch calls
+	 */
+	requestInit?: RequestInit;
+
 	/**
 	 * URL to a file index as a JSON file or the file index object itself.
 	 * Defaults to `index.json`.
@@ -75,6 +80,7 @@ export interface FetchOptions {
  */
 export class FetchFS extends IndexFS {
 	public readonly baseUrl: string;
+	public readonly requestInit?: RequestInit;
 
 	public async ready(): Promise<void> {
 		if (this._isInitialized) {
@@ -94,15 +100,16 @@ export class FetchFS extends IndexFS {
 		}
 	}
 
-	public constructor({ index = 'index.json', baseUrl = '' }: FetchOptions) {
+	public constructor({ index = 'index.json', baseUrl = '', requestInit }: FetchOptions) {
 		// prefix url must end in a directory separator.
 		if (baseUrl.at(-1) != '/') {
 			baseUrl += '/';
 		}
 
-		super(typeof index != 'string' ? index : fetchFile<IndexData>(baseUrl + index, 'json'));
+		super(typeof index != 'string' ? index : fetchFile<IndexData>(baseUrl + index, 'json', requestInit));
 
 		this.baseUrl = baseUrl;
+		this.requestInit = requestInit;
 	}
 
 	public metadata(): FileSystemMetadata {
@@ -136,7 +143,7 @@ export class FetchFS extends IndexFS {
 			return stats.fileData;
 		}
 
-		const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer');
+		const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer', this.requestInit);
 		stats.fileData = data;
 		return data;
 	}
@@ -154,16 +161,9 @@ const _Fetch = {
 	name: 'Fetch',
 
 	options: {
-		index: {
-			type: ['string', 'object'],
-			required: false,
-			description: 'URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.',
-		},
-		baseUrl: {
-			type: 'string',
-			required: false,
-			description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
-		},
+		index: { type: ['string', 'object'], required: false },
+		baseUrl: { type: 'string', required: false },
+		requestInit: { type: 'object', required: false },
 	},
 
 	isAvailable(): boolean {

package/src/backends/memory.ts

@@ -32,11 +32,7 @@ const _InMemory = {
 		return true;
 	},
 	options: {
-		name: {
-			type: 'string',
-			required: false,
-			description: 'The name of the store',
-		},
+		name: { type: 'string', required: false },
 	},
 	create({ name }: { name?: string }) {
 		const fs = new StoreFS(new InMemoryStore(name));

package/src/backends/port/fs.ts

@@ -298,7 +298,6 @@ const _Port = {
 		port: {
 			type: 'object',
 			required: true,
-			description: 'The target port that you want to connect to',
 			validator(port: RPC.Port) {
 				// Check for a `postMessage` function.
 				if (typeof port?.postMessage != 'function') {
@@ -309,7 +308,6 @@ const _Port = {
 		timeout: {
 			type: 'number',
 			required: false,
-			description: 'How long to wait before the request times out',
 		},
 	},
 

package/src/config.ts

@@ -163,8 +163,8 @@ export async function configure<T extends ConfigMounts>(configuration: Partial<C
 
 	cache.setEnabled(configuration.cacheStats ?? false);
 	config.checkAccess = !configuration.disableAccessChecks;
-	config.syncOnRead = !configuration.onlySyncOnClose || !configuration.disableUpdateOnRead;
-	config.syncOnWrite = !configuration.onlySyncOnClose;
+	config.updateOnRead = !configuration.disableUpdateOnRead;
+	config.syncImmediately = !configuration.onlySyncOnClose;
 
 	if (configuration.addDevices) {
 		const devfs = new DeviceFS();

package/src/devices.ts

@@ -1,3 +1,7 @@
+/*
+This is a great resource: https://www.kernel.org/doc/html/latest/admin-guide/devices.html
+*/
+
 import type { FileReadResult } from 'node:fs/promises';
 import { InMemoryStore } from './backends/memory.js';
 import { StoreFS } from './backends/store/fs.js';
@@ -12,9 +16,10 @@ import type { Ino } from './inode.js';
 /**
  * A device
  * @todo Maybe add major/minor number or some other device information, like a UUID?
- * @experimental
+ * @privateRemarks
+ * UUIDs were considered, however they don't make sense without an easy mechanism for persistance
  */
-export interface Device {
+export interface Device<TData = any> {
 	/**
 	 * The device's driver
 	 */
@@ -24,13 +29,31 @@ export interface Device {
 	 * Which inode the device is assigned
 	 */
 	ino: Ino;
+
+	/**
+	 * Data associated with a device.
+	 * This is meant to be used by device drivers.
+	 * @experimental
+	 */
+	data: TData;
+
+	/**
+	 * Major device number
+	 * @experimental
+	 */
+	major: number;
+
+	/**
+	 * Minor device number
+	 * @experimental
+	 */
+	minor: number;
 }
 
 /**
  * A device driver
- * @experimental
  */
-export interface DeviceDriver {
+export interface DeviceDriver<TData = any> {
 	/**
 	 * The name of the device driver
 	 */
@@ -38,26 +61,42 @@ export interface DeviceDriver {
 
 	/**
 	 * Whether the device is buffered (a "block" device) or unbuffered (a "character" device)
+	 * @default false
 	 */
-	isBuffered: boolean;
+	isBuffered?: boolean;
+
+	/**
+	 * Initializes a new device.
+	 * @returns `Device.data`
+	 * @experimental
+	 */
+	init?(ino: Ino): {
+		data?: TData;
+		minor?: number;
+		major?: number;
+	};
 
 	/**
 	 * Synchronously read from the device
+	 * @group File operations
 	 */
 	read(file: DeviceFile, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
 
 	/**
 	 * Synchronously write to the device
+	 * @group File operations
 	 */
 	write(file: DeviceFile, buffer: Uint8Array, offset: number, length: number, position?: number): number;
 
 	/**
 	 * Sync the device
+	 * @group File operations
 	 */
 	sync?(file: DeviceFile): void;
 
 	/**
 	 * Close the device
+	 * @group File operations
 	 */
 	close?(file: DeviceFile): void;
 }
@@ -67,7 +106,6 @@ export interface DeviceDriver {
  * This class only does some simple things:
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
- * @experimental
  */
 export class DeviceFile extends File {
 	public position = 0;
@@ -182,12 +220,15 @@ export class DeviceFile extends File {
 }
 
 /**
- * @experimental
+ * A temporary file system that manages and interfaces with devices
  */
 export class DeviceFS extends StoreFS<InMemoryStore> {
 	protected readonly devices = new Map<string, Device>();
 
-	public createDevice(path: string, driver: DeviceDriver): Device {
+	/**
+	 * Creates a new device at `path` relative to the `DeviceFS` root.
+	 */
+	public createDevice<TData = any>(path: string, driver: DeviceDriver<TData>): Device<TData | Record<string, never>> {
 		if (this.existsSync(path)) {
 			throw ErrnoError.With('EEXIST', path, 'mknod');
 		}
@@ -196,6 +237,10 @@ export class DeviceFS extends StoreFS<InMemoryStore> {
 		const dev = {
 			driver,
 			ino,
+			data: {},
+			minor: 0,
+			major: 0,
+			...driver.init?.(ino),
 		};
 		this.devices.set(path, dev);
 		return dev;
@@ -373,7 +418,9 @@ function defaultWrite(file: DeviceFile, buffer: Uint8Array, offset: number, leng
  */
 export const nullDevice: DeviceDriver = {
 	name: 'null',
-	isBuffered: false,
+	init() {
+		return { major: 1, minor: 3 };
+	},
 	read(): number {
 		return 0;
 	},
@@ -392,7 +439,9 @@ export const nullDevice: DeviceDriver = {
  */
 export const zeroDevice: DeviceDriver = {
 	name: 'zero',
-	isBuffered: false,
+	init() {
+		return { major: 1, minor: 5 };
+	},
 	read(file: DeviceFile, buffer: ArrayBufferView, offset = 0, length = buffer.byteLength): number {
 		const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 		for (let i = offset; i < offset + length; i++) {
@@ -412,7 +461,9 @@ export const zeroDevice: DeviceDriver = {
  */
 export const fullDevice: DeviceDriver = {
 	name: 'full',
-	isBuffered: false,
+	init() {
+		return { major: 1, minor: 7 };
+	},
 	read(file: DeviceFile, buffer: ArrayBufferView, offset = 0, length = buffer.byteLength): number {
 		const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 		for (let i = offset; i < offset + length; i++) {
@@ -435,7 +486,9 @@ export const fullDevice: DeviceDriver = {
  */
 export const randomDevice: DeviceDriver = {
 	name: 'random',
-	isBuffered: false,
+	init() {
+		return { major: 1, minor: 8 };
+	},
 	read(file: DeviceFile, buffer: ArrayBufferView, offset = 0, length = buffer.byteLength): number {
 		const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 		for (let i = offset; i < offset + length; i++) {

package/src/emulation/config.ts

@@ -5,14 +5,14 @@ export const config = {
 	checkAccess: true,
 
 	/**
-	 * Whether to sync atime updates immediately when reading from a file
+	 * Whether to mark a file as dirty after updating its `atime` when read from
 	 */
-	syncOnRead: true,
+	updateOnRead: true,
 
 	/**
-	 * Whether to immediately sync when files are written to
+	 * Whether to immediately sync when files are changed
 	 */
-	syncOnWrite: true,
+	syncImmediately: true,
 
 	/**
 	 * If a file's buffer is not large enough to store content when writing and the buffer can't be resized, reuse the buffer passed to write()

package/src/emulation/shared.ts

@@ -54,7 +54,7 @@ export function mount(mountPoint: string, fs: FileSystem): void {
  */
 export function umount(mountPoint: string): void {
 	if (mountPoint[0] !== '/') {
-		mountPoint = `/${mountPoint}`;
+		mountPoint = '/' + mountPoint;
 	}
 	mountPoint = resolve(mountPoint);
 	if (!mounts.has(mountPoint)) {
@@ -64,11 +64,10 @@ export function umount(mountPoint: string): void {
 }
 
 /**
- * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root
  */
 export function resolveMount(path: string): { fs: FileSystem; path: string; mountPoint: string } {
 	path = normalizePath(path);
-	// Maybe do something for devices here
 	const sortedMounts = [...mounts].sort((a, b) => (a[0].length > b[0].length ? -1 : 1)); // descending order of the string length
 	for (const [mountPoint, fs] of sortedMounts) {
 		// We know path is normalized, so it would be a substring of the mount point.

package/src/file.ts

@@ -441,12 +441,12 @@ export class PreloadFile<FS extends FileSystem> extends File {
 
 	public async truncate(length: number): Promise<void> {
 		this._truncate(length);
-		if (config.syncOnWrite) await this.sync();
+		if (config.syncImmediately) await this.sync();
 	}
 
 	public truncateSync(length: number): void {
 		this._truncate(length);
-		if (config.syncOnWrite) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 	}
 
 	protected _write(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = this.position): number {
@@ -494,7 +494,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 */
 	public async write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number> {
 		const bytesWritten = this._write(buffer, offset, length, position);
-		if (config.syncOnWrite) await this.sync();
+		if (config.syncImmediately) await this.sync();
 		return bytesWritten;
 	}
 
@@ -509,7 +509,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 */
 	public writeSync(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = this.position): number {
 		const bytesWritten = this._write(buffer, offset, length, position);
-		if (config.syncOnWrite) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 		return bytesWritten;
 	}
 
@@ -517,11 +517,17 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.read');
 		}
+
 		if (!isReadable(this.flag)) {
 			throw new ErrnoError(Errno.EPERM, 'File not opened with a readable mode.');
 		}
-		this.dirty = true;
+
+		if (config.updateOnRead) {
+			this.dirty = true;
+		}
+
 		this.stats.atimeMs = Date.now();
+
 		position ??= this.position;
 		let end = position + length;
 		if (end > this.stats.size) {
@@ -547,7 +553,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 */
 	public async read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{ bytesRead: number; buffer: TBuffer }> {
 		const bytesRead = this._read(buffer, offset, length, position);
-		if (config.syncOnRead) await this.sync();
+		if (config.syncImmediately) await this.sync();
 		return { bytesRead, buffer };
 	}
 
@@ -562,7 +568,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 */
 	public readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number {
 		const bytesRead = this._read(buffer, offset, length, position);
-		if (config.syncOnRead) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 		return bytesRead;
 	}
 
@@ -572,7 +578,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		}
 		this.dirty = true;
 		this.stats.chmod(mode);
-		if (config.syncOnWrite) await this.sync();
+		if (config.syncImmediately) await this.sync();
 	}
 
 	public chmodSync(mode: number): void {
@@ -581,7 +587,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		}
 		this.dirty = true;
 		this.stats.chmod(mode);
-		if (config.syncOnWrite) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 	}
 
 	public async chown(uid: number, gid: number): Promise<void> {
@@ -590,7 +596,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		}
 		this.dirty = true;
 		this.stats.chown(uid, gid);
-		if (config.syncOnWrite) await this.sync();
+		if (config.syncImmediately) await this.sync();
 	}
 
 	public chownSync(uid: number, gid: number): void {
@@ -599,7 +605,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		}
 		this.dirty = true;
 		this.stats.chown(uid, gid);
-		if (config.syncOnWrite) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 	}
 
 	public async utimes(atime: Date, mtime: Date): Promise<void> {
@@ -609,7 +615,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		this.dirty = true;
 		this.stats.atime = atime;
 		this.stats.mtime = mtime;
-		if (config.syncOnWrite) await this.sync();
+		if (config.syncImmediately) await this.sync();
 	}
 
 	public utimesSync(atime: Date, mtime: Date): void {
@@ -619,7 +625,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		this.dirty = true;
 		this.stats.atime = atime;
 		this.stats.mtime = mtime;
-		if (config.syncOnWrite) this.syncSync();
+		if (config.syncImmediately) this.syncSync();
 	}
 
 	public async _setType(type: FileType): Promise<void> {