@zenfs/core 2.4.4 → 2.5.0

package/README.md

@@ -163,6 +163,19 @@ fs.umount('/mnt/zip'); // finished using the zip
 
 ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out the [Devices and Device Drivers](https://zenfs.dev/core/documents/Devices_and_Device_Drivers) documentation for more information.
 
+## `node:*` emulation
+
+ZenFS also includes emulation of some other `node:` modules for various reasons, importable from `@zenfs/core/<name>`:
+
+- `node:path`
+- `node:readline`
+
+For example:
+
+```ts
+import * as path from '@zenfs/core/path';
+```
+
 ## Bundling
 
 ZenFS exports a drop-in for Node's `fs` module, so you can use it for your bundler of preference using the default export.

package/dist/backends/cow.d.ts

@@ -1,5 +1,6 @@
 import type { CreationOptions, StreamOptions, UsageInfo } from '../internal/filesystem.js';
 import type { InodeLike } from '../internal/inode.js';
+import type { Backend } from './backend.js';
 import { EventEmitter } from 'eventemitter3';
 import { type MountConfiguration } from '../config.js';
 import { FileSystem } from '../internal/filesystem.js';
@@ -9,18 +10,17 @@ import { FileSystem } from '../internal/filesystem.js';
  */
 export interface CopyOnWriteOptions {
     /** The file system that initially populates this file system. */
-    readable: MountConfiguration<any>;
+    readable: MountConfiguration<Backend>;
     /** The file system to write modified files to. */
-    writable: MountConfiguration<any>;
+    writable: MountConfiguration<Backend>;
     /** @see {@link Journal} */
     journal?: Journal;
 }
-declare const journalOperations: readonly ["delete"];
 /**
  * @category Internals
  * @internal
  */
-export type JournalOperation = (typeof journalOperations)[number];
+export type JournalOperation = 'delete';
 /**
  * @category Internals
  * @internal
@@ -61,6 +61,7 @@ export declare class CopyOnWriteFS extends FileSystem {
     /** The journal to use for persisting deletions */
     readonly journal: Journal;
     ready(): Promise<void>;
+    readySync(): void;
     constructor(
     /** The file system that initially populates this file system. */
     readable: FileSystem, 

package/dist/backends/cow.js

@@ -6,12 +6,12 @@ import { resolveMountConfig } from '../config.js';
 import { FileSystem } from '../internal/filesystem.js';
 import { isDirectory } from '../internal/inode.js';
 import { dirname, join } from '../path.js';
-const journalOperations = ['delete'];
+const journalOperations = new Set(['delete']);
 /** Because TS doesn't work right w/o it */
 function isJournalOp(op) {
-    return journalOperations.includes(op);
+    return journalOperations.has(op);
 }
-const maxOpLength = Math.max(...journalOperations.map(op => op.length));
+const maxOpLength = Math.max(...journalOperations.values().map(op => op.length));
 const journalMagicString = '#journal@v0\n';
 /**
  * Tracks various operations for the CoW backend
@@ -79,6 +79,10 @@ export class CopyOnWriteFS extends FileSystem {
         await this.readable.ready();
         await this.writable.ready();
     }
+    readySync() {
+        this.readable.readySync();
+        this.writable.readySync();
+    }
     constructor(
     /** The file system that initially populates this file system. */
     readable, 

package/dist/backends/passthrough.js

@@ -54,7 +54,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { err, warn } from 'kerium/log';
 import { FileSystem } from '../internal/filesystem.js';
 import { isDirectory } from '../internal/inode.js';
-import { resolve } from '../path.js';
 export class PassthroughFS extends FileSystem {
     nodeFS;
     prefix;
@@ -306,7 +305,7 @@ const _Passthrough = {
         prefix: { type: 'string', required: true },
     },
     create({ fs, prefix }) {
-        return new PassthroughFS(fs, resolve(prefix));
+        return new PassthroughFS(fs, prefix);
     },
 };
 /**

package/dist/backends/store/fs.d.ts

@@ -40,6 +40,7 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
     _move(from: string, to: string): void;
     protected _initialized: boolean;
     ready(): Promise<void>;
+    readySync(): void;
     constructor(store: T);
     /**
      * @experimental
@@ -107,6 +108,7 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
      * Populates the `_ids` and `_paths` maps with all existing files stored in the underlying `Store`.
      */
     private _populate;
+    private _populateSync;
     /**
      * Find an inode without using the ID tables
      */

package/dist/backends/store/fs.js

@@ -144,6 +144,16 @@ export class StoreFS extends FileSystem {
         await this._populate();
         this._initialized = true;
     }
+    readySync() {
+        if (this._initialized)
+            return;
+        if (!this.attributes.has('no_async_preload')) {
+            this.checkRootSync();
+        }
+        this.checkRootSync();
+        this._populateSync();
+        this._initialized = true;
+    }
     constructor(store) {
         super(store.type ?? 0x6b766673, store.name);
         this.store = store;
@@ -781,6 +791,70 @@ export class StoreFS extends FileSystem {
                 await result_11;
         }
     }
+    _populateSync() {
+        const env_22 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (this._initialized) {
+                warn('Attempted to populate tables after initialization');
+                return;
+            }
+            debug('Populating tables with existing store metadata');
+            const tx = __addDisposableResource(env_22, this.transaction(), false);
+            const rootData = tx.getSync(rootIno);
+            if (!rootData) {
+                notice('Store does not have a root inode');
+                const inode = new Inode({ ino: rootIno, data: 1, mode: 0o777 | S_IFDIR });
+                tx.setSync(inode.data, encodeUTF8('{}'));
+                this._add(rootIno, '/');
+                tx.setSync(rootIno, inode);
+                tx.commitSync();
+                return;
+            }
+            if (rootData.length < sizeof(Inode)) {
+                crit('Store contains an invalid root inode. Refusing to populate tables');
+                return;
+            }
+            const visitedDirectories = new Set();
+            let i = 0;
+            const queue = [['/', rootIno]];
+            while (queue.length > 0) {
+                i++;
+                const [path, ino] = queue.shift();
+                this._add(ino, path);
+                const inodeData = tx.getSync(ino);
+                if (!inodeData) {
+                    warn('Store is missing data for inode: ' + ino);
+                    continue;
+                }
+                if (inodeData.length < sizeof(Inode)) {
+                    warn(`Invalid inode size for ino ${ino}: ${inodeData.length}`);
+                    continue;
+                }
+                const inode = new Inode(inodeData);
+                if ((inode.mode & S_IFDIR) != S_IFDIR || visitedDirectories.has(ino)) {
+                    continue;
+                }
+                visitedDirectories.add(ino);
+                const dirData = tx.getSync(inode.data);
+                if (!dirData) {
+                    warn('Store is missing directory data: ' + inode.data);
+                    continue;
+                }
+                const dirListing = decodeDirListing(dirData);
+                for (const [entryName, childIno] of Object.entries(dirListing)) {
+                    queue.push([join(path, entryName), childIno]);
+                }
+            }
+            debug(`Added ${i} existing inode(s) from store`);
+        }
+        catch (e_22) {
+            env_22.error = e_22;
+            env_22.hasError = true;
+        }
+        finally {
+            __disposeResources(env_22);
+        }
+    }
     /**
      * Find an inode without using the ID tables
      */
@@ -859,7 +933,7 @@ export class StoreFS extends FileSystem {
      * @param data The data to store at the file's data node.
      */
     async commitNew(path, options, data) {
-        const env_22 = { stack: [], error: void 0, hasError: false };
+        const env_23 = { stack: [], error: void 0, hasError: false };
         try {
             /*
                 The root always exists.
@@ -868,7 +942,7 @@ export class StoreFS extends FileSystem {
             */
             if (path == '/')
                 throw withErrno('EEXIST');
-            const tx = __addDisposableResource(env_22, this.transaction(), true);
+            const tx = __addDisposableResource(env_23, this.transaction(), true);
             const { dir: parentPath, base: fname } = parse(path);
             const parent = await this.findInode(tx, parentPath);
             const listing = decodeDirListing((await tx.get(parent.data)) ?? _throw(withErrno('ENOENT')));
@@ -892,12 +966,12 @@ export class StoreFS extends FileSystem {
             await tx.commit();
             return inode;
         }
-        catch (e_22) {
-            env_22.error = e_22;
-            env_22.hasError = true;
+        catch (e_23) {
+            env_23.error = e_23;
+            env_23.hasError = true;
         }
         finally {
-            const result_12 = __disposeResources(env_22);
+            const result_12 = __disposeResources(env_23);
             if (result_12)
                 await result_12;
         }
@@ -911,7 +985,7 @@ export class StoreFS extends FileSystem {
      * @return The Inode for the new file.
      */
     commitNewSync(path, options, data) {
-        const env_23 = { stack: [], error: void 0, hasError: false };
+        const env_24 = { stack: [], error: void 0, hasError: false };
         try {
             /*
                 The root always exists.
@@ -920,7 +994,7 @@ export class StoreFS extends FileSystem {
             */
             if (path == '/')
                 throw withErrno('EEXIST');
-            const tx = __addDisposableResource(env_23, this.transaction(), false);
+            const tx = __addDisposableResource(env_24, this.transaction(), false);
             const { dir: parentPath, base: fname } = parse(path);
             const parent = this.findInodeSync(tx, parentPath);
             const listing = decodeDirListing(tx.getSync(parent.data) ?? _throw(withErrno('ENOENT')));
@@ -942,12 +1016,12 @@ export class StoreFS extends FileSystem {
             tx.commitSync();
             return inode;
         }
-        catch (e_23) {
-            env_23.error = e_23;
-            env_23.hasError = true;
+        catch (e_24) {
+            env_24.error = e_24;
+            env_24.hasError = true;
         }
         finally {
-            __disposeResources(env_23);
+            __disposeResources(env_24);
         }
     }
     /**
@@ -956,9 +1030,9 @@ export class StoreFS extends FileSystem {
      * @param isDir Does the path belong to a directory, or a file?
      */
     async remove(path, isDir) {
-        const env_24 = { stack: [], error: void 0, hasError: false };
+        const env_25 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_24, this.transaction(), true);
+            const tx = __addDisposableResource(env_25, this.transaction(), true);
             const { dir: parent, base: fileName } = parse(path), parentNode = await this.findInode(tx, parent), listing = decodeDirListing((await tx.get(parentNode.data)) ?? _throw(withErrno('ENOENT')));
             if (!listing[fileName])
                 throw withErrno('ENOENT');
@@ -979,12 +1053,12 @@ export class StoreFS extends FileSystem {
             }
             await tx.commit();
         }
-        catch (e_24) {
-            env_24.error = e_24;
-            env_24.hasError = true;
+        catch (e_25) {
+            env_25.error = e_25;
+            env_25.hasError = true;
         }
         finally {
-            const result_13 = __disposeResources(env_24);
+            const result_13 = __disposeResources(env_25);
             if (result_13)
                 await result_13;
         }
@@ -995,9 +1069,9 @@ export class StoreFS extends FileSystem {
      * @param isDir Does the path belong to a directory, or a file?
      */
     removeSync(path, isDir) {
-        const env_25 = { stack: [], error: void 0, hasError: false };
+        const env_26 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_25, this.transaction(), false);
+            const tx = __addDisposableResource(env_26, this.transaction(), false);
             const { dir: parent, base: fileName } = parse(path), parentNode = this.findInodeSync(tx, parent), listing = decodeDirListing(tx.getSync(parentNode.data) ?? _throw(withErrno('ENOENT'))), ino = listing[fileName];
             if (!ino)
                 throw withErrno('ENOENT');
@@ -1017,12 +1091,12 @@ export class StoreFS extends FileSystem {
             }
             tx.commitSync();
         }
-        catch (e_25) {
-            env_25.error = e_25;
-            env_25.hasError = true;
+        catch (e_26) {
+            env_26.error = e_26;
+            env_26.hasError = true;
         }
         finally {
-            __disposeResources(env_25);
+            __disposeResources(env_26);
         }
     }
 }

package/dist/config.d.ts

@@ -18,6 +18,13 @@ export type MountConfiguration<T extends Backend> = FilesystemOf<T> | BackendCon
  * @see MountConfiguration
  */
 export declare function resolveMountConfig<T extends Backend>(configuration: MountConfiguration<T>, _depth?: number): Promise<FilesystemOf<T>>;
+/**
+ * @experimental
+ * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
+ * @see MountConfiguration
+ */
+export declare function resolveMountConfigSync<T extends Backend>(configuration: MountConfiguration<T>, _depth?: number): FilesystemOf<T>;
 /**
  * An object mapping mount points to backends
  * @category Backends and Configuration
@@ -82,6 +89,12 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
  * @category Backends and Configuration
  */
 export declare function configureSingle<T extends Backend>(configuration: MountConfiguration<T>): Promise<void>;
+/**
+ * @experimental
+ * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
+ */
+export declare function configureSingleSync<T extends Backend>(configuration: MountConfiguration<T>): void;
 /**
  * @category Backends and Configuration
  */
@@ -92,4 +105,11 @@ export declare function addDevice(driver: DeviceDriver, options?: object): Devic
  * @see Configuration
  */
 export declare function configure<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): Promise<void>;
+/**
+ * @experimental
+ * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
+ * @see Configuration
+ */
+export declare function configureSync<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): void;
 export declare function sync(): Promise<void>;

package/dist/config.js

@@ -5,6 +5,7 @@ import { createCredentials } from './internal/credentials.js';
 import { DeviceFS } from './internal/devices.js';
 import { FileSystem } from './internal/filesystem.js';
 import { exists, mkdir, stat } from './node/promises.js';
+import { existsSync, mkdirSync, statSync } from './node/sync.js';
 import { _setAccessChecks } from './vfs/config.js';
 import { mount, mounts, umount } from './vfs/shared.js';
 /**
@@ -20,6 +21,9 @@ export function configureFileSystem(fs, config) {
 function isMountConfig(arg) {
     return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
 }
+function isThenable(value) {
+    return typeof value?.then == 'function';
+}
 /**
  * Retrieve a file system with `configuration`.
  * @category Backends and Configuration
@@ -60,6 +64,57 @@ export async function resolveMountConfig(configuration, _depth = 0) {
     await mount.ready();
     return mount;
 }
+/**
+ * @experimental
+ * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
+ * @see MountConfiguration
+ */
+export function resolveMountConfigSync(configuration, _depth = 0) {
+    if (typeof configuration !== 'object' || configuration == null) {
+        throw log.err(withErrno('EINVAL', 'Invalid options on mount configuration'));
+    }
+    if (!isMountConfig(configuration)) {
+        throw log.err(withErrno('EINVAL', 'Invalid mount configuration'));
+    }
+    if (configuration instanceof FileSystem) {
+        configuration.readySync();
+        return configuration;
+    }
+    if (isBackend(configuration)) {
+        configuration = { backend: configuration };
+    }
+    for (const [key, value] of Object.entries(configuration)) {
+        if (key == 'backend')
+            continue;
+        if (!isMountConfig(value))
+            continue;
+        log.info('Resolving nested mount configuration: ' + key);
+        if (_depth > 10) {
+            throw log.err(withErrno('EINVAL', 'Invalid configuration, too deep and possibly infinite'));
+        }
+        configuration[key] = resolveMountConfigSync(value, ++_depth);
+    }
+    const { backend } = configuration;
+    if (typeof backend.isAvailable == 'function') {
+        const available = backend.isAvailable(configuration);
+        if (isThenable(available)) {
+            throw log.err(withErrno('EAGAIN', 'Backend availability check would block: ' + backend.name));
+        }
+        if (!available) {
+            throw log.err(withErrno('EPERM', 'Backend not available: ' + backend.name));
+        }
+    }
+    checkOptions(backend, configuration);
+    const mountFs = backend.create(configuration);
+    if (isThenable(mountFs)) {
+        throw log.err(withErrno('EAGAIN', 'Backend initialization would block: ' + backend.name));
+    }
+    const resolved = mountFs;
+    configureFileSystem(resolved, configuration);
+    resolved.readySync();
+    return resolved;
+}
 /**
  * Configures ZenFS with single mount point /
  * @category Backends and Configuration
@@ -72,6 +127,19 @@ export async function configureSingle(configuration) {
     umount('/');
     mount('/', resolved);
 }
+/**
+ * @experimental
+ * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
+ */
+export function configureSingleSync(configuration) {
+    if (!isMountConfig(configuration)) {
+        throw new TypeError('Invalid single mount point configuration');
+    }
+    const resolved = resolveMountConfigSync(configuration);
+    umount('/');
+    mount('/', resolved);
+}
 /**
  * Like `fs.mount`, but it also creates missing directories.
  * @privateRemarks
@@ -92,6 +160,33 @@ async function mountWithMkdir(path, fs) {
     }
     mount(path, fs);
 }
+/**
+ * Like `fs.mount`, but it also creates missing directories.
+ * @privateRemarks
+ * This is implemented as a separate function to avoid a circular dependency between vfs/shared.ts and other vfs layer files.
+ * @internal
+ */
+function mountWithMkdirSync(path, fs) {
+    if (path == '/') {
+        mount(path, fs);
+        return;
+    }
+    let stats = null;
+    try {
+        stats = statSync(path);
+    }
+    catch (error) {
+        if (error?.code != 'ENOENT')
+            throw error;
+    }
+    if (!stats) {
+        mkdirSync(path, { recursive: true });
+    }
+    else if (!stats.isDirectory()) {
+        throw withErrno('ENOTDIR', 'Missing directory at mount point: ' + path);
+    }
+    mount(path, fs);
+}
 /**
  * @category Backends and Configuration
  */
@@ -149,6 +244,53 @@ export async function configure(configuration) {
         }
     }
 }
+/**
+ * @experimental
+ * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
+ * @see Configuration
+ */
+export function configureSync(configuration) {
+    Object.assign(defaultContext.credentials, createCredentials({
+        uid: configuration.uid || 0,
+        gid: configuration.gid || 0,
+    }));
+    _setAccessChecks(!configuration.disableAccessChecks);
+    if (configuration.log)
+        log.configure(configuration.log);
+    if (configuration.mounts) {
+        for (const [_point, mountConfig] of Object.entries(configuration.mounts).sort(([a], [b]) => (a.length > b.length ? 1 : -1))) {
+            const point = _point.startsWith('/') ? _point : '/' + _point;
+            if (isBackendConfig(mountConfig)) {
+                mountConfig.disableAsyncCache ??= configuration.disableAsyncCache || false;
+                mountConfig.caseFold ??= configuration.caseFold;
+            }
+            if (point == '/')
+                umount('/');
+            mountWithMkdirSync(point, resolveMountConfigSync(mountConfig));
+        }
+    }
+    for (const fs of mounts.values()) {
+        configureFileSystem(fs, configuration);
+    }
+    if (configuration.addDevices && !mounts.has('/dev')) {
+        const devfs = new DeviceFS();
+        devfs.addDefaults();
+        devfs.readySync();
+        mountWithMkdirSync('/dev', devfs);
+    }
+    if (configuration.defaultDirectories) {
+        for (const dir of _defaultDirectories) {
+            if (existsSync(dir)) {
+                const stats = statSync(dir);
+                if (!stats.isDirectory())
+                    log.warn('Default directory exists but is not a directory: ' + dir);
+                continue;
+            }
+            mkdirSync(dir);
+        }
+    }
+}
 export async function sync() {
     for (const fs of mounts.values())
         await fs.sync();

package/dist/internal/filesystem.d.ts

@@ -171,6 +171,7 @@ export declare abstract class FileSystem {
      */
     usage(): UsageInfo;
     ready(): Promise<void>;
+    readySync(): void;
     abstract rename(oldPath: string, newPath: string): Promise<void>;
     abstract renameSync(oldPath: string, newPath: string): void;
     abstract stat(path: string): Promise<InodeLike>;

package/dist/internal/filesystem.js

@@ -1,3 +1,4 @@
+import { withErrno } from 'kerium';
 const _chunkSize = 0x1000;
 /**
  * Provides a consistent and easy to use internal API.
@@ -61,6 +62,10 @@ export class FileSystem {
         };
     }
     async ready() { }
+    readySync() {
+        if (this.ready !== FileSystem.prototype.ready)
+            throw withErrno('EAGAIN');
+    }
     /**
      * Test whether or not `path` exists.
      */

package/dist/mixins/mutexed.d.ts

@@ -35,6 +35,7 @@ export declare class _MutexedFS<T extends FileSystem> implements FileSystem {
     set _uuid(value: UUID);
     get uuid(): UUID;
     ready(): Promise<void>;
+    readySync(): void;
     usage(): UsageInfo;
     /**
      * The current locks

package/dist/mixins/mutexed.js

@@ -115,6 +115,9 @@ export class _MutexedFS {
     async ready() {
         return await this._fs.ready();
     }
+    readySync() {
+        return this._fs.readySync();
+    }
     usage() {
         return this._fs.usage();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.4.4",
+	"version": "2.5.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",

package/tests/common/config.test.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { configureSingleSync, configureSync, fs, InMemory, mounts, SingleBuffer, type Backend } from '@zenfs/core';
+import { Errno } from 'kerium';
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+
+const AsyncBackend = {
+	name: 'AsyncBackend',
+	options: {},
+	async create() {
+		await Promise.resolve();
+		return InMemory.create({ label: 'async-backend' });
+	},
+} satisfies Backend;
+
+suite('Sync configuration', () => {
+	test('configureSingleSync mounts root synchronously', () => {
+		configureSingleSync({ backend: InMemory, label: 'sync-root' });
+		assert.equal(mounts.get('/')?.label, 'sync-root');
+
+		fs.writeFileSync('/sync-file', 'sync');
+		assert.equal(fs.readFileSync('/sync-file', 'utf8'), 'sync');
+	});
+
+	test('configureSync mounts additional directories', () => {
+		configureSync({
+			mounts: {
+				tmp: { backend: InMemory, label: 'sync-tmp' },
+			},
+		});
+
+		assert.ok(mounts.has('/tmp'));
+		fs.writeFileSync('/tmp/sync.txt', 'ok');
+		assert.equal(fs.readFileSync('/tmp/sync.txt', 'utf8'), 'ok');
+
+		fs.umount('/tmp');
+		fs.rmSync('/tmp', { recursive: true, force: true });
+	});
+
+	test('configureSync rejects asynchronous backends', () => {
+		assert.throws(
+			() =>
+				configureSync({
+					mounts: { '/': { backend: AsyncBackend } },
+				}),
+			{ errno: Errno.EAGAIN }
+		);
+	});
+
+	test('configureSingleSync works with SingleBuffer', () => {
+		const buffer = new ArrayBuffer(0x20000);
+		configureSingleSync({ backend: SingleBuffer, buffer });
+
+		fs.writeFileSync('/sb.txt', 'single-buffer');
+		assert.equal(fs.readFileSync('/sb.txt', 'utf8'), 'single-buffer');
+	});
+});