@zenfs/core 0.11.2 → 0.12.1

package/src/filesystem.ts

@@ -30,6 +30,20 @@ export interface FileSystemMetadata {
 	 * 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;
 }
 
 /**
@@ -44,7 +58,7 @@ export interface FileSystemMetadata {
  */
 export abstract class FileSystem {
 	/**
-	 * Get metadata about the current file syste,
+	 * Get metadata about the current file system
 	 */
 	public metadata(): FileSystemMetadata {
 		return {
@@ -52,12 +66,13 @@ export abstract class FileSystem {
 			readonly: false,
 			totalSpace: 0,
 			freeSpace: 0,
+			noResizableBuffers: false,
+			noAsyncCache: false,
 		};
 	}
 
-	public constructor(options?: object) {
-		// unused
-	}
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	public constructor(options?: object) {}
 
 	public async ready(): Promise<void> {}
 
@@ -157,7 +172,7 @@ export abstract class FileSystem {
 			await this.stat(path, cred);
 			return true;
 		} catch (e) {
-			return false;
+			return (e as ErrnoError).code != 'ENOENT';
 		}
 	}
 
@@ -169,7 +184,7 @@ export abstract class FileSystem {
 			this.statSync(path, cred);
 			return true;
 		} catch (e) {
-			return false;
+			return (e as ErrnoError).code != 'ENOENT';
 		}
 	}
 
@@ -198,19 +213,19 @@ export abstract class FileSystem {
  * @internal
  */
 declare abstract class SyncFS extends FileSystem {
-	metadata(): FileSystemMetadata;
-	ready(): Promise<void>;
-	exists(path: string, cred: Cred): Promise<boolean>;
-	rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-	stat(path: string, cred: Cred): Promise<Stats>;
-	createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
-	openFile(path: string, flag: string, cred: Cred): Promise<File>;
-	unlink(path: string, cred: Cred): Promise<void>;
-	rmdir(path: string, cred: Cred): Promise<void>;
-	mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-	readdir(path: string, cred: Cred): Promise<string[]>;
-	link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-	sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+	public metadata(): FileSystemMetadata;
+	public ready(): Promise<void>;
+	public exists(path: string, cred: Cred): Promise<boolean>;
+	public rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+	public stat(path: string, cred: Cred): Promise<Stats>;
+	public createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
+	public openFile(path: string, flag: string, cred: Cred): Promise<File>;
+	public unlink(path: string, cred: Cred): Promise<void>;
+	public rmdir(path: string, cred: Cred): Promise<void>;
+	public mkdir(path: string, mode: number, cred: Cred): Promise<void>;
+	public readdir(path: string, cred: Cred): Promise<string[]>;
+	public link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
+	public sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
 }
 
 /**
@@ -268,25 +283,33 @@ export function Sync<T extends abstract new (...args: any[]) => FileSystem>(FS:
 
 /**
  * @internal
+ * Note: `_*` should be treated like protected.
+ * Protected can't be used because of TS quirks however.
  */
 declare abstract class AsyncFS extends FileSystem {
 	/**
+	 * @access protected
 	 * @hidden
 	 */
-	abstract _sync: FileSystem;
-	queueDone(): Promise<void>;
-	metadata(): FileSystemMetadata;
-	ready(): Promise<void>;
-	renameSync(oldPath: string, newPath: string, cred: Cred): void;
-	statSync(path: string, cred: Cred): Stats;
-	createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
-	openFileSync(path: string, flag: string, cred: Cred): File;
-	unlinkSync(path: string, cred: Cred): void;
-	rmdirSync(path: string, cred: Cred): void;
-	mkdirSync(path: string, mode: number, cred: Cred): void;
-	readdirSync(path: string, cred: Cred): string[];
-	linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-	syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+	_disableSync: boolean;
+	/**
+	 * @access protected
+	 * @hidden
+	 */
+	abstract _sync?: FileSystem;
+	public queueDone(): Promise<void>;
+	public metadata(): FileSystemMetadata;
+	public ready(): Promise<void>;
+	public renameSync(oldPath: string, newPath: string, cred: Cred): void;
+	public statSync(path: string, cred: Cred): Stats;
+	public createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
+	public openFileSync(path: string, flag: string, cred: Cred): File;
+	public unlinkSync(path: string, cred: Cred): void;
+	public rmdirSync(path: string, cred: Cred): void;
+	public mkdirSync(path: string, mode: number, cred: Cred): void;
+	public readdirSync(path: string, cred: Cred): string[];
+	public linkSync(srcpath: string, dstpath: string, cred: Cred): void;
+	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -331,14 +354,18 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 
 		private _isInitialized: boolean = false;
 
-		abstract _sync: FileSystem;
+		_disableSync: boolean = false;
+
+		abstract _sync?: FileSystem;
 
 		public async ready(): Promise<void> {
-			await this._sync.ready();
 			await super.ready();
-			if (this._isInitialized) {
+			if (this._isInitialized || this._disableSync) {
 				return;
 			}
+			this.checkSync();
+
+			await this._sync.ready();
 
 			try {
 				await this.crossCopy('/');
@@ -349,22 +376,42 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 			}
 		}
 
+		public metadata(): FileSystemMetadata {
+			return {
+				...super.metadata(),
+				noAsyncCache: this._disableSync,
+			};
+		}
+
+		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, cred: Cred): void {
+			this.checkSync(oldPath, 'rename');
 			this._sync.renameSync(oldPath, newPath, cred);
 			this.queue('rename', oldPath, newPath, cred);
 		}
 
 		public statSync(path: string, cred: Cred): Stats {
+			this.checkSync(path, 'stat');
 			return this._sync.statSync(path, cred);
 		}
 
 		public createFileSync(path: string, flag: string, mode: number, cred: Cred): PreloadFile<this> {
+			this.checkSync(path, 'createFile');
 			this._sync.createFileSync(path, flag, mode, cred);
 			this.queue('createFile', path, flag, mode, cred);
 			return this.openFileSync(path, flag, cred);
 		}
 
 		public openFileSync(path: string, flag: string, cred: Cred): PreloadFile<this> {
+			this.checkSync(path, 'openFile');
 			const file = this._sync.openFileSync(path, flag, cred);
 			const stats = file.statSync();
 			const buffer = new Uint8Array(stats.size);
@@ -373,35 +420,42 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 		}
 
 		public unlinkSync(path: string, cred: Cred): void {
+			this.checkSync(path, 'unlinkSync');
 			this._sync.unlinkSync(path, cred);
 			this.queue('unlink', path, cred);
 		}
 
 		public rmdirSync(path: string, cred: Cred): void {
+			this.checkSync(path, 'rmdir');
 			this._sync.rmdirSync(path, cred);
 			this.queue('rmdir', path, cred);
 		}
 
 		public mkdirSync(path: string, mode: number, cred: Cred): void {
+			this.checkSync(path, 'mkdir');
 			this._sync.mkdirSync(path, mode, cred);
 			this.queue('mkdir', path, mode, cred);
 		}
 
 		public readdirSync(path: string, cred: Cred): string[] {
+			this.checkSync(path, 'readdir');
 			return this._sync.readdirSync(path, cred);
 		}
 
 		public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
+			this.checkSync(srcpath, 'link');
 			this._sync.linkSync(srcpath, dstpath, cred);
 			this.queue('link', srcpath, dstpath, cred);
 		}
 
 		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, cred: Cred): boolean {
+			this.checkSync(path, 'exists');
 			return this._sync.existsSync(path, cred);
 		}
 
@@ -409,6 +463,7 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 		 * @internal
 		 */
 		protected async crossCopy(path: string): Promise<void> {
+			this.checkSync(path, 'crossCopy');
 			const stats = await this.stat(path, rootCred);
 			if (stats.isDirectory()) {
 				if (path !== '/') {
@@ -463,21 +518,21 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
  * @internal
  */
 declare abstract class ReadonlyFS extends FileSystem {
-	metadata(): FileSystemMetadata;
-	rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-	renameSync(oldPath: string, newPath: string, cred: Cred): void;
-	createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
-	createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
-	unlink(path: string, cred: Cred): Promise<void>;
-	unlinkSync(path: string, cred: Cred): void;
-	rmdir(path: string, cred: Cred): Promise<void>;
-	rmdirSync(path: string, cred: Cred): void;
-	mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-	mkdirSync(path: string, mode: number, cred: Cred): void;
-	link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-	linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-	sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-	syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+	public metadata(): FileSystemMetadata;
+	public rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+	public renameSync(oldPath: string, newPath: string, cred: Cred): void;
+	public createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
+	public createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
+	public unlink(path: string, cred: Cred): Promise<void>;
+	public unlinkSync(path: string, cred: Cred): void;
+	public rmdir(path: string, cred: Cred): Promise<void>;
+	public rmdirSync(path: string, cred: Cred): void;
+	public mkdir(path: string, mode: number, cred: Cred): Promise<void>;
+	public mkdirSync(path: string, mode: number, cred: Cred): void;
+	public link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
+	public linkSync(srcpath: string, dstpath: string, cred: Cred): void;
+	public sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+	public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
 
 /**

package/src/index.ts

@@ -2,7 +2,7 @@ export * from './error.js';
 export * from './backends/port/fs.js';
 export * from './backends/fetch.js';
 export * from './backends/memory.js';
-export * from './backends/Index.js';
+export * from './backends/index/fs.js';
 export * from './backends/locked.js';
 export * from './backends/overlay.js';
 export * from './backends/store/fs.js';

package/src/stats.ts

@@ -14,45 +14,45 @@ export enum FileType {
 /**
  *
  */
-export interface StatsLike {
+export interface StatsLike<T extends number | bigint = number | bigint> {
 	/**
 	 * Size of the item in bytes.
 	 * For directories/symlinks, this is normally the size of the struct that represents the item.
 	 */
-	size: number | bigint;
+	size: T;
 	/**
 	 * Unix-style file mode (e.g. 0o644) that includes the item type
 	 * Type of the item can be FILE, DIRECTORY, SYMLINK, or SOCKET
 	 */
-	mode: number | bigint;
+	mode: T;
 	/**
 	 * time of last access, in milliseconds since epoch
 	 */
-	atimeMs: number | bigint;
+	atimeMs: T;
 	/**
 	 * time of last modification, in milliseconds since epoch
 	 */
-	mtimeMs: number | bigint;
+	mtimeMs: T;
 	/**
 	 * time of last time file status was changed, in milliseconds since epoch
 	 */
-	ctimeMs: number | bigint;
+	ctimeMs: T;
 	/**
 	 * time of file creation, in milliseconds since epoch
 	 */
-	birthtimeMs: number | bigint;
+	birthtimeMs: T;
 	/**
 	 * the id of the user that owns the file
 	 */
-	uid: number | bigint;
+	uid: T;
 	/**
 	 * the id of the group that owns the file
 	 */
-	gid: number | bigint;
+	gid: T;
 	/**
 	 * the ino
 	 */
-	ino: number | bigint;
+	ino: T;
 }
 
 /**
@@ -71,7 +71,7 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	}
 
 	protected _convert(arg: number | bigint | string | boolean): T {
-		return <T>(this._isBigint ? BigInt(arg) : Number(arg));
+		return (this._isBigint ? BigInt(arg) : Number(arg)) as T;
 	}
 
 	public blocks: T;
@@ -186,7 +186,7 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 	constructor({ atimeMs, mtimeMs, ctimeMs, birthtimeMs, uid, gid, size, mode, ino }: Partial<StatsLike> = {}) {
 		const currentTime = Date.now();
 		const resolveT = (val: number | bigint | undefined, _default: number) =>
-			<T>(typeof val == this._typename ? val : this._convert(typeof val == this._typename_inverse ? val! : _default));
+			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);
@@ -213,7 +213,7 @@ export abstract class StatsCommon<T extends number | bigint> implements Node.Sta
 		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 = <T>(this.mode | this._convert(itemType));
+			this.mode = (this.mode | this._convert(itemType)) as T;
 		}
 	}
 

package/dist/backends/Index.d.ts

@@ -1,204 +0,0 @@
-import type { Cred } from '../cred.js';
-import { NoSyncFile } from '../file.js';
-import { FileSystem } from '../filesystem.js';
-import { Stats } from '../stats.js';
-/**
- * @internal
- */
-export type ListingTree = {
-    [key: string]: ListingTree | null;
-};
-/**
- * @internal
- */
-export interface ListingQueueNode<TData> {
-    pwd: string;
-    tree: ListingTree;
-    parent: IndexDirInode<TData>;
-}
-/**
- * A simple class for storing a filesystem index. Assumes that all paths passed
- * to it are *absolute* paths.
- *
- * Can be used as a partial or a full index, although care must be taken if used
- * for the former purpose, especially when directories are concerned.
- *
- * @internal
- */
-export declare class FileIndex<TData> {
-    /**
-     * Static method for constructing indices from a JSON listing.
-     * @param listing Directory listing generated by tools
-     * @return A new FileIndex object.
-     */
-    static FromListing<T>(listing: ListingTree): FileIndex<T>;
-    protected _index: Map<string, IndexDirInode<TData>>;
-    /**
-     * Constructs a new FileIndex.
-     */
-    constructor();
-    files(): IndexFileInode<TData>[];
-    /**
-     * Adds the given absolute path to the index if it is not already in the index.
-     * Creates any needed parent directories.
-     * @param path The path to add to the index.
-     * @param inode The inode for the
-     *   path to add.
-     * @return 'True' if it was added or already exists, 'false' if there
-     *   was an issue adding it (e.g. item in path is a file, item exists but is
-     *   different).
-     * @todo If adding fails and implicitly creates directories, we do not clean up
-     *   the new empty directories.
-     */
-    add(path: string, inode: IndexInode<TData>): boolean;
-    /**
-     * Adds the given absolute path to the index if it is not already in the index.
-     * The path is added without special treatment (no joining of adjacent separators, etc).
-     * Creates any needed parent directories.
-     * @param path The path to add to the index.
-     * @param inode The inode for the path to add.
-     * @return 'True' if it was added or already exists, 'false' if there
-     *   was an issue adding it (e.g. item in path is a file, item exists but is
-     *   different).
-     * @todo If adding fails and implicitly creates directories, we do not clean up the new empty directories.
-     */
-    addFast(path: string, inode: IndexInode<TData>): boolean;
-    /**
-     * Removes the given path. Can be a file or a directory.
-     * @return The removed item,
-     *   or null if it did not exist.
-     */
-    remove(path: string): IndexInode<TData> | void;
-    /**
-     * Retrieves the directory listing of the given path.
-     * @return An array of files in the given path, or 'null' if it does not exist.
-     */
-    ls(path: string): string[] | void;
-    /**
-     * Returns the inode of the given item.
-     * @return Returns null if the item does not exist.
-     */
-    get(path: string): IndexInode<TData> | void | null;
-}
-/**
- * Generic interface for file/directory inodes.
- * Note that Stats objects are what we use for file inodes.
- */
-export declare abstract class IndexInode<TData> {
-    data?: TData | undefined;
-    constructor(data?: TData | undefined);
-    /**
-     * Whether this inode is for a file
-     */
-    abstract isFile(): this is IndexFileInode<TData>;
-    /**
-     * Whether this inode is for a directory
-     */
-    abstract isDirectory(): this is IndexDirInode<TData>;
-    abstract toStats(): Stats;
-}
-/**
- * Inode for a file. Stores an arbitrary (filesystem-specific) data payload.
- */
-export declare class IndexFileInode<TData> extends IndexInode<TData> {
-    isFile(): boolean;
-    isDirectory(): boolean;
-    toStats(): Stats;
-}
-/**
- * Inode for a directory. Currently only contains the directory listing.
- */
-export declare class IndexDirInode<TData> extends IndexInode<TData> {
-    /**
-     * @internal
-     */
-    _listing: Map<string, IndexInode<TData>>;
-    isFile(): boolean;
-    isDirectory(): boolean;
-    /**
-     * Return a Stats object for this inode.
-     * @todo Should probably remove this at some point. This isn't the responsibility of the FileIndex.
-     */
-    get stats(): Stats;
-    /**
-     * Alias of getStats()
-     * @todo Remove this at some point. This isn't the responsibility of the FileIndex.
-     */
-    toStats(): Stats;
-    /**
-     * Returns the directory listing for this directory. Paths in the directory are
-     * relative to the directory's path.
-     * @return The directory listing for this directory.
-     */
-    get listing(): string[];
-    /**
-     * Returns the inode for the indicated item, or null if it does not exist.
-     * @param path Name of item in this directory.
-     */
-    get(path: string): IndexInode<TData> | void;
-    /**
-     * Add the given item to the directory listing. Note that the given inode is
-     * not copied, and will be mutated by the DirInode if it is a DirInode.
-     * @param path Item name to add to the directory listing.
-     * @param inode The inode for the
-     *   item to add to the directory inode.
-     * @return True if it was added, false if it already existed.
-     */
-    add(path: string, inode: IndexInode<TData>): boolean;
-    /**
-     * Removes the given item from the directory listing.
-     * @param path Name of item to remove from the directory listing.
-     * @return Returns the item
-     *   removed, or null if the item did not exist.
-     */
-    remove(path: string): IndexInode<TData> | void;
-}
-declare const IndexFS_base: (abstract new (...args: any[]) => {
-    metadata(): import("../filesystem.js").FileSystemMetadata;
-    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-    renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    createFile(path: string, flag: string, mode: number, cred: Cred): Promise<import("../file.js").File>;
-    createFileSync(path: string, flag: string, mode: number, cred: Cred): import("../file.js").File;
-    unlink(path: string, cred: Cred): Promise<void>;
-    unlinkSync(path: string, cred: Cred): void;
-    rmdir(path: string, cred: Cred): Promise<void>;
-    rmdirSync(path: string, cred: Cred): void;
-    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-    mkdirSync(path: string, mode: number, cred: Cred): void;
-    link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-    ready(): Promise<void>;
-    stat(path: string, cred: Cred): Promise<Stats>;
-    statSync(path: string, cred: Cred): Stats;
-    openFile(path: string, flag: string, cred: Cred): Promise<import("../file.js").File>;
-    openFileSync(path: string, flag: string, cred: Cred): import("../file.js").File;
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    readdirSync(path: string, cred: Cred): string[];
-    exists(path: string, cred: Cred): Promise<boolean>;
-    existsSync(path: string, cred: Cred): boolean;
-}) & typeof FileSystem;
-export declare abstract class IndexFS<TData> extends IndexFS_base {
-    protected _index: FileIndex<TData>;
-    constructor(index: ListingTree);
-    stat(path: string): Promise<Stats>;
-    statSync(path: string): Stats;
-    openFile(path: string, flag: string, cred: Cred): Promise<NoSyncFile<this>>;
-    openFileSync(path: string, flag: string, cred: Cred): NoSyncFile<this>;
-    readdir(path: string): Promise<string[]>;
-    readdirSync(path: string): string[];
-    protected abstract statFileInode(inode: IndexFileInode<TData>, path: string): Promise<Stats>;
-    protected abstract statFileInodeSync(inode: IndexFileInode<TData>, path: string): Stats;
-    protected abstract openFileInode(inode: IndexFileInode<TData>, path: string, flag: string): Promise<NoSyncFile<this>>;
-    protected abstract openFileInodeSync(inode: IndexFileInode<TData>, path: string, flag: string): NoSyncFile<this>;
-}
-export declare abstract class SyncIndexFS<TData> extends IndexFS<TData> {
-    protected statFileInode(inode: IndexFileInode<TData>, path: string): Promise<Stats>;
-    protected openFileInode(inode: IndexFileInode<TData>, path: string, flag: string): Promise<NoSyncFile<this>>;
-}
-export declare abstract class AsyncIndexFS<TData> extends IndexFS<TData> {
-    protected statFileInodeSync(inode: IndexFileInode<TData>, path: string): Stats;
-    protected openFileInodeSync(inode: IndexFileInode<TData>, path: string, flag: string): NoSyncFile<this>;
-}
-export {};