@zenfs/core 0.12.1 → 0.12.3

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;
 
@@ -44,17 +44,35 @@ export interface FileSystemMetadata {
 	 * @default false
 	 */
 	noAsyncCache: boolean;
+
+	/**
+	 * The optimal block size to use with the file system
+	 * @default 4096
+	 */
+	blockSize?: number;
+
+	/**
+	 * Total number of (file) nodes available
+	 */
+	totalNodes?: number;
+
+	/**
+	 * Number of free (file) nodes available
+	 */
+	freeNodes?: number;
+
+	/**
+	 * The type of the FS
+	 */
+	type: number;
 }
 
 /**
  * Structure for a filesystem. All ZenFS backends must extend this.
  *
- * This class includes some default implementations
- *
- * Assume the following about arguments passed to each API method:
+ * This class includes default implementations for `exists` and `existsSync`
  *
- * - 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 {
 	/**
@@ -68,17 +86,16 @@ export abstract class FileSystem {
 			freeSpace: 0,
 			noResizableBuffers: false,
 			noAsyncCache: false,
+			type: ZenFsType,
 		};
 	}
 
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	public constructor(options?: object) {}
+	public constructor() {}
 
 	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>;
 	/**
@@ -97,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;
 
@@ -142,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[]>;
 	/**
@@ -325,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,6 +1,7 @@
 import type * as Node from 'fs';
-import { Cred } from './cred.js';
-import { S_IFDIR, S_IFLNK, S_IFMT, S_IFREG, S_IRWXG, S_IRWXO, S_IRWXU } from './emulation/constants.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';
 
 /**
  * Indicates the type of the given file. Applied to 'mode'.
@@ -60,21 +61,15 @@ export interface StatsLike<T extends number | bigint = number | bigint> {
  * Common code used by both Stats and BigIntStats.
  */
 export abstract class StatsCommon<T extends number | bigint> implements Node.StatsBase<T>, StatsLike {
-	protected abstract _isBigint: boolean;
-
-	protected get _typename(): string {
-		return this._isBigint ? 'bigint' : 'number';
-	}
-
-	protected get _typename_inverse(): string {
-		return this._isBigint ? 'number' : 'bigint';
-	}
+	protected abstract _isBigint: T extends bigint ? true : false;
 
 	protected _convert(arg: number | bigint | string | boolean): T {
 		return (this._isBigint ? BigInt(arg) : Number(arg)) as T;
 	}
 
-	public blocks: T;
+	public get blocks(): T {
+		return this._convert(Math.ceil(Number(this.size) / 512));
+	}
 
 	/**
 	 * Unix-style file mode (e.g. 0o644) that includes the type of the item.
@@ -184,17 +179,15 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	 * Creates a new stats instance from a stats-like object. Can be used to copy stats (note)
 	 */
 	constructor({ atimeMs, mtimeMs, ctimeMs, birthtimeMs, uid, gid, size, mode, ino }: Partial<StatsLike> = {}) {
-		const currentTime = Date.now();
-		const resolveT = (val: number | bigint | undefined, _default: number) =>
-			typeof val == this._typename ? (val as T) : this._convert(typeof val == this._typename_inverse ? val! : _default);
-		this.atimeMs = resolveT(atimeMs, currentTime);
-		this.mtimeMs = resolveT(mtimeMs, currentTime);
-		this.ctimeMs = resolveT(ctimeMs, currentTime);
-		this.birthtimeMs = resolveT(birthtimeMs, currentTime);
-		this.uid = resolveT(uid, 0);
-		this.gid = resolveT(gid, 0);
-		this.size = resolveT(size, 0);
-		this.ino = resolveT(ino, 0);
+		const now = Date.now();
+		this.atimeMs = this._convert(atimeMs ?? now);
+		this.mtimeMs = this._convert(mtimeMs ?? now);
+		this.ctimeMs = this._convert(ctimeMs ?? now);
+		this.birthtimeMs = this._convert(birthtimeMs ?? now);
+		this.uid = this._convert(uid ?? 0);
+		this.gid = this._convert(gid ?? 0);
+		this.size = this._convert(size ?? 0);
+		this.ino = this._convert(ino ?? 0);
 		const itemType: FileType = Number(mode) & S_IFMT || FileType.FILE;
 
 		if (mode) {
@@ -209,8 +202,6 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 					this.mode = this._convert(0o777);
 			}
 		}
-		// number of 512B blocks allocated
-		this.blocks = this._convert(Math.ceil(Number(size) / 512));
 		// Check if mode also includes top-most bits, which indicate the file's type.
 		if ((this.mode & S_IFMT) == 0) {
 			this.mode = (this.mode | this._convert(itemType)) as T;
@@ -241,19 +232,19 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	// Currently unsupported
 
 	public isSocket(): boolean {
-		return false;
+		return (this.mode & S_IFMT) === S_IFSOCK;
 	}
 
 	public isBlockDevice(): boolean {
-		return false;
+		return (this.mode & S_IFMT) === S_IFBLK;
 	}
 
 	public isCharacterDevice(): boolean {
-		return false;
+		return (this.mode & S_IFMT) === S_IFCHR;
 	}
 
 	public isFIFO(): boolean {
-		return false;
+		return (this.mode & S_IFMT) === S_IFIFO;
 	}
 
 	/**
@@ -315,16 +306,16 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	}
 
 	public get atimeNs(): bigint {
-		return BigInt(this.atimeMs);
+		return BigInt(this.atimeMs) * 1000n;
 	}
 	public get mtimeNs(): bigint {
-		return BigInt(this.mtimeMs);
+		return BigInt(this.mtimeMs) * 1000n;
 	}
 	public get ctimeNs(): bigint {
-		return BigInt(this.ctimeMs);
+		return BigInt(this.ctimeMs) * 1000n;
 	}
 	public get birthtimeNs(): bigint {
-		return BigInt(this.birthtimeMs);
+		return BigInt(this.birthtimeMs) * 1000n;
 	}
 }
 
@@ -334,41 +325,35 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
  * Attribute descriptions are from `man 2 stat'
  * @see http://nodejs.org/api/fs.html#fs_class_fs_stats
  * @see http://man7.org/linux/man-pages/man2/stat.2.html
+ * @internal
  */
 export class Stats extends StatsCommon<number> implements Node.Stats, StatsLike {
-	protected _isBigint = false;
-
-	/**
-	 * Clones the stats object.
-	 * @deprecated use `new Stats(stats)`
-	 */
-	public static clone(stats: Stats): Stats {
-		return new Stats(stats);
-	}
+	protected _isBigint = false as const;
 }
 Stats satisfies typeof Node.Stats;
 
 /**
  * Stats with bigint
  * @todo Implement with bigint instead of wrapping Stats
+ * @internal
  */
 export class BigIntStats extends StatsCommon<bigint> implements Node.BigIntStats, StatsLike {
-	protected _isBigint = true;
-
-	/**
-	 * Clone a stats object.
-	 * @deprecated use `new BigIntStats(stats)`
-	 */
-	public static clone(stats: BigIntStats | Stats): BigIntStats {
-		return new BigIntStats(stats);
-	}
+	protected _isBigint = true as const;
 }
 
+/**
+ * @internal
+ */
+export const ZenFsType = 0x7a656e6673; // 'z' 'e' 'n' 'f' 's'
+
+/**
+ * @hidden
+ */
 export class StatsFs implements Node.StatsFsBase<number> {
 	/** Type of file system. */
-	public type: number = 0;
+	public type: number = 0x7a656e6673;
 	/**  Optimal transfer block size. */
-	public bsize: number = 0;
+	public bsize: number = 4096;
 	/**  Total data blocks in file system. */
 	public blocks: number = 0;
 	/** Free blocks in file system. */
@@ -376,16 +361,19 @@ export class StatsFs implements Node.StatsFsBase<number> {
 	/** Available blocks for unprivileged users */
 	public bavail: number = 0;
 	/** Total file nodes in file system. */
-	public files: number = 0;
+	public files: number = size_max;
 	/** Free file nodes in file system. */
-	public ffree: number = 0;
+	public ffree: number = size_max;
 }
 
+/**
+ * @hidden
+ */
 export class BigIntStatsFs implements Node.StatsFsBase<bigint> {
 	/** Type of file system. */
-	public type: bigint = 0n;
+	public type: bigint = 0x7a656e6673n;
 	/**  Optimal transfer block size. */
-	public bsize: bigint = 0n;
+	public bsize: bigint = 4096n;
 	/**  Total data blocks in file system. */
 	public blocks: bigint = 0n;
 	/** Free blocks in file system. */
@@ -393,7 +381,7 @@ export class BigIntStatsFs implements Node.StatsFsBase<bigint> {
 	/** Available blocks for unprivileged users */
 	public bavail: bigint = 0n;
 	/** Total file nodes in file system. */
-	public files: bigint = 0n;
+	public files: bigint = BigInt(size_max);
 	/** Free file nodes in file system. */
-	public ffree: bigint = 0n;
+	public ffree: bigint = BigInt(size_max);
 }

package/src/utils.ts

@@ -1,8 +1,8 @@
 import type { OptionalTuple } from 'utilium';
 import { ErrnoError, Errno } from './error.js';
-import { Cred } from './cred.js';
+import type { Cred } from './cred.js';
 import { dirname, resolve, type AbsolutePath } from './emulation/path.js';
-import { FileSystem } from './filesystem.js';
+import type { FileSystem } from './filesystem.js';
 import type * as fs from 'node:fs';
 
 declare global {