@zenfs/core 1.1.6 → 1.2.1

package/dist/emulation/sync.d.ts

@@ -3,6 +3,7 @@ import type * as fs from 'node:fs';
 import type { FileContents } from '../filesystem.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { Dir, Dirent } from './dir.js';
+import { type InternalOptions, type ReaddirOptions } from './shared.js';
 export declare function renameSync(oldPath: fs.PathLike, newPath: fs.PathLike): void;
 /**
  * Test whether or not `path` exists by checking with the file system.
@@ -110,29 +111,19 @@ export declare function mkdirSync(path: fs.PathLike, options?: fs.Mode | (fs.Mak
     recursive?: false;
 }) | null): void;
 export declare function mkdirSync(path: fs.PathLike, options?: fs.Mode | fs.MakeDirectoryOptions | null): string | undefined;
-export declare function readdirSync(path: fs.PathLike, options?: {
-    recursive?: boolean;
-    encoding?: BufferEncoding | null;
+export declare function readdirSync(path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
     withFileTypes?: false;
-} | BufferEncoding | null): string[];
-export declare function readdirSync(path: fs.PathLike, options: {
-    recursive?: boolean;
-    encoding: 'buffer';
+}) | BufferEncoding | null): string[];
+export declare function readdirSync(path: fs.PathLike, options: fs.BufferEncodingOption & ReaddirOptions & {
     withFileTypes?: false;
-} | 'buffer'): Buffer[];
-export declare function readdirSync(path: fs.PathLike, options: {
-    recursive?: boolean;
-    withFileTypes: true;
-}): Dirent[];
-export declare function readdirSync(path: fs.PathLike, options?: (fs.ObjectEncodingOptions & {
+}): Buffer[];
+export declare function readdirSync(path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
     withFileTypes?: false;
-    recursive?: boolean;
 }) | BufferEncoding | null): string[] | Buffer[];
-export declare function readdirSync(path: fs.PathLike, options?: {
-    withFileTypes?: boolean;
-    recursive?: boolean;
-    encoding?: BufferEncoding | 'buffer' | null;
-} | BufferEncoding | 'buffer' | null): string[] | Dirent[] | Buffer[];
+export declare function readdirSync(path: fs.PathLike, options: fs.ObjectEncodingOptions & ReaddirOptions & {
+    withFileTypes: true;
+}): Dirent[];
+export declare function readdirSync(path: fs.PathLike, options?: (ReaddirOptions & (fs.ObjectEncodingOptions | fs.BufferEncodingOption)) | BufferEncoding | null): string[] | Dirent[] | Buffer[];
 export declare function linkSync(targetPath: fs.PathLike, linkPath: fs.PathLike): void;
 /**
  * Synchronous `symlink`.
@@ -163,7 +154,7 @@ export declare function accessSync(path: fs.PathLike, mode?: number): void;
  * Synchronous `rm`. Removes files or directories (recursively).
  * @param path The path to the file or directory to remove.
  */
-export declare function rmSync(path: fs.PathLike, options?: fs.RmOptions): void;
+export declare function rmSync(path: fs.PathLike, options?: fs.RmOptions & InternalOptions): void;
 /**
  * Synchronous `mkdtemp`. Creates a unique temporary directory.
  * @param prefix The directory prefix.

package/dist/emulation/sync.js

@@ -54,13 +54,15 @@ import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
 import { _statfs, fd2file, fdMap, file2fd, fixError, mounts, resolveMount } from './shared.js';
+import { config } from './config.js';
 import { emitChange } from './watchers.js';
+import * as cache from './cache.js';
 export function renameSync(oldPath, newPath) {
     oldPath = normalizePath(oldPath);
     newPath = normalizePath(newPath);
     const oldMount = resolveMount(oldPath);
     const newMount = resolveMount(newPath);
-    if (!statSync(dirname(oldPath)).hasAccess(constants.W_OK)) {
+    if (config.checkAccess && !statSync(dirname(oldPath)).hasAccess(constants.W_OK)) {
         throw ErrnoError.With('EACCES', oldPath, 'rename');
     }
     try {
@@ -100,7 +102,7 @@ export function statSync(path, options) {
     const { fs, path: resolved } = resolveMount(realpathSync(path));
     try {
         const stats = fs.statSync(resolved);
-        if (!stats.hasAccess(constants.R_OK)) {
+        if (config.checkAccess && !stats.hasAccess(constants.R_OK)) {
             throw ErrnoError.With('EACCES', resolved, 'stat');
         }
         return options?.bigint ? new BigIntStats(stats) : stats;
@@ -145,7 +147,7 @@ export function unlinkSync(path) {
     path = normalizePath(path);
     const { fs, path: resolved } = resolveMount(path);
     try {
-        if (!fs.statSync(resolved).hasAccess(constants.W_OK)) {
+        if (config.checkAccess && !(cache.getStats(path) || fs.statSync(resolved)).hasAccess(constants.W_OK)) {
             throw ErrnoError.With('EACCES', resolved, 'unlink');
         }
         fs.unlinkSync(resolved);
@@ -174,7 +176,7 @@ function _openSync(path, _flag, _mode, resolveSymlinks = true) {
         }
         // Create the file
         const parentStats = fs.statSync(dirname(resolved));
-        if (!parentStats.hasAccess(constants.W_OK)) {
+        if (config.checkAccess && !parentStats.hasAccess(constants.W_OK)) {
             throw ErrnoError.With('EACCES', dirname(path), '_open');
         }
         if (!parentStats.isDirectory()) {
@@ -182,7 +184,7 @@ function _openSync(path, _flag, _mode, resolveSymlinks = true) {
         }
         return fs.createFileSync(resolved, flag, mode);
     }
-    if (!stats.hasAccess(mode) || !stats.hasAccess(flagToMode(flag))) {
+    if (config.checkAccess && (!stats.hasAccess(mode) || !stats.hasAccess(flagToMode(flag)))) {
         throw ErrnoError.With('EACCES', path, '_open');
     }
     if (isExclusive(flag)) {
@@ -392,7 +394,11 @@ export function rmdirSync(path) {
     path = normalizePath(path);
     const { fs, path: resolved } = resolveMount(realpathSync(path));
     try {
-        if (!fs.statSync(resolved).hasAccess(constants.W_OK)) {
+        const stats = cache.getStats(path) || fs.statSync(resolved);
+        if (!stats.isDirectory()) {
+            throw ErrnoError.With('ENOTDIR', resolved, 'rmdir');
+        }
+        if (config.checkAccess && !stats.hasAccess(constants.W_OK)) {
             throw ErrnoError.With('EACCES', resolved, 'rmdir');
         }
         fs.rmdirSync(resolved);
@@ -406,12 +412,12 @@ rmdirSync;
 export function mkdirSync(path, options) {
     options = typeof options === 'object' ? options : { mode: options };
     const mode = normalizeMode(options?.mode, 0o777);
-    path = realpathSync(normalizePath(path));
+    path = realpathSync(path);
     const { fs, path: resolved } = resolveMount(path);
     const errorPaths = { [resolved]: path };
     try {
         if (!options?.recursive) {
-            if (!fs.statSync(dirname(resolved)).hasAccess(constants.W_OK)) {
+            if (config.checkAccess && !fs.statSync(dirname(resolved)).hasAccess(constants.W_OK)) {
                 throw ErrnoError.With('EACCES', dirname(resolved), 'mkdir');
             }
             return fs.mkdirSync(resolved, mode);
@@ -422,7 +428,7 @@ export function mkdirSync(path, options) {
             errorPaths[dir] = original;
         }
         for (const dir of dirs) {
-            if (!fs.statSync(dirname(dir)).hasAccess(constants.W_OK)) {
+            if (config.checkAccess && !fs.statSync(dirname(dir)).hasAccess(constants.W_OK)) {
                 throw ErrnoError.With('EACCES', dirname(dir), 'mkdir');
             }
             fs.mkdirSync(dir, mode);
@@ -441,8 +447,13 @@ export function readdirSync(path, options) {
     const { fs, path: resolved } = resolveMount(realpathSync(path));
     let entries;
     try {
-        if (!fs.statSync(resolved).hasAccess(constants.R_OK)) {
-            throw ErrnoError.With('EACCES', path, 'readdir');
+        const stats = cache.getStats(path) || fs.statSync(resolved);
+        cache.setStats(path, stats);
+        if (config.checkAccess && !stats.hasAccess(constants.R_OK)) {
+            throw ErrnoError.With('EACCES', resolved, 'readdir');
+        }
+        if (!stats.isDirectory()) {
+            throw ErrnoError.With('ENOTDIR', resolved, 'readdir');
         }
         entries = fs.readdirSync(resolved);
     }
@@ -463,11 +474,12 @@ export function readdirSync(path, options) {
     // Iterate over entries and handle recursive case if needed
     const values = [];
     for (const entry of entries) {
-        const entryStat = fs.statSync(join(resolved, entry));
+        const entryStat = cache.getStats(join(path, entry)) || fs.statSync(join(resolved, entry));
+        cache.setStats(join(path, entry), entryStat);
         if (options?.withFileTypes) {
             values.push(new Dirent(entry, entryStat));
         }
-        else if (options?.encoding === 'buffer') {
+        else if (options?.encoding == 'buffer') {
             values.push(Buffer.from(entry));
         }
         else {
@@ -475,7 +487,7 @@ export function readdirSync(path, options) {
         }
         if (!entryStat.isDirectory() || !options?.recursive)
             continue;
-        for (const subEntry of readdirSync(join(path, entry), options)) {
+        for (const subEntry of readdirSync(join(path, entry), { ...options, _isIndirect: true })) {
             if (subEntry instanceof Dirent) {
                 subEntry.path = join(entry, subEntry.path);
                 values.push(subEntry);
@@ -488,17 +500,20 @@ export function readdirSync(path, options) {
             }
         }
     }
+    if (!options?._isIndirect) {
+        cache.clearStats();
+    }
     return values;
 }
 readdirSync;
 // SYMLINK METHODS
 export function linkSync(targetPath, linkPath) {
     targetPath = normalizePath(targetPath);
-    if (!statSync(dirname(targetPath)).hasAccess(constants.R_OK)) {
+    if (config.checkAccess && !statSync(dirname(targetPath)).hasAccess(constants.R_OK)) {
         throw ErrnoError.With('EACCES', dirname(targetPath), 'link');
     }
     linkPath = normalizePath(linkPath);
-    if (!statSync(dirname(linkPath)).hasAccess(constants.W_OK)) {
+    if (config.checkAccess && !statSync(dirname(linkPath)).hasAccess(constants.W_OK)) {
         throw ErrnoError.With('EACCES', dirname(linkPath), 'link');
     }
     const { fs, path } = resolveMount(targetPath);
@@ -507,7 +522,7 @@ export function linkSync(targetPath, linkPath) {
         throw ErrnoError.With('EXDEV', linkPath, 'link');
     }
     try {
-        if (!fs.statSync(path).hasAccess(constants.W_OK)) {
+        if (config.checkAccess && !fs.statSync(path).hasAccess(constants.W_OK)) {
             throw ErrnoError.With('EACCES', path, 'link');
         }
         return fs.linkSync(path, linkPath);
@@ -608,6 +623,8 @@ export function realpathSync(path, options) {
 }
 realpathSync;
 export function accessSync(path, mode = 0o600) {
+    if (!config.checkAccess)
+        return;
     if (!statSync(path).hasAccess(mode)) {
         throw new ErrnoError(Errno.EACCES);
     }
@@ -621,7 +638,7 @@ export function rmSync(path, options) {
     path = normalizePath(path);
     let stats;
     try {
-        stats = statSync(path);
+        stats = cache.getStats(path) || statSync(path);
     }
     catch (error) {
         if (error.code != 'ENOENT' || !options?.force)
@@ -630,26 +647,31 @@ export function rmSync(path, options) {
     if (!stats) {
         return;
     }
+    cache.setStats(path, stats);
     switch (stats.mode & constants.S_IFMT) {
         case constants.S_IFDIR:
             if (options?.recursive) {
-                for (const entry of readdirSync(path)) {
-                    rmSync(join(path, entry), options);
+                for (const entry of readdirSync(path, { _isIndirect: true })) {
+                    rmSync(join(path, entry), { ...options, _isIndirect: true });
                 }
             }
             rmdirSync(path);
-            return;
+            break;
         case constants.S_IFREG:
         case constants.S_IFLNK:
             unlinkSync(path);
-            return;
+            break;
         case constants.S_IFBLK:
         case constants.S_IFCHR:
         case constants.S_IFIFO:
         case constants.S_IFSOCK:
         default:
+            cache.clearStats();
             throw new ErrnoError(Errno.EPERM, 'File type not supported', path, 'rm');
     }
+    if (!options?._isIndirect) {
+        cache.clearStats();
+    }
 }
 rmSync;
 export function mkdtempSync(prefix, options) {

package/dist/file.d.ts

@@ -1,7 +1,7 @@
 import type { FileReadResult } from 'node:fs/promises';
 import type { FileSystem } from './filesystem.js';
-import { Stats, type FileType } from './stats.js';
 import './polyfills.js';
+import { Stats, type FileType } from './stats.js';
 /**
     Typescript does not include a type declaration for resizable array buffers.
     It has been standardized into ECMAScript though

package/dist/file.js

@@ -1,7 +1,8 @@
 import { O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY, S_IFMT, size_max } from './emulation/constants.js';
+import { config } from './emulation/config.js';
 import { Errno, ErrnoError } from './error.js';
-import { Stats } from './stats.js';
 import './polyfills.js';
+import { Stats } from './stats.js';
 const validFlags = ['r', 'r+', 'rs', 'rs+', 'w', 'wx', 'w+', 'wx+', 'a', 'ax', 'a+', 'ax+'];
 export function parseFlag(flag) {
     if (typeof flag === 'number') {
@@ -383,7 +384,8 @@ export class PreloadFile extends File {
      */
     async read(buffer, offset, length, position) {
         const bytesRead = this._read(buffer, offset, length, position);
-        await this.sync();
+        if (config.syncOnRead)
+            await this.sync();
         return { bytesRead, buffer };
     }
     /**
@@ -397,7 +399,8 @@ export class PreloadFile extends File {
      */
     readSync(buffer, offset, length, position) {
         const bytesRead = this._read(buffer, offset, length, position);
-        this.statSync();
+        if (config.syncOnRead)
+            this.syncSync();
         return bytesRead;
     }
     async chmod(mode) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.1.6",
+	"version": "1.2.1",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -18,6 +18,7 @@
 		"zenfs-test": "scripts/test.js"
 	},
 	"files": [
+		"src",
 		"dist",
 		"tests",
 		"license.md",
@@ -48,7 +49,8 @@
 		"./mixins": "./dist/mixins/index.js",
 		"./path": "./dist/emulation/path.js",
 		"./eslint": "./eslint.shared.js",
-		"./tests/*": "./tests/*"
+		"./tests/*": "./tests/*",
+		"./src/*": "./src/*"
 	},
 	"scripts": {
 		"format": "prettier --write .",

package/readme.md

@@ -32,7 +32,7 @@ npm install @zenfs/core
 ```js
 import { fs } from '@zenfs/core'; // You can also use the default export
 
-fs.writeFileSync('/test.txt', 'You can do this in anywhere (including browsers)!');
+fs.writeFileSync('/test.txt', 'You can do this anywhere, including browsers!');
 
 const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);

package/scripts/test.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -8,6 +9,8 @@ const { values: options, positionals } = parseArgs({
 	options: {
 		help: { short: 'h', type: 'boolean', default: false },
 		verbose: { type: 'boolean', default: false },
+		test: { type: 'string' },
+		forceExit: { short: 'f', type: 'boolean', default: false },
 	},
 	allowPositionals: true,
 });
@@ -20,12 +23,27 @@ paths: The setup files to run tests on
 options:
 	--help, -h		Outputs this help message
 	--verbose		Output verbose messages
+	--test			Which test to run
+	--forceExit		Whether to use --test-force-exit
 	`);
 	process.exit();
 }
 
+if (options.verbose) console.debug('Forcing tests to exit (--test-force-exit)');
+
+if (!existsSync(join(import.meta.dirname, '../dist'))) {
+	console.log('ERROR: Missing build. If you are using an installed package, please submit a bug report.');
+	process.exit(1);
+}
+
+const testsGlob = join(import.meta.dirname, `../tests/fs/${options.test || '*'}.test.ts`);
+
 for (const setupFile of positionals) {
 	if (options.verbose) console.debug('Running tests for:', setupFile);
 	process.env.SETUP = setupFile;
-	execSync('tsx --test --experimental-test-coverage ' + join(import.meta.dirname, '../tests/fs/*.test.ts'), { stdio: 'inherit' });
+	if (!existsSync(setupFile)) {
+		console.log('ERROR: Skipping non-existent file:', setupFile);
+		continue;
+	}
+	execSync(['tsx --test --experimental-test-coverage', options.forceExit ? '--test-force-exit' : '', testsGlob, process.env.CMD].join(' '), { stdio: 'inherit' });
 }

package/src/backends/backend.ts

@@ -0,0 +1,160 @@
+import type { Entries, RequiredKeys } from 'utilium';
+import { ErrnoError, Errno } from '../error.js';
+import type { FileSystem } from '../filesystem.js';
+import { levenshtein } from '../utils.js';
+
+type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
+
+/**
+ * Resolves the type of Backend.options from the options interface
+ */
+export type OptionsConfig<T> = {
+	[K in keyof T]: {
+		/**
+		 * The basic JavaScript type(s) for this option.
+		 */
+		type: OptionType | readonly OptionType[];
+
+		/**
+		 * Description of the option. Used in error messages and documentation.
+		 */
+		description: string;
+
+		/**
+		 * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
+		 */
+		required: K extends RequiredKeys<T> ? true : false;
+
+		/**
+		 * A custom validation function to check if the option is valid.
+		 * When async, resolves if valid and rejects if not.
+		 * When sync, it will throw an error if not valid.
+		 */
+		validator?(opt: T[K]): void | Promise<void>;
+	};
+};
+
+/**
+ * Configuration options shared by backends and `Configuration`
+ */
+export interface SharedConfig {
+	/**
+	 * If set, disables the sync cache and sync operations on async file systems.
+	 */
+	disableAsyncCache?: boolean;
+}
+
+/**
+ * A backend
+ */
+export interface Backend<FS extends FileSystem = FileSystem, TOptions extends object = object> {
+	/**
+	 * Create a new instance of the backend
+	 */
+	create(options: TOptions & Partial<SharedConfig>): FS | Promise<FS>;
+
+	/**
+	 * A name to identify the backend.
+	 */
+	name: string;
+
+	/**
+	 * Describes all of the options available for this backend.
+	 */
+	options: OptionsConfig<TOptions>;
+
+	/**
+	 * Whether the backend is available in the current environment.
+	 * It supports checking synchronously and asynchronously
+	 *
+	 * Returns 'true' if this backend is available in the current
+	 * environment. For example, a backend using a browser API will return
+	 * 'false' if the API is unavailable
+	 *
+	 */
+	isAvailable(): boolean | Promise<boolean>;
+}
+
+/**
+ * Gets the options type of a backend
+ * @internal
+ */
+export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
+
+/**
+ * Gets the FileSystem type for a backend
+ * @internal
+ */
+export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
+
+/** @internal */
+export function isBackend(arg: unknown): arg is Backend {
+	return arg != null && typeof arg == 'object' && 'isAvailable' in arg && typeof arg.isAvailable == 'function' && 'create' in arg && typeof arg.create == 'function';
+}
+
+/**
+ * Checks that `options` object is valid for the file system options.
+ * @internal
+ */
+export async function checkOptions<T extends Backend>(backend: T, options: Record<string, unknown>): Promise<void> {
+	if (typeof options != 'object' || options === null) {
+		throw new ErrnoError(Errno.EINVAL, 'Invalid options');
+	}
+
+	// Check for required options.
+	for (const [optName, opt] of Object.entries(backend.options) as Entries<OptionsConfig<Record<string, any>>>) {
+		const providedValue = options?.[optName];
+
+		if (providedValue === undefined || providedValue === null) {
+			if (!opt.required) {
+				continue;
+			}
+			/* Required option not provided.
+			if any incorrect options provided, which ones are close to the provided one?
+			(edit distance 5 === close)*/
+			const incorrectOptions = Object.keys(options)
+				.filter(o => !(o in backend.options))
+				.map((a: string) => {
+					return { str: a, distance: levenshtein(optName, a) };
+				})
+				.filter(o => o.distance < 5)
+				.sort((a, b) => a.distance - b.distance);
+
+			throw new ErrnoError(
+				Errno.EINVAL,
+				`${backend.name}: Required option '${optName}' not provided.${
+					incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''
+				}`
+			);
+		}
+		// Option provided, check type.
+		const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
+		if (!typeMatches) {
+			throw new ErrnoError(
+				Errno.EINVAL,
+				`${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${
+					Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : (opt.type as string)
+				}, but received ${typeof providedValue}`
+			);
+		}
+
+		if (opt.validator) {
+			await opt.validator(providedValue);
+		}
+		// Otherwise: All good!
+	}
+}
+
+/**
+ * Specifies a file system backend type and its options.
+ *
+ * Individual options can recursively contain BackendConfiguration objects for values that require file systems.
+ *
+ * The configuration for each file system corresponds to that file system's option object passed to its `create()` method.
+ */
+export type BackendConfiguration<T extends Backend> = OptionsOf<T> & Partial<SharedConfig> & { backend: T };
+
+/** @internal */
+export function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T> {
+	return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
+}