@zenfs/core 1.0.9 → 1.0.11

package/src/file.ts

@@ -6,10 +6,10 @@ import { size_max } from './inode.js';
 import { Stats, type FileType } from './stats.js';
 import './polyfills.js';
 
-/*
+/**
 	Typescript does not include a type declaration for resizable array buffers. 
 	It has been standardized into ECMAScript though
-	Remove this if TS adds them to lib declarations
+	@todo Remove this if TS adds them to lib declarations
 */
 declare global {
 	interface ArrayBuffer {
@@ -152,9 +152,6 @@ export abstract class File {
 		 * The file system that created the file
 		 */
 		public fs: FileSystem,
-		/**
-		 * The path to the file
-		 */
 		public readonly path: string
 	) {}
 
@@ -163,24 +160,10 @@ export abstract class File {
 	 */
 	public abstract position: number;
 
-	/**
-	 * Asynchronous `stat`.
-	 */
 	public abstract stat(): Promise<Stats>;
-
-	/**
-	 * Synchronous `stat`.
-	 */
 	public abstract statSync(): Stats;
 
-	/**
-	 * Asynchronous close.
-	 */
 	public abstract close(): Promise<void>;
-
-	/**
-	 * Synchronous close.
-	 */
 	public abstract closeSync(): void;
 
 	public [Symbol.asyncDispose](): Promise<void> {
@@ -191,65 +174,40 @@ export abstract class File {
 		return this.closeSync();
 	}
 
-	/**
-	 * Asynchronous truncate.
-	 */
 	public abstract truncate(len: number): Promise<void>;
-
-	/**
-	 * Synchronous truncate.
-	 */
 	public abstract truncateSync(len: number): void;
 
-	/**
-	 * Asynchronous sync.
-	 */
 	public abstract sync(): Promise<void>;
-
-	/**
-	 * Synchronous sync.
-	 */
 	public abstract syncSync(): void;
 
 	/**
 	 * Write buffer to the file.
-	 * Note that it is unsafe to use fs.write multiple times on the same file
-	 * without waiting for the callback.
-	 * @param buffer Uint8Array containing the data to write to
-	 *  the file.
+	 * @param buffer Uint8Array containing the data to write to the file.
 	 * @param offset Offset in the buffer to start reading data from.
 	 * @param length The amount of bytes to write to the file.
-	 * @param position Offset from the beginning of the file where this
-	 *   data should be written. If position is null, the data will be written at
-	 *   the current position.
+	 * @param position Offset from the beginning of the file where this data should be written.
+	 * If position is null, the data will be written at the current position.
 	 * @returns Promise resolving to the new length of the buffer
 	 */
 	public abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
 
 	/**
 	 * Write buffer to the file.
-	 * Note that it is unsafe to use fs.writeSync multiple times on the same file
-	 * without waiting for it to return.
-	 * @param buffer Uint8Array containing the data to write to
-	 *  the file.
+	 * @param buffer Uint8Array containing the data to write to the file.
 	 * @param offset Offset in the buffer to start reading data from.
 	 * @param length The amount of bytes to write to the file.
-	 * @param position Offset from the beginning of the file where this
-	 *   data should be written. If position is null, the data will be written at
-	 *   the current position.
+	 * @param position Offset from the beginning of the file where this 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): number;
 
 	/**
 	 * Read data from the file.
-	 * @param buffer The buffer that the data will be
-	 *   written to.
-	 * @param offset The offset within the buffer where writing will
-	 *   start.
+	 * @param buffer The buffer that the data will be written to.
+	 * @param offset The offset within the buffer where writing will start.
 	 * @param length An integer specifying the number of bytes to read.
-	 * @param position An integer specifying where to begin reading from
-	 *   in the file. If position is null, data will be read from the current file
-	 *   position.
+	 * @param position An integer specifying where to begin reading from in the file.
+	 * If position is null, data will be read from the current file position.
 	 * @returns Promise resolving to the new length of the buffer
 	 */
 	public abstract read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>>;
@@ -259,15 +217,12 @@ export abstract class File {
 	 * @param buffer The buffer that the data will be written to.
 	 * @param offset The offset within the buffer where writing will start.
 	 * @param length An integer specifying the number of bytes to read.
-	 * @param position An integer specifying where to begin reading from
-	 *   in the file. If position is null, data will be read from the current file
-	 *   position.
+	 * @param position An integer specifying where to begin reading from in the file.
+	 * If position is null, data will be read from the current file position.
 	 */
 	public abstract readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
 
 	/**
-	 * Asynchronous `datasync`.
-	 *
 	 * Default implementation maps to `sync`.
 	 */
 	public datasync(): Promise<void> {
@@ -275,32 +230,16 @@ export abstract class File {
 	}
 
 	/**
-	 * Synchronous `datasync`.
-	 *
 	 * Default implementation maps to `syncSync`.
 	 */
 	public datasyncSync(): void {
 		return this.syncSync();
 	}
 
-	/**
-	 * Asynchronous `chown`.
-	 */
 	public abstract chown(uid: number, gid: number): Promise<void>;
-
-	/**
-	 * Synchronous `chown`.
-	 */
 	public abstract chownSync(uid: number, gid: number): void;
 
-	/**
-	 * Asynchronous `fchmod`.
-	 */
 	public abstract chmod(mode: number): Promise<void>;
-
-	/**
-	 * Synchronous `fchmod`.
-	 */
 	public abstract chmodSync(mode: number): void;
 
 	/**
@@ -327,9 +266,8 @@ export abstract class File {
 }
 
 /**
- * An implementation of the File interface that operates on a file that is
- * completely in-memory. PreloadFiles are backed by a Uint8Array.
- *
+ * An implementation of `File` that operates completely in-memory.
+ * `PreloadFile`s are backed by a `Uint8Array`.
  */
 export class PreloadFile<FS extends FileSystem> extends File {
 	/**
@@ -348,16 +286,8 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	protected closed: boolean = false;
 
 	/**
-	 * Creates a file with the given path and, optionally, the given contents. Note
-	 * that, if contents is specified, it will be mutated by the file!
-	 * @param _mode The mode that the file was opened using.
-	 *   Dictates permissions and where the file pointer starts.
-	 * @param stats The stats object for the given file.
-	 *   PreloadFile will mutate this object. Note that this object must contain
-	 *   the appropriate mode that the file was opened as.
-	 * @param buffer A buffer containing the entire
-	 *   contents of the file. PreloadFile will mutate this buffer. If not
-	 *   specified, we assume it is a new file.
+	 * Creates a file with `path` and, optionally, the given contents.
+	 * Note that, if contents is specified, it will be mutated by the file.
 	 */
 	public constructor(
 		/**
@@ -368,6 +298,9 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		path: string,
 		public readonly flag: string,
 		public readonly stats: Stats,
+		/**
+		 * A buffer containing the entire contents of the file.
+		 */
 		protected _buffer: Uint8Array = new Uint8Array(new ArrayBuffer(0, fs.metadata().noResizableBuffers ? {} : { maxByteLength: size_max }))
 	) {
 		super(fs, path);
@@ -399,10 +332,10 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	 * Get the current file position.
 	 *
 	 * We emulate the following bug mentioned in the Node documentation:
-	 * > On Linux, positional writes don't work when the file is opened in append
-	 *   mode. The kernel ignores the position argument and always appends the data
-	 *   to the end of the file.
-	 * @return The current file position.
+	 *
+	 * On Linux, positional writes don't work when the file is opened in append mode.
+	 * The kernel ignores the position argument and always appends the data to the end of the file.
+	 * @returns The current file position.
 	 */
 	public get position(): number {
 		if (isAppendable(this.flag)) {
@@ -411,12 +344,8 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		return this._position;
 	}
 
-	/**
-	 * Set the file position.
-	 * @param newPos new position
-	 */
-	public set position(newPos: number) {
-		this._position = newPos;
+	public set position(value: number) {
+		this._position = value;
 	}
 
 	public async sync(): Promise<void> {
@@ -458,8 +387,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 	}
 
 	/**
-	 * Cleans up
-	 * This will *not* sync the file data to the FS
+	 * Cleans up. This will *not* sync the file data to the FS
 	 */
 	protected dispose(force?: boolean): void {
 		if (this.closed) {
@@ -477,9 +405,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		this.closed = true;
 	}
 
-	/**
-	 * Asynchronous `stat`.
-	 */
 	public stat(): Promise<Stats> {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.stat');
@@ -487,9 +412,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		return Promise.resolve(new Stats(this.stats));
 	}
 
-	/**
-	 * Synchronous `stat`.
-	 */
 	public statSync(): Stats {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.stat');
@@ -517,19 +439,11 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		this._buffer = this._buffer.slice(0, length);
 	}
 
-	/**
-	 * Asynchronous truncate.
-	 * @param length
-	 */
 	public async truncate(length: number): Promise<void> {
 		this._truncate(length);
 		await this.sync();
 	}
 
-	/**
-	 * Synchronous truncate.
-	 * @param length
-	 */
 	public truncateSync(length: number): void {
 		this._truncate(length);
 		this.syncSync();
@@ -567,15 +481,11 @@ export class PreloadFile<FS extends FileSystem> extends File {
 
 	/**
 	 * Write buffer to the file.
-	 * Note that it is unsafe to use fs.write multiple times on the same file
-	 * without waiting for the callback.
-	 * @param buffer Uint8Array containing the data to write to
-	 *  the file.
+	 * @param buffer Uint8Array containing the data to write to the file.
 	 * @param offset Offset in the buffer to start reading data from.
 	 * @param length The amount of bytes to write to the file.
-	 * @param position Offset from the beginning of the file where this
-	 *   data should be written. If position is null, the data will be written at
-	 *   the current position.
+	 * @param position Offset from the beginning of the file where this data should be written.
+	 * If position is null, the data will be written at  the current position.
 	 */
 	public async write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number> {
 		const bytesWritten = this._write(buffer, offset, length, position);
@@ -585,15 +495,11 @@ export class PreloadFile<FS extends FileSystem> extends File {
 
 	/**
 	 * Write buffer to the file.
-	 * Note that it is unsafe to use fs.writeSync multiple times on the same file
-	 * without waiting for the callback.
-	 * @param buffer Uint8Array containing the data to write to
-	 *  the file.
+	 * @param buffer Uint8Array containing the data to write to the file.
 	 * @param offset Offset in the buffer to start reading data from.
 	 * @param length The amount of bytes to write to the file.
-	 * @param position Offset from the beginning of the file where this
-	 *   data should be written. If position is null, the data will be written at
-	 *   the current position.
+	 * @param position Offset from the beginning of the file where this data should be written.
+	 * If position is null, the data will be written at  the current position.
 	 * @returns bytes written
 	 */
 	public writeSync(buffer: Uint8Array, offset: number = 0, length: number = this.stats.size, position: number = this.position): number {
@@ -628,14 +534,11 @@ export class PreloadFile<FS extends FileSystem> extends File {
 
 	/**
 	 * Read data from the file.
-	 * @param buffer The buffer that the data will be
-	 *   written to.
-	 * @param offset The offset within the buffer where writing will
-	 *   start.
+	 * @param buffer The buffer that the data will be written to.
+	 * @param offset The offset within the buffer where writing will start.
 	 * @param length An integer specifying the number of bytes to read.
-	 * @param position An integer specifying where to begin reading from
-	 *   in the file. If position is null, data will be read from the current file
-	 *   position.
+	 * @param position An integer specifying where to begin reading from in the file.
+	 * If position is null, data will be read from the current file position.
 	 */
 	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);
@@ -645,13 +548,11 @@ export class PreloadFile<FS extends FileSystem> extends File {
 
 	/**
 	 * Read data from the file.
-	 * @param buffer The buffer that the data will be
-	 *   written to.
+	 * @param buffer The buffer that the data will be written to.
 	 * @param offset The offset within the buffer where writing will start.
 	 * @param length An integer specifying the number of bytes to read.
-	 * @param position An integer specifying where to begin reading from
-	 *   in the file. If position is null, data will be read from the current file
-	 *   position.
+	 * @param position An integer specifying where to begin reading from in the file.
+	 * If position is null, data will be read from the current file position.
 	 * @returns number of bytes written
 	 */
 	public readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number {
@@ -660,10 +561,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		return bytesRead;
 	}
 
-	/**
-	 * Asynchronous `fchmod`.
-	 * @param mode the mode
-	 */
 	public async chmod(mode: number): Promise<void> {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.chmod');
@@ -673,10 +570,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		await this.sync();
 	}
 
-	/**
-	 * Synchronous `fchmod`.
-	 * @param mode
-	 */
 	public chmodSync(mode: number): void {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.chmod');
@@ -686,11 +579,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		this.syncSync();
 	}
 
-	/**
-	 * Asynchronous `fchown`.
-	 * @param uid
-	 * @param gid
-	 */
 	public async chown(uid: number, gid: number): Promise<void> {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.chown');
@@ -700,11 +588,6 @@ export class PreloadFile<FS extends FileSystem> extends File {
 		await this.sync();
 	}
 
-	/**
-	 * Synchronous `fchown`.
-	 * @param uid
-	 * @param gid
-	 */
 	public chownSync(uid: number, gid: number): void {
 		if (this.closed) {
 			throw ErrnoError.With('EBADF', this.path, 'File.chown');
@@ -762,34 +645,18 @@ export class PreloadFile<FS extends FileSystem> extends File {
 }
 
 /**
- * For the filesystems which do not sync to anything..
+ * For the file systems which do not sync to anything.
  */
 export class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
-	public constructor(fs: T, path: string, flag: string, stats: Stats, contents?: Uint8Array) {
-		super(fs, path, flag, stats, contents);
-	}
-	/**
-	 * Asynchronous sync. Doesn't do anything, simply calls the cb.
-	 */
 	public sync(): Promise<void> {
 		return Promise.resolve();
 	}
-	/**
-	 * Synchronous sync. Doesn't do anything.
-	 */
-	public syncSync(): void {
-		// NOP.
-	}
-	/**
-	 * Asynchronous close. Doesn't do anything, simply calls the cb.
-	 */
+
+	public syncSync(): void {}
+
 	public close(): Promise<void> {
 		return Promise.resolve();
 	}
-	/**
-	 * Synchronous close. Doesn't do anything.
-	 */
-	public closeSync(): void {
-		// NOP.
-	}
+
+	public closeSync(): void {}
 }

package/src/filesystem.ts

@@ -14,7 +14,7 @@ export interface FileSystemMetadata {
 	name: string;
 
 	/**
-	 * Wheter the FS is readonly or not
+	 * Whether the FS is readonly or not
 	 */
 	readonly: boolean;
 
@@ -65,11 +65,10 @@ export interface FileSystemMetadata {
 }
 
 /**
- * Structure for a filesystem. All ZenFS backends must extend this.
- *
- * This class includes default implementations for `exists` and `existsSync`
- *
+ * Provides a consistent and easy to use internal API.
+ * Default implementations for `exists` and `existsSync` are included.
  * If you are extending this class, note that every path is an absolute path and all arguments are present.
+ * @internal
  */
 export abstract class FileSystem {
 	/**
@@ -99,88 +98,52 @@ export abstract class FileSystem {
 
 	public async ready(): Promise<void> {}
 
-	/**
-	 * Asynchronous rename.
-	 */
 	public abstract rename(oldPath: string, newPath: string): Promise<void>;
-	/**
-	 * Synchronous rename.
-	 */
 	public abstract renameSync(oldPath: string, newPath: string): void;
 
-	/**
-	 * Asynchronous `stat`.
-	 */
 	public abstract stat(path: string): Promise<Stats>;
-
-	/**
-	 * Synchronous `stat`.
-	 */
 	public abstract statSync(path: string): Stats;
 
 	/**
-	 * Opens the file at `path` with the given flag. The file must exist.
+	 * Opens the file at `path` with `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): Promise<File>;
 
 	/**
-	 * Opens the file at `path` with the given flag. The file must exist.
+	 * Opens the file at `path` with `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): File;
 
 	/**
-	 * Create the file at `path` with the given mode. Then, open it with the given flag.
+	 * Create the file at `path` with `mode`. Then, open it with `flag`.
 	 */
 	public abstract createFile(path: string, flag: string, mode: number): Promise<File>;
 
 	/**
-	 * Create the file at `path` with the given mode. Then, open it with the given flag.
+	 * Create the file at `path` with `mode`. Then, open it with `flag`.
 	 */
 	public abstract createFileSync(path: string, flag: string, mode: number): File;
 
-	/**
-	 * Asynchronous `unlink`.
-	 */
 	public abstract unlink(path: string): Promise<void>;
-	/**
-	 * Synchronous `unlink`.
-	 */
 	public abstract unlinkSync(path: string): void;
+
 	// Directory operations
-	/**
-	 * Asynchronous `rmdir`.
-	 */
+
 	public abstract rmdir(path: string): Promise<void>;
-	/**
-	 * Synchronous `rmdir`.
-	 */
 	public abstract rmdirSync(path: string): void;
-	/**
-	 * Asynchronous `mkdir`.
-	 * @param mode Mode to make the directory using.
-	 */
+
 	public abstract mkdir(path: string, mode: number): Promise<void>;
-	/**
-	 * Synchronous `mkdir`.
-	 * @param mode Mode to make the directory using.
-	 */
 	public abstract mkdirSync(path: string, mode: number): void;
-	/**
-	 * Asynchronous `readdir`. Reads the contents of a directory.
-	 */
+
 	public abstract readdir(path: string): Promise<string[]>;
-	/**
-	 * Synchronous `readdir`. Reads the contents of a directory.
-	 */
 	public abstract readdirSync(path: string): string[];
 
 	/**
-	 * Test whether or not the given path exists.
+	 * Test whether or not `path` exists.
 	 */
 	public async exists(path: string): Promise<boolean> {
 		try {
@@ -192,7 +155,7 @@ export abstract class FileSystem {
 	}
 
 	/**
-	 * Test whether or not the given path exists.
+	 * Test whether or not `path` exists.
 	 */
 	public existsSync(path: string): boolean {
 		try {
@@ -203,23 +166,9 @@ export abstract class FileSystem {
 		}
 	}
 
-	/**
-	 * Asynchronous `link`.
-	 */
 	public abstract link(target: string, link: string): Promise<void>;
-
-	/**
-	 * Synchronous `link`.
-	 */
 	public abstract linkSync(target: string, link: string): void;
 
-	/**
-	 * Synchronize the data and stats for path asynchronously
-	 */
 	public abstract sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-
-	/**
-	 * Synchronize the data and stats for path synchronously
-	 */
 	public abstract syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }

package/src/mixins/async.ts

@@ -3,14 +3,12 @@ import { Errno, ErrnoError } from '../error.js';
 import { parseFlag, PreloadFile, type File } from '../file.js';
 import type { FileSystem } from '../filesystem.js';
 import type { Stats } from '../stats.js';
-import type { _AsyncFSMethods, Mixin } from './shared.js';
+import type { AsyncFSMethods, Mixin } from './shared.js';
 
-/**
- * @internal
- */
+/** @internal */
 export type AsyncOperation = {
-	[K in keyof _AsyncFSMethods]: [K, ...Parameters<FileSystem[K]>];
-}[keyof _AsyncFSMethods];
+	[K in keyof AsyncFSMethods]: [K, ...Parameters<FileSystem[K]>];
+}[keyof AsyncFSMethods];
 
 /**
  * Async() implements synchronous methods on an asynchronous file system

package/src/mixins/mutexed.ts

@@ -227,15 +227,15 @@ export class _MutexedFS<T extends FileSystem> implements FileSystem {
  * This serializes access to an underlying async filesystem.
  * For example, on an OverlayFS instance with an async lower
  * directory operations like rename and rmdir may involve multiple
- * requests involving both the upper and lower filesystems -- they
+ * requests involving both the upper and lower file systems -- they
  * are not executed in a single atomic step. OverlayFS uses this
  * to avoid having to reason about the correctness of
  * multiple requests interleaving.
  *
- * Note:
+ * @privateRemarks
  * Instead of extending the passed class, `MutexedFS` stores it internally.
- * This is to avoid a deadlock caused when a mathod calls another one
- * The problem is discussed extensivly in [#78](https://github.com/zen-fs/core/issues/78)
+ * This is to avoid a deadlock caused when a method calls another one
+ * The problem is discussed extensively in [#78](https://github.com/zen-fs/core/issues/78)
  * Instead of extending `FileSystem`,
  * `MutexedFS` implements it in order to make sure all of the methods are passed through
  *