@zenfs/core 1.1.6 → 1.2.0

package/src/filesystem.ts

@@ -0,0 +1,174 @@
+import type { ErrnoError } from './error.js';
+import type { File } from './file.js';
+import { ZenFsType, type Stats } from './stats.js';
+
+export type FileContents = ArrayBufferView | string;
+
+/**
+ * Metadata about a FileSystem
+ */
+export interface FileSystemMetadata {
+	/**
+	 * The name of the FS
+	 */
+	name: string;
+
+	/**
+	 * Whether the FS is readonly or not
+	 */
+	readonly: boolean;
+
+	/**
+	 * The total space
+	 */
+	totalSpace: number;
+
+	/**
+	 * The available space
+	 */
+	freeSpace: number;
+
+	/**
+	 * If set, disables File from using a resizable array buffer.
+	 * @default false
+	 */
+	noResizableBuffers: boolean;
+
+	/**
+	 * If set, disables caching on async file systems.
+	 * This means *sync operations will not work*.
+	 * It has no affect on sync file systems.
+	 * @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;
+}
+
+/**
+ * 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 {
+	/**
+	 * Get metadata about the current file system
+	 */
+	public metadata(): FileSystemMetadata {
+		return {
+			name: this.constructor.name.toLowerCase(),
+			readonly: false,
+			totalSpace: 0,
+			freeSpace: 0,
+			noResizableBuffers: false,
+			noAsyncCache: this._disableSync ?? false,
+			type: ZenFsType,
+		};
+	}
+
+	/**
+	 * Whether the sync cache should be disabled.
+	 * Only affects async things.
+	 * @internal @protected
+	 */
+	_disableSync?: boolean;
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+	public constructor(...args: any[]) {}
+
+	public async ready(): Promise<void> {}
+
+	public abstract rename(oldPath: string, newPath: string): Promise<void>;
+	public abstract renameSync(oldPath: string, newPath: string): void;
+
+	public abstract stat(path: string): Promise<Stats>;
+	public abstract statSync(path: string): Stats;
+
+	/**
+	 * 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 `flag`. The file must exist.
+	 * @param path The path to open.
+	 * @param flag The flag to use when opening the file.
+	 */
+	public abstract openFileSync(path: string, flag: string): File;
+
+	/**
+	 * 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 `mode`. Then, open it with `flag`.
+	 */
+	public abstract createFileSync(path: string, flag: string, mode: number): File;
+
+	public abstract unlink(path: string): Promise<void>;
+	public abstract unlinkSync(path: string): void;
+
+	// Directory operations
+
+	public abstract rmdir(path: string): Promise<void>;
+	public abstract rmdirSync(path: string): void;
+
+	public abstract mkdir(path: string, mode: number): Promise<void>;
+	public abstract mkdirSync(path: string, mode: number): void;
+
+	public abstract readdir(path: string): Promise<string[]>;
+	public abstract readdirSync(path: string): string[];
+
+	/**
+	 * Test whether or not `path` exists.
+	 */
+	public async exists(path: string): Promise<boolean> {
+		try {
+			await this.stat(path);
+			return true;
+		} catch (e) {
+			return (e as ErrnoError).code != 'ENOENT';
+		}
+	}
+
+	/**
+	 * Test whether or not `path` exists.
+	 */
+	public existsSync(path: string): boolean {
+		try {
+			this.statSync(path);
+			return true;
+		} catch (e) {
+			return (e as ErrnoError).code != 'ENOENT';
+		}
+	}
+
+	public abstract link(target: string, link: string): Promise<void>;
+	public abstract linkSync(target: string, link: string): void;
+
+	public abstract sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+	public abstract syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from './error.js';
+export * from './backends/port/fs.js';
+export * from './backends/fetch.js';
+export * from './backends/memory.js';
+export * from './backends/file_index.js';
+export * from './backends/overlay.js';
+export * from './backends/store/fs.js';
+export * from './backends/store/simple.js';
+export * from './backends/store/store.js';
+export * from './backends/backend.js';
+export * from './config.js';
+export * from './credentials.js';
+export * from './devices.js';
+export { default as devices } from './devices.js';
+export * from './file.js';
+export * from './filesystem.js';
+export * from './inode.js';
+export * from './mixins/index.js';
+export * from './stats.js';
+export * from './utils.js';
+
+export * from './emulation/index.js';
+import * as fs from './emulation/index.js';
+export { fs };
+export default fs;

package/src/inode.ts

@@ -0,0 +1,132 @@
+import { Stats, type StatsLike } from './stats.js';
+import { types as t, struct, sizeof, serialize, deserialize } from 'utilium';
+
+/**
+ * Alias for an ino.
+ * This will be helpful if in the future inode numbers/IDs are changed to strings or numbers.
+ */
+export type Ino = bigint;
+
+/**
+ * Room inode
+ * @hidden
+ */
+export const rootIno = 0n;
+
+/**
+ * Generates a random 32 bit integer, then converts to a hex string
+ */
+function _random() {
+	return Math.round(Math.random() * 2 ** 32).toString(16);
+}
+
+/**
+ * Generate a random ino
+ * @internal
+ */
+export function randomIno(): Ino {
+	return BigInt('0x' + _random() + _random());
+}
+
+/**
+ * Generic inode definition that can easily be serialized.
+ */
+@struct()
+export class Inode implements StatsLike {
+	public get data(): Uint8Array {
+		return serialize(this);
+	}
+
+	public constructor(buffer?: ArrayBufferLike) {
+		if (buffer) {
+			if (buffer.byteLength < sizeof(Inode)) {
+				throw new RangeError(`Can not create an inode from a buffer less than ${sizeof(Inode)} bytes`);
+			}
+
+			deserialize(this, buffer);
+			return;
+		}
+
+		// set defaults on a fresh inode
+		this.ino = randomIno();
+		this.nlink = 1;
+		this.size = 4096;
+		const now = Date.now();
+		this.atimeMs = now;
+		this.mtimeMs = now;
+		this.ctimeMs = now;
+		this.birthtimeMs = now;
+	}
+
+	@t.uint64 public ino!: Ino;
+	@t.uint32 public size!: number;
+	@t.uint16 public mode!: number;
+	@t.uint32 public nlink!: number;
+	@t.uint32 public uid!: number;
+	@t.uint32 public gid!: number;
+	@t.float64 public atimeMs!: number;
+	@t.float64 public birthtimeMs!: number;
+	@t.float64 public mtimeMs!: number;
+	@t.float64 public ctimeMs!: number;
+
+	/**
+	 * Handy function that converts the Inode to a Node Stats object.
+	 */
+	public toStats(): Stats {
+		return new Stats(this);
+	}
+
+	/**
+	 * Updates the Inode using information from the stats object. Used by file
+	 * systems at sync time, e.g.:
+	 * - Program opens file and gets a File object.
+	 * - Program mutates file. File object is responsible for maintaining
+	 *   metadata changes locally -- typically in a Stats object.
+	 * - Program closes file. File object's metadata changes are synced with the
+	 *   file system.
+	 * @return True if any changes have occurred.
+	 */
+	public update(stats: Readonly<Stats>): boolean {
+		let hasChanged = false;
+		if (this.size !== stats.size) {
+			this.size = stats.size;
+			hasChanged = true;
+		}
+
+		if (this.mode !== stats.mode) {
+			this.mode = stats.mode;
+			hasChanged = true;
+		}
+
+		if (this.nlink !== stats.nlink) {
+			this.nlink = stats.nlink;
+			hasChanged = true;
+		}
+
+		if (this.uid !== stats.uid) {
+			this.uid = stats.uid;
+			hasChanged = true;
+		}
+
+		if (this.uid !== stats.uid) {
+			this.uid = stats.uid;
+			hasChanged = true;
+		}
+
+		if (this.atimeMs !== stats.atimeMs) {
+			this.atimeMs = stats.atimeMs;
+			hasChanged = true;
+		}
+		if (this.mtimeMs !== stats.mtimeMs) {
+			this.mtimeMs = stats.mtimeMs;
+			hasChanged = true;
+		}
+
+		if (this.ctimeMs !== stats.ctimeMs) {
+			this.ctimeMs = stats.ctimeMs;
+			hasChanged = true;
+		}
+
+		return hasChanged;
+	}
+}

package/src/mixins/async.ts

@@ -0,0 +1,208 @@
+import { join } from '../emulation/path.js';
+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';
+
+/** @internal */
+export type AsyncOperation = {
+	[K in keyof AsyncFSMethods]: [K, ...Parameters<FileSystem[K]>];
+}[keyof AsyncFSMethods];
+
+/**
+ * Async() implements synchronous methods on an asynchronous file system
+ *
+ * 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 preloaded into the synchronous store.
+ *
+ */
+export function Async<T extends typeof FileSystem>(
+	FS: T
+): Mixin<
+	T,
+	{
+		/**
+		 * @internal @protected
+		 */
+		_sync?: FileSystem;
+		queueDone(): Promise<void>;
+		ready(): Promise<void>;
+		renameSync(oldPath: string, newPath: string): void;
+		statSync(path: string): Stats;
+		createFileSync(path: string, flag: string, mode: number): File;
+		openFileSync(path: string, flag: string): File;
+		unlinkSync(path: string): void;
+		rmdirSync(path: string): void;
+		mkdirSync(path: string, mode: number): void;
+		readdirSync(path: string): string[];
+		linkSync(srcpath: string, dstpath: string): void;
+		syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+	}
+> {
+	abstract class AsyncFS extends FS {
+		/**
+		 * Queue of pending asynchronous operations.
+		 */
+		private _queue: AsyncOperation[] = [];
+		private get _queueRunning(): boolean {
+			return !!this._queue.length;
+		}
+
+		public queueDone(): Promise<void> {
+			return new Promise(resolve => {
+				const check = (): unknown => (this._queueRunning ? setTimeout(check) : resolve());
+				check();
+			});
+		}
+
+		private _isInitialized: boolean = false;
+
+		abstract _sync?: FileSystem;
+
+		public async ready(): Promise<void> {
+			await super.ready();
+			if (this._isInitialized || this._disableSync) {
+				return;
+			}
+			this.checkSync();
+
+			await this._sync.ready();
+
+			try {
+				await this.crossCopy('/');
+				this._isInitialized = true;
+			} catch (e) {
+				this._isInitialized = false;
+				throw e;
+			}
+		}
+
+		protected checkSync(path?: string, syscall?: string): asserts this is { _sync: FileSystem } {
+			if (this._disableSync) {
+				throw new ErrnoError(Errno.ENOTSUP, 'Sync caching has been disabled for this async file system', path, syscall);
+			}
+			if (!this._sync) {
+				throw new ErrnoError(Errno.ENOTSUP, 'No sync cache is attached to this async file system', path, syscall);
+			}
+		}
+
+		public renameSync(oldPath: string, newPath: string): void {
+			this.checkSync(oldPath, 'rename');
+			this._sync.renameSync(oldPath, newPath);
+			this.queue('rename', oldPath, newPath);
+		}
+
+		public statSync(path: string): Stats {
+			this.checkSync(path, 'stat');
+			return this._sync.statSync(path);
+		}
+
+		public createFileSync(path: string, flag: string, mode: number): PreloadFile<this> {
+			this.checkSync(path, 'createFile');
+			this._sync.createFileSync(path, flag, mode);
+			this.queue('createFile', path, flag, mode);
+			return this.openFileSync(path, flag);
+		}
+
+		public openFileSync(path: string, flag: string): PreloadFile<this> {
+			this.checkSync(path, 'openFile');
+			const file = this._sync.openFileSync(path, flag);
+			const stats = file.statSync();
+			const buffer = new Uint8Array(stats.size);
+			file.readSync(buffer);
+			return new PreloadFile(this, path, flag, stats, buffer);
+		}
+
+		public unlinkSync(path: string): void {
+			this.checkSync(path, 'unlinkSync');
+			this._sync.unlinkSync(path);
+			this.queue('unlink', path);
+		}
+
+		public rmdirSync(path: string): void {
+			this.checkSync(path, 'rmdir');
+			this._sync.rmdirSync(path);
+			this.queue('rmdir', path);
+		}
+
+		public mkdirSync(path: string, mode: number): void {
+			this.checkSync(path, 'mkdir');
+			this._sync.mkdirSync(path, mode);
+			this.queue('mkdir', path, mode);
+		}
+
+		public readdirSync(path: string): string[] {
+			this.checkSync(path, 'readdir');
+			return this._sync.readdirSync(path);
+		}
+
+		public linkSync(srcpath: string, dstpath: string): void {
+			this.checkSync(srcpath, 'link');
+			this._sync.linkSync(srcpath, dstpath);
+			this.queue('link', srcpath, dstpath);
+		}
+
+		public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
+			this.checkSync(path, 'sync');
+			this._sync.syncSync(path, data, stats);
+			this.queue('sync', path, data, stats);
+		}
+
+		public existsSync(path: string): boolean {
+			this.checkSync(path, 'exists');
+			return this._sync.existsSync(path);
+		}
+
+		/**
+		 * @internal
+		 */
+		protected async crossCopy(path: string): Promise<void> {
+			this.checkSync(path, 'crossCopy');
+			const stats = await this.stat(path);
+			if (!stats.isDirectory()) {
+				await using asyncFile = await this.openFile(path, parseFlag('r'));
+				using syncFile = this._sync.createFileSync(path, parseFlag('w'), stats.mode);
+				const buffer = new Uint8Array(stats.size);
+				await asyncFile.read(buffer);
+				syncFile.writeSync(buffer, 0, stats.size);
+				return;
+			}
+			if (path !== '/') {
+				const stats = await this.stat(path);
+				this._sync.mkdirSync(path, stats.mode);
+			}
+			const files = await this.readdir(path);
+			for (const file of files) {
+				await this.crossCopy(join(path, file));
+			}
+		}
+
+		/**
+		 * @internal
+		 */
+		private async _next(): Promise<void> {
+			if (!this._queueRunning) {
+				return;
+			}
+
+			const [method, ...args] = this._queue.shift()!;
+			// @ts-expect-error 2556 (since ...args is not correctly picked up as being a tuple)
+			await this[method](...args);
+			await this._next();
+		}
+
+		/**
+		 * @internal
+		 */
+		private queue(...op: AsyncOperation) {
+			this._queue.push(op);
+			void this._next();
+		}
+	}
+
+	return AsyncFS;
+}

package/src/mixins/index.ts

@@ -0,0 +1,5 @@
+export * from './async.js';
+export * from './mutexed.js';
+export * from './readonly.js';
+export * from './shared.js';
+export * from './sync.js';