@zenfs/core 0.12.2 → 0.12.3

package/readme.md

@@ -4,7 +4,7 @@ ZenFS is a file system that emulates the [NodeJS filesystem API](http://nodejs.o
 
 It works using a system of backends, which are used by ZenFS to store and retrieve data. ZenFS can also integrate with other tools.
 
-ZenFS is a fork of [BrowserFS](https://github.com/jvilk/BrowserFS). If you are using ZenFS in a research paper, you may want to [cite BrowserFS](https://github.com/jvilk/BrowserFS?tab=readme-ov-file#citing).
+ZenFS is a fork of [BrowserFS](https://github.com/jvilk/BrowserFS). If you are using ZenFS in a research paper, you may want to [cite BrowserFS](https://github.com/jvilk/BrowserFS#citing).
 
 ## Backends
 

package/src/backends/backend.ts

@@ -1,6 +1,6 @@
 import type { RequiredKeys } from 'utilium';
 import { ErrnoError, Errno } from '../error.js';
-import { FileSystem } from '../filesystem.js';
+import type { FileSystem } from '../filesystem.js';
 import { levenshtein } from '../utils.js';
 
 type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';

package/src/backends/fetch.ts

@@ -1,6 +1,6 @@
 import { Errno, ErrnoError } from '../error.js';
 import type { FileSystemMetadata } from '../filesystem.js';
-import { Stats } from '../stats.js';
+import type { Stats } from '../stats.js';
 import type { Backend } from './backend.js';
 import { IndexFS } from './index/fs.js';
 import type { IndexData } from './index/index.js';

package/src/backends/index/fs.ts

@@ -4,7 +4,8 @@ import { NoSyncFile, isWriteable, flagToMode } from '../../file.js';
 import { Readonly, FileSystem } from '../../filesystem.js';
 import type { Stats } from '../../stats.js';
 import { decode } from '../../utils.js';
-import { Index, IndexData } from './index.js';
+import type { IndexData } from './index.js';
+import { Index } from './index.js';
 
 export abstract class IndexFS extends Readonly(FileSystem) {
 	protected index: Index = new Index();

package/src/backends/index/index.ts

@@ -1,6 +1,7 @@
 import { isJSON } from 'utilium';
 import { Errno, ErrnoError } from '../../error.js';
-import { Stats, StatsLike } from '../../stats.js';
+import type { StatsLike } from '../../stats.js';
+import { Stats } from '../../stats.js';
 import { encode } from '../../utils.js';
 import { basename, dirname } from '../../emulation/path.js';
 

package/src/backends/overlay.ts

@@ -1,10 +1,13 @@
-import { FileSystem, FileSystemMetadata } from '../filesystem.js';
+import type { FileSystemMetadata } from '../filesystem.js';
+import { FileSystem } from '../filesystem.js';
 import { ErrnoError, Errno } from '../error.js';
-import { File, PreloadFile, parseFlag } from '../file.js';
+import type { File } from '../file.js';
+import { PreloadFile, parseFlag } from '../file.js';
 import { Stats } from '../stats.js';
 import { LockedFS } from './locked.js';
 import { dirname } from '../emulation/path.js';
-import { Cred, rootCred } from '../cred.js';
+import type { Cred } from '../cred.js';
+import { rootCred } from '../cred.js';
 import { decode, encode } from '../utils.js';
 import type { Backend } from './backend.js';
 /**

package/src/backends/port/fs.ts

@@ -38,12 +38,16 @@ export class PortFile extends File {
 		);
 	}
 
+	protected _throwNoSync(syscall: string): never {
+		throw new ErrnoError(Errno.ENOTSUP, 'Syncrohnous operations not support on PortFile', this.path, syscall);
+	}
+
 	public stat(): Promise<Stats> {
 		return this.rpc('stat');
 	}
 
 	public statSync(): Stats {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.stat');
+		this._throwNoSync('stat');
 	}
 
 	public truncate(len: number): Promise<void> {
@@ -51,7 +55,7 @@ export class PortFile extends File {
 	}
 
 	public truncateSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.truncate');
+		this._throwNoSync('truncate');
 	}
 
 	public write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number> {
@@ -59,7 +63,7 @@ export class PortFile extends File {
 	}
 
 	public writeSync(): number {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.write');
+		this._throwNoSync('write');
 	}
 
 	public async read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>> {
@@ -68,7 +72,7 @@ export class PortFile extends File {
 	}
 
 	public readSync(): number {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.read');
+		this._throwNoSync('read');
 	}
 
 	public chown(uid: number, gid: number): Promise<void> {
@@ -76,7 +80,7 @@ export class PortFile extends File {
 	}
 
 	public chownSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.chown');
+		this._throwNoSync('chown');
 	}
 
 	public chmod(mode: number): Promise<void> {
@@ -84,7 +88,7 @@ export class PortFile extends File {
 	}
 
 	public chmodSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.chmod');
+		this._throwNoSync('chmod');
 	}
 
 	public utimes(atime: Date, mtime: Date): Promise<void> {
@@ -92,7 +96,7 @@ export class PortFile extends File {
 	}
 
 	public utimesSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.utimes');
+		this._throwNoSync('utimes');
 	}
 
 	public _setType(type: FileType): Promise<void> {
@@ -100,7 +104,7 @@ export class PortFile extends File {
 	}
 
 	public _setTypeSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile._setType');
+		this._throwNoSync('_setType');
 	}
 
 	public close(): Promise<void> {
@@ -108,7 +112,7 @@ export class PortFile extends File {
 	}
 
 	public closeSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.close');
+		this._throwNoSync('close');
 	}
 
 	public sync(): Promise<void> {
@@ -116,7 +120,7 @@ export class PortFile extends File {
 	}
 
 	public syncSync(): void {
-		throw ErrnoError.With('ENOSYS', this.path, 'PortFile.sync');
+		this._throwNoSync('sync');
 	}
 }
 

package/src/config.ts

@@ -18,7 +18,7 @@ function isMountConfig<T extends Backend>(arg: unknown): arg is MountConfigurati
 
 /**
  * Retrieve a file system with the given configuration.
- * @param config A BackendConfig object.
+ * @see MountConfiguration
  */
 export async function resolveMountConfig<T extends Backend>(config: MountConfiguration<T>, _depth = 0): Promise<FilesystemOf<T>> {
 	if (typeof config !== 'object' || config == null) {

package/src/cred.ts

@@ -1,6 +1,7 @@
 /**
  * Credentials used for various operations.
- * Similar to Linux's cred struct. See https://github.com/torvalds/linux/blob/master/include/linux/cred.h
+ * Similar to Linux's cred struct.
+ * @see https://github.com/torvalds/linux/blob/master/include/linux/cred.h
  */
 export interface Cred {
 	uid: number;

package/src/emulation/async.ts

@@ -5,7 +5,8 @@ import type { FileContents } from '../filesystem.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { nop, normalizeMode, type Callback } from '../utils.js';
 import { R_OK } from './constants.js';
-import { Dirent, type Dir } from './dir.js';
+import type { Dirent } from './dir.js';
+import { type Dir } from './dir.js';
 import * as promises from './promises.js';
 import { fd2file } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';

package/src/emulation/promises.ts

@@ -7,7 +7,8 @@ import type { ReadableStream as TReadableStream } from 'node:stream/web';
 import type { Interface as ReadlineInterface } from 'readline';
 import type { ReadableStreamController } from 'stream/web';
 import { Errno, ErrnoError } from '../error.js';
-import { ActionType, File, isAppendable, isReadable, isWriteable, parseFlag, pathExistsAction, pathNotExistsAction } from '../file.js';
+import type { File } from '../file.js';
+import { isAppendable, isExclusive, isReadable, isTruncating, isWriteable, parseFlag } from '../file.js';
 import type { FileContents } from '../filesystem.js';
 import { BigIntStats, FileType, type Stats } from '../stats.js';
 import { normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
@@ -110,7 +111,7 @@ export class FileHandle implements promises.FileHandle {
 			throw new ErrnoError(Errno.EINVAL, 'Encoding not specified');
 		}
 		const encodedData = typeof data == 'string' ? Buffer.from(data, options.encoding!) : data;
-		await this.file.write(encodedData, 0, encodedData.length, null);
+		await this.file.write(encodedData, 0, encodedData.length);
 	}
 
 	/**
@@ -492,41 +493,35 @@ async function _open(path: fs.PathLike, _flag: fs.OpenMode, _mode: fs.Mode = 0o6
 	const { fs, path: resolved } = resolveMount(path);
 
 	if (!(await fs.exists(path, cred))) {
-		switch (pathNotExistsAction(flag)) {
-			case ActionType.CREATE:
-				// Ensure parent exists.
-				const parentStats: Stats = await fs.stat(dirname(resolved), cred);
-				if (parentStats && !parentStats.isDirectory()) {
-					throw ErrnoError.With('ENOTDIR', dirname(path), '_open');
-				}
-				return new FileHandle(await fs.createFile(resolved, flag, mode, cred));
-			case ActionType.THROW:
-				throw ErrnoError.With('ENOENT', path, '_open');
-			default:
-				throw new ErrnoError(Errno.EINVAL, 'Invalid file flag');
+		if ((!isWriteable(flag) && !isAppendable(flag)) || flag == 'r+') {
+			throw ErrnoError.With('ENOENT', path, '_open');
+		}
+		// Create the file
+		const parentStats: Stats = await fs.stat(dirname(resolved), cred);
+		if (parentStats && !parentStats.isDirectory()) {
+			throw ErrnoError.With('ENOTDIR', dirname(path), '_open');
 		}
+		return new FileHandle(await fs.createFile(resolved, flag, mode, cred));
 	}
 
-	switch (pathExistsAction(flag)) {
-		case ActionType.THROW:
-			throw ErrnoError.With('EEXIST', path, '_open');
-		case ActionType.TRUNCATE:
-			/* 
-					In a previous implementation, we deleted the file and
-					re-created it. However, this created a race condition if another
-					asynchronous request was trying to read the file, as the file
-					would not exist for a small period of time.
-				*/
-			const file: File = await fs.openFile(resolved, flag, cred);
-			await file.truncate(0);
-			await file.sync();
-			return new FileHandle(file);
-		case ActionType.NOP:
-			// Must await so thrown errors are caught by the catch below
-			return new FileHandle(await fs.openFile(resolved, flag, cred));
-		default:
-			throw new ErrnoError(Errno.EINVAL, 'Invalid file flag');
+	if (isExclusive(flag)) {
+		throw ErrnoError.With('EEXIST', path, '_open');
 	}
+
+	if (!isTruncating(flag)) {
+		return new FileHandle(await fs.openFile(resolved, flag, cred));
+	}
+
+	/* 
+		In a previous implementation, we deleted the file and
+		re-created it. However, this created a race condition if another
+		asynchronous request was trying to read the file, as the file
+		would not exist for a small period of time.
+	*/
+	const file: File = await fs.openFile(resolved, flag, cred);
+	await file.truncate(0);
+	await file.sync();
+	return new FileHandle(file);
 }
 
 /**

package/src/emulation/shared.ts

@@ -2,12 +2,12 @@
 
 import type { BigIntStatsFs, StatsFs } from 'node:fs';
 import { InMemory } from '../backends/memory.js';
-import { Cred, rootCred } from '../cred.js';
+import type { Cred } from '../cred.js';
+import { rootCred } from '../cred.js';
 import { Errno, ErrnoError } from '../error.js';
 import type { File } from '../file.js';
-import { FileSystem } from '../filesystem.js';
+import type { FileSystem } from '../filesystem.js';
 import { size_max } from '../inode.js';
-import { ZenFsType } from '../stats.js';
 import { normalizePath } from '../utils.js';
 import { resolve, type AbsolutePath } from './path.js';
 
@@ -129,7 +129,7 @@ export function _statfs<const T extends boolean>(fs: FileSystem, bigint?: T): T
 	const bs = md.blockSize || 4096;
 
 	return {
-		type: (bigint ? BigInt : Number)(md.type || ZenFsType),
+		type: (bigint ? BigInt : Number)(md.type),
 		bsize: (bigint ? BigInt : Number)(bs),
 		ffree: (bigint ? BigInt : Number)(md.freeNodes || size_max),
 		files: (bigint ? BigInt : Number)(md.totalNodes || size_max),

package/src/emulation/streams.ts

@@ -1,6 +1,6 @@
 import type * as Node from 'fs';
 import { Readable, Writable } from 'readable-stream';
-import { Callback } from '../utils.js';
+import type { Callback } from '../utils.js';
 import { ErrnoError, Errno } from '../error.js';
 
 export class ReadStream extends Readable implements Node.ReadStream {

package/src/emulation/sync.ts

@@ -1,8 +1,9 @@
 import { Buffer } from 'buffer';
 import type * as fs from 'node:fs';
 import { Errno, ErrnoError } from '../error.js';
-import { ActionType, File, isAppendable, isReadable, isWriteable, parseFlag, pathExistsAction, pathNotExistsAction } from '../file.js';
-import { FileContents } from '../filesystem.js';
+import type { File } from '../file.js';
+import { isAppendable, isExclusive, isReadable, isTruncating, isWriteable, parseFlag } from '../file.js';
+import type { FileContents } from '../filesystem.js';
 import { BigIntStats, FileType, type Stats } from '../stats.js';
 import { normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
 import { COPYFILE_EXCL, F_OK, S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK } from './constants.js';
@@ -131,19 +132,15 @@ function _openSync(path: fs.PathLike, _flag: fs.OpenMode, _mode?: fs.Mode | null
 	const { fs, path: resolved } = resolveMount(path);
 
 	if (!fs.existsSync(resolved, cred)) {
-		switch (pathNotExistsAction(flag)) {
-			case ActionType.CREATE:
-				// Ensure parent exists.
-				const parentStats: Stats = fs.statSync(dirname(resolved), cred);
-				if (!parentStats.isDirectory()) {
-					throw ErrnoError.With('ENOTDIR', dirname(path), '_open');
-				}
-				return fs.createFileSync(resolved, flag, mode, cred);
-			case ActionType.THROW:
-				throw ErrnoError.With('ENOENT', path, '_open');
-			default:
-				throw new ErrnoError(Errno.EINVAL, 'Invalid FileFlag object.');
+		if ((!isWriteable(flag) && !isAppendable(flag)) || flag == 'r+') {
+			throw ErrnoError.With('ENOENT', path, '_open');
+		}
+		// Create the file
+		const parentStats: Stats = fs.statSync(dirname(resolved), cred);
+		if (!parentStats.isDirectory()) {
+			throw ErrnoError.With('ENOTDIR', dirname(path), '_open');
 		}
+		return fs.createFileSync(resolved, flag, mode, cred);
 	}
 
 	const stats: Stats = fs.statSync(resolved, cred);
@@ -152,25 +149,23 @@ function _openSync(path: fs.PathLike, _flag: fs.OpenMode, _mode?: fs.Mode | null
 		throw ErrnoError.With('EACCES', path, '_open');
 	}
 
-	// File exists.
-	switch (pathExistsAction(flag)) {
-		case ActionType.THROW:
-			throw ErrnoError.With('EEXIST', path, '_open');
-		case ActionType.TRUNCATE:
-			// Delete file.
-			fs.unlinkSync(resolved, cred);
-			/*
-				Create file. Use the same mode as the old file.
-				Node itself modifies the ctime when this occurs, so this action
-				will preserve that behavior if the underlying file system
-				supports those properties.
-			*/
-			return fs.createFileSync(resolved, flag, stats.mode, cred);
-		case ActionType.NOP:
-			return fs.openFileSync(resolved, flag, cred);
-		default:
-			throw new ErrnoError(Errno.EINVAL, 'Invalid FileFlag object.');
+	if (isExclusive(flag)) {
+		throw ErrnoError.With('EEXIST', path, '_open');
 	}
+
+	if (!isTruncating(flag)) {
+		return fs.openFileSync(resolved, flag, cred);
+	}
+
+	// Delete file.
+	fs.unlinkSync(resolved, cred);
+	/*
+		Create file. Use the same mode as the old file.
+		Node itself modifies the ctime when this occurs, so this action
+		will preserve that behavior if the underlying file system
+		supports those properties.
+	*/
+	return fs.createFileSync(resolved, flag, stats.mode, cred);
 }
 
 /**
@@ -292,7 +287,7 @@ export function appendFileSync(filename: fs.PathOrFileDescriptor, data: FileCont
 	const encodedData = typeof data == 'string' ? Buffer.from(data, options.encoding!) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 	const file = _openSync(typeof filename == 'number' ? fd2file(filename).path! : filename.toString(), flag, options.mode, true);
 	try {
-		file.writeSync(encodedData, 0, encodedData.byteLength, null);
+		file.writeSync(encodedData, 0, encodedData.byteLength);
 	} finally {
 		file.closeSync();
 	}

package/src/error.ts

@@ -1,7 +1,7 @@
 /**
  * Standard libc error codes. More will be added to this enum and error strings as they are
  * needed.
- * @url https://en.wikipedia.org/wiki/Errno.h
+ * @see https://en.wikipedia.org/wiki/Errno.h
  */
 export enum Errno {
 	/** Operation not permitted */

package/src/file.ts

@@ -1,6 +1,6 @@
 import type { FileReadResult } from 'node:fs/promises';
-import { ErrnoError, Errno } from './error.js';
 import { O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY, S_IFMT } from './emulation/constants.js';
+import { Errno, ErrnoError } from './error.js';
 import type { FileSystem } from './filesystem.js';
 import { size_max } from './inode.js';
 import { Stats, type FileType } from './stats.js';
@@ -32,20 +32,6 @@ declare global {
 	}
 }
 
-/**
- * @hidden
- */
-export enum ActionType {
-	// Indicates that the code should not do anything.
-	NOP = 0,
-	// Indicates that the code should throw an exception.
-	THROW = 1,
-	// Indicates that the code should truncate the file, but only if it is a file.
-	TRUNCATE = 2,
-	// Indicates that the code should create the file.
-	CREATE = 3,
-}
-
 const validFlags = ['r', 'r+', 'rs', 'rs+', 'w', 'wx', 'w+', 'wx+', 'a', 'ax', 'a+', 'ax+'];
 
 export function parseFlag(flag: string | number): string {
@@ -158,25 +144,6 @@ export function isExclusive(flag: string): boolean {
 	return flag.indexOf('x') !== -1;
 }
 
-export function pathExistsAction(flag: string): ActionType {
-	if (isExclusive(flag)) {
-		return ActionType.THROW;
-	}
-
-	if (isTruncating(flag)) {
-		return ActionType.TRUNCATE;
-	}
-
-	return ActionType.NOP;
-}
-
-export function pathNotExistsAction(flag: string): ActionType {
-	if ((isWriteable(flag) || isAppendable(flag)) && flag !== 'r+') {
-		return ActionType.CREATE;
-	}
-	return ActionType.THROW;
-}
-
 export abstract class File {
 	/**
 	 * Get the current file position.
@@ -249,7 +216,7 @@ export abstract class File {
 	 *   the current position.
 	 * @returns Promise resolving to the new length of the buffer
 	 */
-	public abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<number>;
+	public abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
 
 	/**
 	 * Write buffer to the file.
@@ -263,7 +230,7 @@ export abstract class File {
 	 *   data should be written. If position is null, the data will be written at
 	 *   the current position.
 	 */
-	public abstract writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): number;
+	public abstract writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
 
 	/**
 	 * Read data from the file.
@@ -515,7 +482,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 *   data should be written. If position is null, the data will be written at
 	 *   the current position.
 	 */
-	public async write(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = 0): Promise<number> {
+	public async write(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = this.position): Promise<number> {
 		const bytesWritten = this.writeSync(buffer, offset, length, position);
 		await this.sync();
 		return bytesWritten;
@@ -534,9 +501,8 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 *   the current position.
 	 * @returns bytes written
 	 */
-	public writeSync(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = 0): number {
+	public writeSync(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = this.position): number {
 		this.dirty = true;
-		position ??= this.position;
 		if (!isWriteable(this.flag)) {
 			throw new ErrnoError(Errno.EPERM, 'File not opened with a writeable mode.');
 		}

package/src/filesystem.ts

@@ -3,7 +3,7 @@ import { ErrnoError, Errno } from './error.js';
 import { rootCred, type Cred } from './cred.js';
 import { join } from './emulation/path.js';
 import { PreloadFile, parseFlag, type File } from './file.js';
-import type { Stats } from './stats.js';
+import { ZenFsType, type Stats } from './stats.js';
 
 export type FileContents = ArrayBufferView | string;
 
@@ -64,26 +64,17 @@ export interface FileSystemMetadata {
 	/**
 	 * The type of the FS
 	 */
-	type?: number;
+	type: number;
 }
 
 /**
  * Structure for a filesystem. All ZenFS backends must extend this.
  *
- * This class includes some default implementations
+ * This class includes default implementations for `exists` and `existsSync`
  *
- * Assume the following about arguments passed to each API method:
- *
- * - Every path is an absolute path. `.`, `..`, and other items are resolved into an absolute form.
- * - All arguments are present. Any optional arguments at the Node API level have been passed in with their default values.
+ * If you are extending this class, note that every path is an absolute path and all arguments are present.
  */
 export abstract class FileSystem {
-	/**
-	 * Numeric type, used for statfs
-	 * @internal @protected
-	 */
-	_type?: number;
-
 	/**
 	 * Get metadata about the current file system
 	 */
@@ -95,7 +86,7 @@ export abstract class FileSystem {
 			freeSpace: 0,
 			noResizableBuffers: false,
 			noAsyncCache: false,
-			type: this._type,
+			type: ZenFsType,
 		};
 	}
 
@@ -104,8 +95,7 @@ export abstract class FileSystem {
 	public async ready(): Promise<void> {}
 
 	/**
-	 * Asynchronous rename. No arguments other than a possible exception
-	 * are given to the completion callback.
+	 * Asynchronous rename.
 	 */
 	public abstract rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
 	/**
@@ -124,29 +114,27 @@ export abstract class FileSystem {
 	public abstract statSync(path: string, cred: Cred): Stats;
 
 	/**
-	 * Opens the file at path p with the given flag. The file must exist.
-	 * @param p The path to open.
+	 * Opens the file at `path` with the given flag. The file must exist.
+	 * @param path The path to open.
 	 * @param flag The flag to use when opening the file.
 	 */
 	public abstract openFile(path: string, flag: string, cred: Cred): Promise<File>;
 
 	/**
-	 * Opens the file at path p with the given flag. The file must exist.
-	 * @param p The path to open.
+	 * Opens the file at `path` with the given flag. The file must exist.
+	 * @param path The path to open.
 	 * @param flag The flag to use when opening the file.
 	 * @return A File object corresponding to the opened file.
 	 */
 	public abstract openFileSync(path: string, flag: string, cred: Cred): File;
 
 	/**
-	 * Create the file at path p with the given mode. Then, open it with the given
-	 * flag.
+	 * Create the file at `path` with the given mode. Then, open it with the given flag.
 	 */
 	public abstract createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
 
 	/**
-	 * Create the file at path p with the given mode. Then, open it with the given
-	 * flag.
+	 * Create the file at `path` with the given mode. Then, open it with the given flag.
 	 */
 	public abstract createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
 
@@ -169,21 +157,16 @@ export abstract class FileSystem {
 	public abstract rmdirSync(path: string, cred: Cred): void;
 	/**
 	 * Asynchronous `mkdir`.
-	 * @param mode Mode to make the directory using. Can be ignored if
-	 *   the filesystem doesn't support permissions.
+	 * @param mode Mode to make the directory using.
 	 */
 	public abstract mkdir(path: string, mode: number, cred: Cred): Promise<void>;
 	/**
 	 * Synchronous `mkdir`.
-	 * @param mode Mode to make the directory using. Can be ignored if
-	 *   the filesystem doesn't support permissions.
+	 * @param mode Mode to make the directory using.
 	 */
 	public abstract mkdirSync(path: string, mode: number, cred: Cred): void;
 	/**
 	 * Asynchronous `readdir`. Reads the contents of a directory.
-	 *
-	 * The callback gets two arguments `(err, files)` where `files` is an array of
-	 * the names of the files in the directory excluding `'.'` and `'..'`.
 	 */
 	public abstract readdir(path: string, cred: Cred): Promise<string[]>;
 	/**
@@ -352,13 +335,11 @@ type AsyncOperation = {
 /**
  * Async() implements synchronous methods on an asynchronous file system
  *
- * Implementing classes must define a protected _sync property for the synchronous file system used as a cache.
- * by:
- *
- * - Performing operations over the in-memory copy, while asynchronously pipelining them
- *   to the backing store.
- * - During application loading, the contents of the async file system can be reloaded into
- *   the synchronous store, if desired.
+ * Implementing classes must define `_sync` for the synchronous file system used as a cache.
+ * Synchronous methods on an asynchronous FS are implemented by:
+ *	- Performing operations over the in-memory copy,
+ * 	while asynchronously pipelining them to the backing store.
+ * 	- During loading, the contents of the async file system are eloaded into the synchronous store.
  *
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/stats.ts

@@ -1,5 +1,5 @@
 import type * as Node from 'fs';
-import { Cred } from './cred.js';
+import type { Cred } from './cred.js';
 import { S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK, S_IRWXG, S_IRWXO, S_IRWXU } from './emulation/constants.js';
 import { size_max } from './inode.js';