@zenfs/core 1.2.7 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.2.7",
+	"version": "1.2.9",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -58,6 +58,7 @@
 		"lint": "eslint src tests",
 		"test:common": "tsx --test --experimental-test-coverage 'tests/**/!(fs)/*.test.ts' 'tests/*.test.ts'",
 		"test": "tsx --test --experimental-test-coverage",
+		"pretest": "npm run build",
 		"build": "tsc -p tsconfig.json",
 		"build:docs": "typedoc",
 		"dev": "npm run build -- --watch",

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/backends/store/fs.ts

@@ -534,22 +534,22 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 	 * @param data The data to store at the file's data node.
 	 */
 	private async commitNew(path: string, type: FileType, mode: number, data: Uint8Array): Promise<Inode> {
-		await using tx = this.store.transaction();
-		const parentPath = dirname(path),
-			parent = await this.findINode(tx, parentPath);
-
-		const fname = basename(path),
-			listing = await this.getDirListing(tx, parent, parentPath);
-
 		/*
 			The root always exists.
 			If we don't check this prior to taking steps below,
-			we will create a file with name '' in root should path == '/'.
+			we will create a file with name '' in root if path is '/'.
 		*/
-		if (path === '/') {
+		if (path == '/') {
 			throw ErrnoError.With('EEXIST', path, 'commitNew');
 		}
 
+		await using tx = this.store.transaction();
+		const parentPath = dirname(path),
+			parent = await this.findINode(tx, parentPath);
+
+		const fname = basename(path),
+			listing = await this.getDirListing(tx, parent, parentPath);
+
 		// Check if file already exists.
 		if (listing[fname]) {
 			await tx.abort();
@@ -581,22 +581,22 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 	 * @return The Inode for the new file.
 	 */
 	protected commitNewSync(path: string, type: FileType, mode: number, data: Uint8Array = new Uint8Array()): Inode {
-		using tx = this.store.transaction();
-		const parentPath = dirname(path),
-			parent = this.findINodeSync(tx, parentPath);
-
-		const fname = basename(path),
-			listing = this.getDirListingSync(tx, parent, parentPath);
-
 		/*
 			The root always exists.
 			If we don't check this prior to taking steps below,
-			we will create a file with name '' in root should p == '/'.
+			we will create a file with name '' in root if path is '/'.
 		*/
-		if (path === '/') {
+		if (path == '/') {
 			throw ErrnoError.With('EEXIST', path, 'commitNew');
 		}
 
+		using tx = this.store.transaction();
+		const parentPath = dirname(path),
+			parent = this.findINodeSync(tx, parentPath);
+
+		const fname = basename(path),
+			listing = this.getDirListingSync(tx, parent, parentPath);
+
 		// Check if file already exists.
 		if (listing[fname]) {
 			throw ErrnoError.With('EEXIST', path, 'commitNew');

package/src/config.ts

@@ -1,12 +1,11 @@
 import type { Backend, BackendConfiguration, FilesystemOf, SharedConfig } from './backends/backend.js';
 import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
 import { credentials } from './credentials.js';
-import { DeviceFS, fullDevice, nullDevice, randomDevice, zeroDevice } from './devices.js';
+import { DeviceFS } from './devices.js';
 import * as cache from './emulation/cache.js';
+import { config } from './emulation/config.js';
 import * as fs from './emulation/index.js';
 import type { AbsolutePath } from './emulation/path.js';
-import { type MountObject } from './emulation/shared.js';
-import { config } from './emulation/config.js';
 import { Errno, ErrnoError } from './error.js';
 import { FileSystem } from './filesystem.js';
 
@@ -151,6 +150,27 @@ export async function configureSingle<T extends Backend>(configuration: MountCon
 	fs.mount('/', resolved);
 }
 
+/**
+ * Like `fs.mount`, but it also creates missing directories.
+ * @privateRemarks
+ * This is implemented as a separate function to avoid a circular dependency between emulation/shared.ts and other emulation layer files.
+ * @internal
+ */
+async function mount(path: string, mount: FileSystem): Promise<void> {
+	if (path == '/') {
+		fs.mount(path, mount);
+		return;
+	}
+
+	const stats = await fs.promises.stat(path).catch(() => null);
+	if (!stats) {
+		await fs.promises.mkdir(path, { recursive: true });
+	} else if (!stats.isDirectory()) {
+		throw ErrnoError.With('ENOTDIR', path, 'configure');
+	}
+	fs.mount(path, mount);
+}
+
 /**
  * Configures ZenFS with `configuration`
  * @see Configuration
@@ -168,18 +188,18 @@ export async function configure<T extends ConfigMounts>(configuration: Partial<C
 
 	if (configuration.addDevices) {
 		const devfs = new DeviceFS();
-		devfs.createDevice('/null', nullDevice);
-		devfs.createDevice('/zero', zeroDevice);
-		devfs.createDevice('/full', fullDevice);
-		devfs.createDevice('/random', randomDevice);
+		devfs.addDefaults();
 		await devfs.ready();
-		fs.mount('/dev', devfs);
+		await mount('/dev', devfs);
 	}
 
 	if (!configuration.mounts) {
 		return;
 	}
 
+	const toMount: [string, FileSystem][] = [];
+	let unmountRoot = false;
+
 	for (const [point, mountConfig] of Object.entries(configuration.mounts)) {
 		if (!point.startsWith('/')) {
 			throw new ErrnoError(Errno.EINVAL, 'Mount points must have absolute paths');
@@ -189,8 +209,11 @@ export async function configure<T extends ConfigMounts>(configuration: Partial<C
 			mountConfig.disableAsyncCache ??= configuration.disableAsyncCache || false;
 		}
 
-		configuration.mounts[point as keyof T & `/${string}`] = await resolveMountConfig(mountConfig);
+		if (point == '/') unmountRoot = true;
+		toMount.push([point, await resolveMountConfig(mountConfig)]);
 	}
 
-	fs.mountObject(configuration.mounts as MountObject);
+	if (unmountRoot) fs.umount('/');
+
+	await Promise.all(toMount.map(([point, fs]) => mount(point, fs)));
 }

package/src/credentials.ts

@@ -21,6 +21,9 @@ export const credentials: Credentials = {
 	egid: 0,
 };
 
+/**
+ * @deprecated
+ */
 export const rootCredentials: Credentials = {
 	uid: 0,
 	gid: 0,

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,11 +237,25 @@ 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;
 	}
 
+	/**
+	 * Adds default devices
+	 */
+	public addDefaults(): void {
+		this.createDevice('/null', nullDevice);
+		this.createDevice('/zero', zeroDevice);
+		this.createDevice('/full', fullDevice);
+		this.createDevice('/random', randomDevice);
+	}
+
 	public constructor() {
 		super(new InMemoryStore('devfs'));
 	}
@@ -373,7 +428,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 +449,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 +471,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 +496,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/promises.ts

@@ -13,11 +13,11 @@ import '../polyfills.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { decodeUTF8, normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
 import * as cache from './cache.js';
+import { config } from './config.js';
 import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { _statfs, fd2file, fdMap, file2fd, fixError, mounts, resolveMount, type InternalOptions, type ReaddirOptions } from './shared.js';
-import { config } from './config.js';
+import { _statfs, fd2file, fdMap, file2fd, fixError, resolveMount, type InternalOptions, type ReaddirOptions } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
 import { FSWatcher, emitChange } from './watchers.js';
 export * as constants from './constants.js';
@@ -625,7 +625,7 @@ export async function rmdir(path: fs.PathLike): Promise<void> {
 	try {
 		const stats = await (cache.getStats(path) || fs.stat(resolved));
 		if (!stats) {
-			throw ErrnoError.With('ENOENT', path, 'readdir');
+			throw ErrnoError.With('ENOENT', path, 'rmdir');
 		}
 		if (!stats.isDirectory()) {
 			throw ErrnoError.With('ENOTDIR', resolved, 'rmdir');
@@ -736,17 +736,6 @@ export async function readdir(
 
 	const entries = await fs.readdir(resolved).catch(handleError);
 
-	for (const point of mounts.keys()) {
-		if (point.startsWith(path)) {
-			const entry = point.slice(path.length);
-			if (entry.includes('/') || entry.length == 0) {
-				// ignore FSs mounted in subdirectories and any FS mounted to `path`.
-				continue;
-			}
-			entries.push(entry);
-		}
-	}
-
 	const values: (string | Dirent | Buffer)[] = [];
 	const addEntry = async (entry: string) => {
 		let entryStats: Stats | undefined;

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.
@@ -107,6 +106,9 @@ export function fixError<E extends ErrnoError>(e: E, paths: Record<string, strin
 	return e;
 }
 
+/**
+ * @deprecated
+ */
 export function mountObject(mounts: MountObject): void {
 	if ('/' in mounts) {
 		umount('/');

package/src/emulation/sync.ts

@@ -6,13 +6,13 @@ import { flagToMode, isAppendable, isExclusive, isReadable, isTruncating, isWrit
 import type { FileContents } from '../filesystem.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { decodeUTF8, normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
+import * as cache from './cache.js';
+import { config } from './config.js';
 import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { _statfs, fd2file, fdMap, file2fd, fixError, mounts, resolveMount, type InternalOptions, type ReaddirOptions } from './shared.js';
-import { config } from './config.js';
+import { _statfs, fd2file, fdMap, file2fd, fixError, resolveMount, type InternalOptions, type ReaddirOptions } from './shared.js';
 import { emitChange } from './watchers.js';
-import * as cache from './cache.js';
 
 export function renameSync(oldPath: fs.PathLike, newPath: fs.PathLike): void {
 	oldPath = normalizePath(oldPath);
@@ -472,18 +472,6 @@ export function readdirSync(
 		throw fixError(e as ErrnoError, { [resolved]: path });
 	}
 
-	for (const mount of mounts.keys()) {
-		if (!mount.startsWith(path)) {
-			continue;
-		}
-		const entry = mount.slice(path.length);
-		if (entry.includes('/') || entry.length == 0) {
-			// ignore FSs mounted in subdirectories and any FS mounted to `path`.
-			continue;
-		}
-		entries.push(entry);
-	}
-
 	// Iterate over entries and handle recursive case if needed
 	const values: (string | Dirent | Buffer)[] = [];
 	for (const entry of entries) {

package/src/mixins/async.ts

@@ -80,8 +80,8 @@ export function Async<T extends typeof FileSystem>(
 				const async = (this as StoreFS<Store>)['store'].transaction();
 
 				const promises = [];
-				for (const key of sync.keysSync()) {
-					promises.push(async.set(key, sync.getSync(key)));
+				for (const key of await async.keys()) {
+					promises.push(async.get(key).then(data => sync.setSync(key, data)));
 				}
 
 				await Promise.all(promises);