@zenfs/core 0.12.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "0.12.0",
+	"version": "0.12.2",
 	"description": "A filesystem in your browser",
 	"main": "dist/index.js",
 	"types": "src/index.ts",
@@ -51,7 +51,7 @@
 		"buffer": "^6.0.3",
 		"minimatch": "^9.0.3",
 		"readable-stream": "^4.5.2",
-		"utilium": "^0.2.1"
+		"utilium": "^0.4.0"
 	},
 	"devDependencies": {
 		"@fal-works/esbuild-plugin-global-externals": "^2.1.2",

package/src/backends/backend.ts

@@ -8,7 +8,7 @@ type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undef
 /**
  * Resolves the type of Backend.options from the options interface
  */
-type OptionsConfig<T> = {
+export type OptionsConfig<T> = {
 	[K in keyof T]: {
 		/**
 		 * The basic JavaScript type(s) for this option.
@@ -66,9 +66,17 @@ export interface Backend<FS extends FileSystem = FileSystem, TOptions extends ob
 	isAvailable(): boolean | Promise<boolean>;
 }
 
-type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
+/**
+ * Gets the options type of a backend
+ * @internal
+ */
+export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
 
-type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
+/**
+ * Gets the FileSystem type for a backend
+ * @internal
+ */
+export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
 
 /**
  * @internal
@@ -81,7 +89,7 @@ export function isBackend(arg: unknown): arg is Backend {
  * Checks that the given options object is valid for the file system options.
  * @internal
  */
-export async function checkOptions<T extends Backend>(backend: T, opts: Partial<OptionsOf<T>> & Record<string, unknown>): Promise<void> {
+export async function checkOptions<T extends Backend>(backend: T, opts: Record<string, unknown>): Promise<void> {
 	if (typeof opts != 'object' || opts === null) {
 		throw new ErrnoError(Errno.EINVAL, 'Invalid options');
 	}
@@ -138,13 +146,14 @@ export async function checkOptions<T extends Backend>(backend: T, opts: Partial<
  *
  * The option object for each file system corresponds to that file system's option object passed to its `Create()` method.
  */
-export type BackendConfiguration<T extends Backend = Backend> = OptionsOf<T> & {
+export type BackendConfiguration<T extends Backend> = OptionsOf<T> & {
 	backend: T;
+	disableAsyncCache?: boolean;
 };
 
 /**
  * @internal
  */
-export function isBackendConfig(arg: unknown): arg is BackendConfiguration {
+export function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T> {
 	return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
 }

package/src/backends/index/index.ts

@@ -4,6 +4,10 @@ import { Stats, StatsLike } from '../../stats.js';
 import { encode } from '../../utils.js';
 import { basename, dirname } from '../../emulation/path.js';
 
+/**
+ * An Index in JSON form
+ * @internal
+ */
 export interface IndexData {
 	version: 1;
 	entries: Record<string, StatsLike<number>>;
@@ -13,6 +17,7 @@ export const version = 1;
 
 /**
  * An index of files
+ * @internal
  */
 export class Index extends Map<string, Stats> {
 	public constructor() {

package/src/backends/overlay.ts

@@ -201,7 +201,7 @@ export class UnlockedOverlayFS extends FileSystem {
 		}
 		// Create an OverlayFile.
 		const file = this._readable.openFileSync(path, parseFlag('r'), cred);
-		const stats = Stats.clone(file.statSync());
+		const stats = new Stats(file.statSync());
 		const data = new Uint8Array(stats.size);
 		file.readSync(data);
 		return new PreloadFile(this, path, flag, stats, data);

package/src/config.ts

@@ -1,17 +1,18 @@
-import { ErrnoError, Errno } from './error.js';
-import type { Backend, BackendConfiguration } from './backends/backend.js';
+import { type Entries } from 'utilium';
+import type { Backend, BackendConfiguration, FilesystemOf } from './backends/backend.js';
 import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
 import * as fs from './emulation/index.js';
-import { setCred, type MountObject } from './emulation/shared.js';
-import { FileSystem } from './filesystem.js';
 import type { AbsolutePath } from './emulation/path.js';
+import { setCred, type MountObject } from './emulation/shared.js';
+import { Errno, ErrnoError } from './error.js';
+import { FileSystem, type Async } from './filesystem.js';
 
 /**
  * Configuration for a specific mount point
  */
-export type MountConfiguration<FS extends FileSystem = FileSystem, TOptions extends object = object> = FS | BackendConfiguration<Backend<FS, TOptions>> | Backend<FS, TOptions>;
+export type MountConfiguration<T extends Backend> = FilesystemOf<T> | BackendConfiguration<T> | T;
 
-function isMountConfig(arg: unknown): arg is MountConfiguration {
+function isMountConfig<T extends Backend>(arg: unknown): arg is MountConfiguration<T> {
 	return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
 }
 
@@ -19,7 +20,7 @@ function isMountConfig(arg: unknown): arg is MountConfiguration {
  * Retrieve a file system with the given configuration.
  * @param config A BackendConfig object.
  */
-export async function resolveMountConfig<FS extends FileSystem, TOptions extends object = object>(config: MountConfiguration<FS, TOptions>, _depth = 0): Promise<FS> {
+export async function resolveMountConfig<T extends Backend>(config: MountConfiguration<T>, _depth = 0): Promise<FilesystemOf<T>> {
 	if (typeof config !== 'object' || config == null) {
 		throw new ErrnoError(Errno.EINVAL, 'Invalid options on mount configuration');
 	}
@@ -33,7 +34,7 @@ export async function resolveMountConfig<FS extends FileSystem, TOptions extends
 	}
 
 	if (isBackend(config)) {
-		config = { backend: config } as BackendConfiguration<Backend<FS, TOptions>>;
+		config = { backend: config } as BackendConfiguration<T>;
 	}
 
 	for (const [key, value] of Object.entries(config)) {
@@ -49,7 +50,7 @@ export async function resolveMountConfig<FS extends FileSystem, TOptions extends
 			throw new ErrnoError(Errno.EINVAL, 'Invalid configuration, too deep and possibly infinite');
 		}
 
-		(<Record<string, FileSystem>>config)[key] = await resolveMountConfig(value, ++_depth);
+		(config as Record<string, FileSystem>)[key] = await resolveMountConfig(value, ++_depth);
 	}
 
 	const { backend } = config;
@@ -58,40 +59,80 @@ export async function resolveMountConfig<FS extends FileSystem, TOptions extends
 		throw new ErrnoError(Errno.EPERM, 'Backend not available: ' + backend);
 	}
 	checkOptions(backend, config);
-	const mount = await backend.create(config);
+	const mount = (await backend.create(config)) as FilesystemOf<T>;
+	if ('_disableSync' in mount) {
+		type AsyncFS = InstanceType<ReturnType<typeof Async<new () => FilesystemOf<T>>>>;
+		(mount as AsyncFS)._disableSync = config.disableAsyncCache || false;
+	}
 	await mount.ready();
 	return mount;
 }
 
+type ConfigMounts = { [K in AbsolutePath]: Backend };
+
 /**
  * Configuration
  */
-export interface Configuration {
-	mounts: Record<AbsolutePath, MountConfiguration>;
-	uid?: number;
-	gid?: number;
+export interface Configuration<T extends ConfigMounts> {
+	/**
+	 * An object mapping mount points to mount configuration
+	 */
+	mounts: { [K in keyof T & AbsolutePath]: MountConfiguration<T[K]> };
+	/**
+	 * The uid to use
+	 */
+	uid: number;
+	/**
+	 * The gid to use
+	 */
+	gid: number;
+	/**
+	 * If set, disables the sync cache and sync operations on async file systems.
+	 */
+	disableAsyncCache: boolean;
 }
 
 /**
- * Creates filesystems with the given configuration, and initializes ZenFS with it.
- * @see Configuration for more info on the configuration object.
+ * Configures ZenFS with single mount point /
+ */
+export async function configure<T extends Backend>(config: MountConfiguration<T>): Promise<void>;
+
+/**
+ * Configures ZenFS with the given configuration
+ * @see Configuration
+ */
+export async function configure<T extends ConfigMounts>(config: Partial<Configuration<T>>): Promise<void>;
+
+/**
+ * Configures ZenFS with the given configuration
+ * @see Configuration
  */
-export async function configure<T extends MountConfiguration | Configuration>(config: T | Configuration): Promise<void> {
+export async function configure(config: MountConfiguration<Backend> | Partial<Configuration<ConfigMounts>>): Promise<void> {
 	const uid = 'uid' in config ? config.uid || 0 : 0;
 	const gid = 'gid' in config ? config.gid || 0 : 0;
 
 	if (isMountConfig(config)) {
 		// single FS
-		config = { mounts: { '/': config } };
+		config = { mounts: { '/': config } } as Partial<Configuration<ConfigMounts>>;
+	}
+
+	setCred({ uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
+
+	if (!config.mounts) {
+		return;
 	}
 
-	for (const [point, value] of Object.entries(config.mounts) as [AbsolutePath, MountConfiguration][]) {
+	for (const [point, mountConfig] of Object.entries(config.mounts) as Entries<typeof config.mounts>) {
 		if (!point.startsWith('/')) {
 			throw new ErrnoError(Errno.EINVAL, 'Mount points must have absolute paths');
 		}
-		config.mounts[point] = await resolveMountConfig(value);
+
+		if (isBackendConfig(mountConfig)) {
+			mountConfig.disableAsyncCache ??= config.disableAsyncCache || false;
+		}
+
+		config.mounts[point] = await resolveMountConfig(mountConfig);
 	}
 
 	fs.mountObject(config.mounts as MountObject);
-	setCred({ uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
 }

package/src/emulation/async.ts

@@ -1,7 +1,8 @@
+import { Buffer } from 'buffer';
 import type * as fs from 'node:fs';
 import { ErrnoError, Errno } from '../error.js';
 import type { FileContents } from '../filesystem.js';
-import { BigIntStats, type BigIntStatsFs, type Stats, type StatsFs } from '../stats.js';
+import { BigIntStats, type Stats } from '../stats.js';
 import { nop, normalizeMode, type Callback } from '../utils.js';
 import { R_OK } from './constants.js';
 import { Dirent, type Dir } from './dir.js';
@@ -52,7 +53,7 @@ export function stat(path: fs.PathLike, options?: fs.StatOptions | Callback<[Sta
 	callback = typeof options == 'function' ? options : callback;
 	promises
 		.stat(path, typeof options != 'function' ? options : {})
-		.then(stats => (<Callback<[Stats] | [BigIntStats]>>callback)(undefined, <any>stats))
+		.then(stats => (callback as Callback<[Stats] | [BigIntStats]>)(undefined, stats as any))
 		.catch(callback);
 }
 stat satisfies Omit<typeof fs.stat, '__promisify__'>;
@@ -71,8 +72,8 @@ export function lstat(path: fs.PathLike, options: fs.StatOptions, callback: Call
 export function lstat(path: fs.PathLike, options?: fs.StatOptions | Callback<[Stats]>, callback: Callback<[Stats]> | Callback<[BigIntStats]> = nop): void {
 	callback = typeof options == 'function' ? options : callback;
 	promises
-		.lstat(path, typeof options != 'function' ? options : <object>{})
-		.then(stats => (<Callback<[Stats] | [BigIntStats]>>callback)(undefined, stats))
+		.lstat(path, typeof options != 'function' ? options : ({} as object))
+		.then(stats => (callback as Callback<[Stats] | [BigIntStats]>)(undefined, stats))
 		.catch(callback);
 }
 lstat satisfies Omit<typeof fs.lstat, '__promisify__'>;
@@ -161,7 +162,7 @@ export function readFile(filename: fs.PathLike, options?: fs.WriteFileOptions |
 
 	promises
 		.readFile(filename, typeof options === 'function' ? null : options)
-		.then(data => (<Callback<[string | Uint8Array]>>cb)(undefined, data))
+		.then(data => (cb as Callback<[string | Uint8Array]>)(undefined, data))
 		.catch(cb);
 }
 readFile satisfies Omit<typeof fs.readFile, '__promisify__'>;
@@ -231,7 +232,7 @@ export function fstat(fd: number, options?: fs.StatOptions | Callback<[Stats]>,
 
 	fd2file(fd)
 		.stat()
-		.then(stats => (<Callback<[Stats | BigIntStats]>>cb)(undefined, typeof options == 'object' && options?.bigint ? new BigIntStats(stats) : stats))
+		.then(stats => (cb as Callback<[Stats | BigIntStats]>)(undefined, typeof options == 'object' && options?.bigint ? new BigIntStats(stats) : stats))
 		.catch(cb);
 }
 fstat satisfies Omit<typeof fs.fstat, '__promisify__'>;
@@ -329,20 +330,20 @@ export function write(fd: number, data: FileContents, cbPosOff?: any, cbLenEnc?:
 			case 'number':
 				// (fd, string, position, encoding?, cb?)
 				position = cbPosOff;
-				encoding = <BufferEncoding>(typeof cbLenEnc === 'string' ? cbLenEnc : 'utf8');
+				encoding = typeof cbLenEnc === 'string' ? (cbLenEnc as BufferEncoding) : 'utf8';
 				cb = typeof cbPos === 'function' ? cbPos : cb;
 				break;
 			default:
 				// ...try to find the callback and get out of here!
 				cb = typeof cbLenEnc === 'function' ? cbLenEnc : typeof cbPos === 'function' ? cbPos : cb;
-				(<Callback<[number, Uint8Array | string]>>cb)(new ErrnoError(Errno.EINVAL, 'Invalid arguments.'));
+				(cb as Callback<[number, Uint8Array | string]>)(new ErrnoError(Errno.EINVAL, 'Invalid arguments.'));
 				return;
 		}
 		buffer = Buffer.from(data);
 		offset = 0;
 		length = buffer.length;
 
-		const _cb = <Callback<[number, string]>>cb;
+		const _cb = cb as Callback<[number, string]>;
 
 		handle
 			.write(buffer, offset, length, position)
@@ -354,7 +355,7 @@ export function write(fd: number, data: FileContents, cbPosOff?: any, cbLenEnc?:
 		offset = cbPosOff;
 		length = cbLenEnc;
 		position = typeof cbPos === 'number' ? cbPos : null;
-		const _cb = <Callback<[number, Uint8Array]>>(typeof cbPos === 'function' ? cbPos : cb);
+		const _cb = typeof cbPos === 'function' ? cbPos : (cb as Callback<[number, Uint8Array]>);
 		handle
 			.write(buffer, offset, length, position)
 			.then(({ bytesWritten }) => _cb(undefined, bytesWritten, buffer))
@@ -526,7 +527,7 @@ export function readlink(
 	callback = typeof options == 'function' ? options : callback;
 	promises
 		.readlink(path)
-		.then(result => (<Callback<[string | Uint8Array]>>callback)(undefined, result))
+		.then(result => (callback as Callback<[string | Uint8Array]>)(undefined, result))
 		.catch(callback);
 }
 readlink satisfies Omit<typeof fs.readlink, '__promisify__'>;
@@ -816,8 +817,8 @@ export function mkdtemp(prefix: string, options: fs.BufferEncodingOption, callba
 export function mkdtemp(prefix: string, options: fs.EncodingOption | fs.BufferEncodingOption | Callback<[string]>, callback: Callback<[Buffer]> | Callback<[string]> = nop): void {
 	callback = typeof options === 'function' ? options : callback;
 	promises
-		.mkdtemp(prefix, typeof options != 'function' ? <fs.EncodingOption>options : null)
-		.then(result => (<Callback<[string | Buffer]>>callback)(undefined, result))
+		.mkdtemp(prefix, typeof options != 'function' ? (options as fs.EncodingOption) : null)
+		.then(result => (callback as Callback<[string | Buffer]>)(undefined, result))
 		.catch(callback);
 }
 mkdtemp satisfies Omit<typeof fs.mkdtemp, '__promisify__'>;
@@ -881,14 +882,14 @@ export function cp(source: fs.PathLike, destination: fs.PathLike, opts: fs.CopyO
 }
 cp satisfies Omit<typeof fs.cp, '__promisify__'>;
 
-export function statfs(path: fs.PathLike, callback: Callback<[StatsFs]>): void;
-export function statfs(path: fs.PathLike, options: fs.StatFsOptions & { bigint?: false }, callback: Callback<[StatsFs]>): void;
-export function statfs(path: fs.PathLike, options: fs.StatFsOptions & { bigint: true }, callback: Callback<[BigIntStatsFs]>): void;
-export function statfs(path: fs.PathLike, options?: fs.StatFsOptions | Callback<[StatsFs]>, callback: Callback<[StatsFs]> | Callback<[BigIntStatsFs]> = nop): void {
+export function statfs(path: fs.PathLike, callback: Callback<[fs.StatsFs]>): void;
+export function statfs(path: fs.PathLike, options: fs.StatFsOptions & { bigint?: false }, callback: Callback<[fs.StatsFs]>): void;
+export function statfs(path: fs.PathLike, options: fs.StatFsOptions & { bigint: true }, callback: Callback<[fs.BigIntStatsFs]>): void;
+export function statfs(path: fs.PathLike, options?: fs.StatFsOptions | Callback<[fs.StatsFs]>, callback: Callback<[fs.StatsFs]> | Callback<[fs.BigIntStatsFs]> = nop): void {
 	callback = typeof options === 'function' ? options : callback;
 	promises
 		.statfs(path, typeof options === 'function' ? undefined : options)
-		.then(result => (<Callback<[StatsFs | BigIntStatsFs]>>callback)(undefined, result))
+		.then(result => (callback as Callback<[fs.StatsFs | fs.BigIntStatsFs]>)(undefined, result))
 		.catch(callback);
 }
 statfs satisfies Omit<typeof fs.statfs, '__promisify__'>;

package/src/emulation/index.ts

@@ -5,4 +5,4 @@ export * as constants from './constants.js';
 export * from './streams.js';
 export * from './dir.js';
 export { mountObject, mounts, mount, umount } from './shared.js';
-export { Stats, BigIntStats, StatsFs } from '../stats.js';
+export { Stats, StatsFs, BigIntStatsFs } from '../stats.js';

package/src/emulation/path.ts

@@ -28,6 +28,9 @@ https://raw.githubusercontent.com/nodejs/node/3907bd1/lib/path.js
 
 import type { ParsedPath } from 'node:path';
 
+/**
+ * An absolute path
+ */
 export type AbsolutePath = `/${string}`;
 
 export let cwd = '/';
@@ -156,7 +159,7 @@ export function normalize(path: string): string {
 	return isAbsolute ? `/${path}` : path;
 }
 
-export function isAbsolute(path: string): boolean {
+export function isAbsolute(path: string): path is AbsolutePath {
 	return path.startsWith('/');
 }
 

package/src/emulation/promises.ts

@@ -6,15 +6,15 @@ import type { Stream } from 'node:stream';
 import type { ReadableStream as TReadableStream } from 'node:stream/web';
 import type { Interface as ReadlineInterface } from 'readline';
 import type { ReadableStreamController } from 'stream/web';
-import { ErrnoError, Errno } from '../error.js';
+import { Errno, ErrnoError } from '../error.js';
 import { ActionType, File, isAppendable, isReadable, isWriteable, parseFlag, pathExistsAction, pathNotExistsAction } from '../file.js';
 import type { FileContents } from '../filesystem.js';
-import { BigIntStats, FileType, type BigIntStatsFs, type Stats, type StatsFs } from '../stats.js';
+import { BigIntStats, FileType, type Stats } from '../stats.js';
 import { normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
 import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { cred, fd2file, fdMap, file2fd, fixError, mounts, resolveMount } from './shared.js';
+import { _statfs, cred, fd2file, fdMap, file2fd, fixError, mounts, resolveMount } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
 export * as constants from './constants.js';
 
@@ -233,7 +233,7 @@ export class FileHandle implements promises.FileHandle {
 		if (typeof data === 'string') {
 			// Signature 1: (fd, string, [position?, [encoding?]])
 			position = typeof posOrOff === 'number' ? posOrOff : null;
-			const encoding = <BufferEncoding>(typeof lenOrEnc === 'string' ? lenOrEnc : 'utf8');
+			const encoding = typeof lenOrEnc === 'string' ? lenOrEnc : ('utf8' as BufferEncoding);
 			offset = 0;
 			buffer = Buffer.from(data, encoding);
 			length = buffer.length;
@@ -491,28 +491,7 @@ async function _open(path: fs.PathLike, _flag: fs.OpenMode, _mode: fs.Mode = 0o6
 	path = resolveSymlinks && (await exists(path)) ? await realpath(path) : path;
 	const { fs, path: resolved } = resolveMount(path);
 
-	try {
-		switch (pathExistsAction(flag)) {
-			case ActionType.THROW:
-				throw ErrnoError.With('EEXIST', path, '_open');
-			case ActionType.TRUNCATE:
-				/* 
-					In a previous implementation, we deleted the file and
-					re-created it. However, this created a race condition if another
-					asynchronous request was trying to read the file, as the file
-					would not exist for a small period of time.
-				*/
-				const file: File = await fs.openFile(resolved, flag, cred);
-				await file.truncate(0);
-				await file.sync();
-				return new FileHandle(file);
-			case ActionType.NOP:
-				// Must await so thrown errors are caught by the catch below
-				return new FileHandle(await fs.openFile(resolved, flag, cred));
-			default:
-				throw new ErrnoError(Errno.EINVAL, 'Invalid file flag');
-		}
-	} catch (e) {
+	if (!(await fs.exists(path, cred))) {
 		switch (pathNotExistsAction(flag)) {
 			case ActionType.CREATE:
 				// Ensure parent exists.
@@ -527,6 +506,27 @@ async function _open(path: fs.PathLike, _flag: fs.OpenMode, _mode: fs.Mode = 0o6
 				throw new ErrnoError(Errno.EINVAL, 'Invalid file flag');
 		}
 	}
+
+	switch (pathExistsAction(flag)) {
+		case ActionType.THROW:
+			throw ErrnoError.With('EEXIST', path, '_open');
+		case ActionType.TRUNCATE:
+			/* 
+					In a previous implementation, we deleted the file and
+					re-created it. However, this created a race condition if another
+					asynchronous request was trying to read the file, as the file
+					would not exist for a small period of time.
+				*/
+			const file: File = await fs.openFile(resolved, flag, cred);
+			await file.truncate(0);
+			await file.sync();
+			return new FileHandle(file);
+		case ActionType.NOP:
+			// Must await so thrown errors are caught by the catch below
+			return new FileHandle(await fs.openFile(resolved, flag, cred));
+		default:
+			throw new ErrnoError(Errno.EINVAL, 'Invalid file flag');
+	}
 }
 
 /**
@@ -1061,9 +1061,11 @@ cp satisfies typeof promises.cp;
  * @since v18.15.0
  * @return Fulfills with an {fs.StatFs} for the file system.
  */
-export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions & { bigint?: false }): Promise<StatsFs>;
-export async function statfs(path: fs.PathLike, opts: fs.StatFsOptions & { bigint: true }): Promise<BigIntStatsFs>;
-export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions): Promise<StatsFs | BigIntStatsFs>;
-export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions): Promise<StatsFs | BigIntStatsFs> {
-	throw ErrnoError.With('ENOSYS', path.toString(), 'statfs');
+export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions & { bigint?: false }): Promise<fs.StatsFs>;
+export async function statfs(path: fs.PathLike, opts: fs.StatFsOptions & { bigint: true }): Promise<fs.BigIntStatsFs>;
+export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions): Promise<fs.StatsFs | fs.BigIntStatsFs>;
+export async function statfs(path: fs.PathLike, opts?: fs.StatFsOptions): Promise<fs.StatsFs | fs.BigIntStatsFs> {
+	path = normalizePath(path);
+	const { fs } = resolveMount(path);
+	return _statfs(fs, opts?.bigint);
 }

package/src/emulation/shared.ts

@@ -1,10 +1,13 @@
 // Utilities and shared data
 
-import { ErrnoError, Errno } from '../error.js';
+import type { BigIntStatsFs, StatsFs } from 'node:fs';
 import { InMemory } from '../backends/memory.js';
 import { Cred, rootCred } from '../cred.js';
+import { Errno, ErrnoError } from '../error.js';
 import type { File } from '../file.js';
 import { FileSystem } from '../filesystem.js';
+import { size_max } from '../inode.js';
+import { ZenFsType } from '../stats.js';
 import { normalizePath } from '../utils.js';
 import { resolve, type AbsolutePath } from './path.js';
 
@@ -117,3 +120,21 @@ export function mountObject(mounts: MountObject): void {
 		mount(point, fs);
 	}
 }
+
+/**
+ * @hidden
+ */
+export function _statfs<const T extends boolean>(fs: FileSystem, bigint?: T): T extends true ? BigIntStatsFs : StatsFs {
+	const md = fs.metadata();
+	const bs = md.blockSize || 4096;
+
+	return {
+		type: (bigint ? BigInt : Number)(md.type || ZenFsType),
+		bsize: (bigint ? BigInt : Number)(bs),
+		ffree: (bigint ? BigInt : Number)(md.freeNodes || size_max),
+		files: (bigint ? BigInt : Number)(md.totalNodes || size_max),
+		bavail: (bigint ? BigInt : Number)(md.freeSpace / bs),
+		bfree: (bigint ? BigInt : Number)(md.freeSpace / bs),
+		blocks: (bigint ? BigInt : Number)(md.totalSpace / bs),
+	} as T extends true ? BigIntStatsFs : StatsFs;
+}