@zenfs/core 2.4.3 → 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/context.d.ts

@@ -11,4 +11,4 @@ export declare const boundContexts: Map<number, BoundContext>;
  * Note that the default credentials of a bound context are copied from the global credentials.
  * @category Contexts
  */
-export declare function bindContext(this: void | null | FSContext, { root, pwd, credentials }?: ContextInit): BoundContext;
+export declare function bindContext(this: V_Context, init?: ContextInit): BoundContext;

package/dist/context.js

@@ -1,12 +1,10 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
+import { UV } from 'kerium';
 import { bindFunctions } from 'utilium';
-import { defaultContext } from './internal/contexts.js';
-import { createCredentials } from './internal/credentials.js';
-import * as path from './path.js';
+import { contextOf, createChildContext } from './internal/contexts.js';
 import * as fs from './node/index.js';
+import * as path from './path.js';
 import * as xattr from './vfs/xattr.js';
-// 0 is reserved for the global/default context
-let _nextId = 1;
 /**
  * A map of all contexts.
  * @internal
@@ -18,19 +16,12 @@ export const boundContexts = new Map();
  * Note that the default credentials of a bound context are copied from the global credentials.
  * @category Contexts
  */
-export function bindContext({ root = this?.root || '/', pwd = this?.pwd || '/', credentials = structuredClone(defaultContext.credentials) } = {}) {
-    const parent = this ?? defaultContext;
-    const ctx = {
-        id: _nextId++,
-        root,
-        pwd,
-        credentials: createCredentials(credentials),
-        descriptors: new Map(),
-        parent,
-        children: [],
-    };
-    const bound = {
-        ...ctx,
+export function bindContext(init = {}) {
+    const $ = contextOf(this);
+    if (!fs.statSync.call(this, $.root).isDirectory())
+        throw UV('ENOTDIR', { syscall: 'chroot', path: $.root });
+    const ctx = createChildContext($, init);
+    const bound = Object.assign(ctx, {
         fs: {
             ...bindFunctions(fs, ctx),
             promises: bindFunctions(fs.promises, ctx),
@@ -42,7 +33,7 @@ export function bindContext({ root = this?.root || '/', pwd = this?.pwd || '/',
             ctx.children.push(child);
             return child;
         },
-    };
+    });
     boundContexts.set(ctx.id, bound);
     return bound;
 }

package/dist/internal/contexts.d.ts

@@ -4,11 +4,18 @@ import type * as path from '../path.js';
 import type { Handle } from '../vfs/file.js';
 import type * as xattr from '../vfs/xattr.js';
 import type { Credentials, CredentialsInit } from './credentials.js';
+/**
+ * Symbol used for context branding
+ * @internal @hidden
+ */
+declare const kIsContext: unique symbol;
 /**
  * A context used for FS operations
  * @category Contexts
  */
 export interface FSContext {
+    /** The unique ID of the context */
+    readonly [kIsContext]: boolean;
     /** The unique ID of the context */
     readonly id: number;
     /**
@@ -22,16 +29,16 @@ export interface FSContext {
     /** The credentials of the context, used for access checks */
     readonly credentials: Credentials;
     /** A map of open file descriptors to their handles */
-    descriptors: Map<number, Handle>;
+    readonly descriptors: Map<number, Handle>;
     /** The parent context, if any. */
-    parent: V_Context;
+    readonly parent: FSContext | null;
     /** The child contexts */
-    children: FSContext[];
+    readonly children: FSContext[];
 }
 /**
  * maybe an FS context
  */
-export type V_Context = void | null | (Partial<FSContext> & object);
+export type V_Context = unknown;
 /**
  * Allows you to restrict operations to a specific root path and set of credentials.
  * @category Contexts
@@ -62,3 +69,16 @@ export interface ContextInit {
  * @category Contexts
  */
 export declare const defaultContext: FSContext;
+export declare function contextOf($: unknown): FSContext;
+/**
+ * Create a blank FS Context
+ * @internal
+ * @category Contexts
+ * @todo Make sure parent root can't be escaped
+ *
+ * This exists so that `kIsContext` is not exported and to make sure the context is "secure".
+ */
+export declare function createChildContext(parent: FSContext, init?: ContextInit): FSContext & {
+    parent: FSContext;
+};
+export {};

package/dist/internal/contexts.js

@@ -1,10 +1,16 @@
 import { createCredentials } from './credentials.js';
+/**
+ * Symbol used for context branding
+ * @internal @hidden
+ */
+const kIsContext = Symbol('ZenFSContext');
 /**
  * The default/global context.
  * @internal @hidden
  * @category Contexts
  */
 export const defaultContext = {
+    [kIsContext]: true,
     id: 0,
     root: '/',
     pwd: '/',
@@ -13,3 +19,37 @@ export const defaultContext = {
     parent: null,
     children: [],
 };
+export function contextOf($) {
+    return typeof $ === 'object' && $ !== null && kIsContext in $ ? $ : defaultContext;
+}
+// 0 is reserved for the global/default context
+let _nextId = 1;
+/**
+ * Create a blank FS Context
+ * @internal
+ * @category Contexts
+ * @todo Make sure parent root can't be escaped
+ *
+ * This exists so that `kIsContext` is not exported and to make sure the context is "secure".
+ */
+export function createChildContext(parent, init = {}) {
+    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials) } = init;
+    const ctx = {
+        [kIsContext]: true,
+        id: _nextId++,
+        root,
+        pwd,
+        credentials: createCredentials(credentials),
+        descriptors: new Map(),
+        parent: parent,
+        children: [],
+    };
+    Object.defineProperties(ctx, {
+        id: { configurable: false, writable: false },
+        credentials: { configurable: false, writable: false },
+        descriptors: { configurable: false, writable: false },
+        parent: { configurable: false, writable: false },
+        children: { configurable: false, writable: false },
+    });
+    return ctx;
+}

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/internal/inode.js

@@ -39,9 +39,9 @@ import { sizeof } from 'memium';
 import { $from, field, struct, types as t } from 'memium/decorators';
 import { decodeUTF8, encodeUTF8, pick } from 'utilium';
 import { BufferView } from 'utilium/buffer.js';
-import { Stats } from '../node/stats.js';
 import * as c from '../constants.js';
-import { defaultContext } from './contexts.js';
+import { Stats } from '../node/stats.js';
+import { contextOf } from './contexts.js';
 /**
  * Root inode
  * @hidden
@@ -620,7 +620,7 @@ export function isFIFO(metadata) {
  * @internal
  */
 export function hasAccess($, inode, access) {
-    const credentials = $?.credentials || defaultContext.credentials;
+    const { credentials } = contextOf($);
     if (isSymbolicLink(inode) || credentials.euid === 0 || credentials.egid === 0)
         return true;
     let perm = 0;

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/dist/node/sync.js

@@ -467,7 +467,7 @@ export function lutimesSync(path, atime, mtime) {
 lutimesSync;
 export function realpathSync(path, options) {
     const encoding = typeof options == 'string' ? options : (options?.encoding ?? 'utf8');
-    path = normalizePath(path);
+    path = normalizePath(path, true);
     const { fullPath } = _sync.resolve(this, path);
     if (encoding == 'utf8' || encoding == 'utf-8')
         return fullPath;

package/dist/path.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-import { defaultContext } from './internal/contexts.js';
+import { contextOf } from './internal/contexts.js';
 import { globToRegex } from './utils.js';
 export const sep = '/';
 function validateObject(str, name) {
@@ -81,7 +81,7 @@ export function formatExt(ext) {
 }
 export function resolve(...parts) {
     let resolved = '';
-    for (const part of [...parts.reverse(), this?.pwd ?? defaultContext.pwd]) {
+    for (const part of [...parts.reverse(), contextOf(this).pwd]) {
         if (!part?.length)
             continue;
         resolved = `${part}/${resolved}`;
@@ -334,7 +334,7 @@ export function format(pathObject) {
     return dir === pathObject.root ? `${dir}${base}` : `${dir}/${base}`;
 }
 export function parse(path) {
-    const isAbsolute = path.startsWith('/');
+    const isAbsolute = path[0] === '/';
     const ret = { root: isAbsolute ? '/' : '', dir: '', base: '', ext: '', name: '' };
     if (path.length === 0)
         return ret;

package/dist/utils.d.ts

@@ -2,6 +2,7 @@ import { type Exception } from 'kerium';
 import type * as fs from 'node:fs';
 import type { Worker as NodeWorker } from 'node:worker_threads';
 import { type OptionalTuple } from 'utilium';
+import type { V_Context } from './internal/contexts.js';
 declare global {
     function atob(data: string): string;
     function btoa(data: string): string;
@@ -31,8 +32,9 @@ export declare function normalizeTime(time: fs.TimeLike): number;
 /**
  * Normalizes a path
  * @internal
+ * @todo clean this up and make it so `path.resolve` is only called when an explicit context is passed (i.e. `normalizePath(..., $)` to use `path.resolve`)
  */
-export declare function normalizePath(p: fs.PathLike, noResolve?: boolean): string;
+export declare function normalizePath(this: V_Context, p: fs.PathLike, noResolve?: boolean): string;
 /**
  * Normalizes options
  * @param options options to normalize

package/dist/utils.js

@@ -51,6 +51,7 @@ export function normalizeTime(time) {
 /**
  * Normalizes a path
  * @internal
+ * @todo clean this up and make it so `path.resolve` is only called when an explicit context is passed (i.e. `normalizePath(..., $)` to use `path.resolve`)
  */
 export function normalizePath(p, noResolve = false) {
     if (p instanceof URL) {
@@ -67,7 +68,7 @@ export function normalizePath(p, noResolve = false) {
         throw withErrno('EINVAL', 'Path can not be empty');
     p = p.replaceAll(/[/\\]+/g, '/');
     // Note: PWD is not resolved here, it is resolved later.
-    return noResolve ? p : resolve(p);
+    return noResolve ? p : resolve.call(this, p);
 }
 /**
  * Normalizes options

package/dist/vfs/acl.js

@@ -44,9 +44,9 @@ import { err } from 'kerium/log';
 import { packed, sizeof } from 'memium';
 import { $from, struct, types as t } from 'memium/decorators';
 import { BufferView } from 'utilium/buffer.js';
-import { defaultContext } from '../internal/contexts.js';
-import { Attributes } from '../internal/inode.js';
 import { R_OK, S_IRWXG, S_IRWXO, S_IRWXU, W_OK, X_OK } from '../constants.js';
+import { contextOf } from '../internal/contexts.js';
+import { Attributes } from '../internal/inode.js';
 import * as xattr from './xattr.js';
 const version = 2;
 export var Type;
@@ -206,7 +206,7 @@ export function check($, inode, access) {
     if (!shouldCheck)
         return true;
     inode.attributes ??= new Attributes();
-    const { euid, egid } = $?.credentials ?? defaultContext.credentials;
+    const { euid, egid } = contextOf($).credentials;
     const data = inode.attributes.get('system.posix_acl_access');
     if (!data)
         return true;

package/dist/vfs/async.js

@@ -1,7 +1,7 @@
 import { setUVMessage, UV } from 'kerium';
 import { decodeUTF8 } from 'utilium';
 import * as constants from '../constants.js';
-import { defaultContext } from '../internal/contexts.js';
+import { contextOf } from '../internal/contexts.js';
 import { hasAccess, isDirectory, isSymbolicLink } from '../internal/inode.js';
 import { basename, dirname, join, parse, resolve as resolvePath } from '../path.js';
 import { normalizeMode, normalizePath } from '../utils.js';
@@ -17,6 +17,7 @@ import { emitChange } from './watchers.js';
  * @internal @hidden
  */
 export async function resolve($, path, preserveSymlinks, extra) {
+    path = resolvePath.call($, path);
     if (preserveSymlinks) {
         const resolved = resolveMount(path, $, extra);
         const stats = await resolved.fs.stat(resolved.path).catch(() => undefined);
@@ -74,7 +75,7 @@ export async function open($, path, opt) {
             throw UV('ENOTDIR', 'open', dirname(path));
         if (!opt.allowDirectory && mode & constants.S_IFDIR)
             throw UV('EISDIR', 'open', path);
-        const { euid: uid, egid: gid } = $?.credentials ?? defaultContext.credentials;
+        const { euid: uid, egid: gid } = contextOf($).credentials;
         const inode = await fs.createFile(resolved, {
             mode,
             uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
@@ -110,7 +111,7 @@ export async function readlink(path) {
 }
 export async function mkdir(path, options = {}) {
     path = normalizePath(path);
-    const { euid: uid, egid: gid } = this?.credentials ?? defaultContext.credentials;
+    const { euid: uid, egid: gid } = contextOf(this).credentials;
     const { mode = 0o777, recursive } = options;
     const { fs, path: resolved } = resolveMount(path, this, { syscall: 'mkdir' });
     const __create = async (path, resolved, parent) => {

package/dist/vfs/file.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { UV, withErrno } from 'kerium';
 import * as c from '../constants.js';
-import { defaultContext } from '../internal/contexts.js';
+import { contextOf } from '../internal/contexts.js';
 import { _chown, InodeFlags, isBlockDevice, isCharacterDevice } from '../internal/inode.js';
 import '../polyfills.js';
 /**
@@ -371,7 +371,7 @@ export class Handle {
  * @internal @hidden
  */
 export function toFD(file) {
-    const map = file.context?.descriptors ?? defaultContext.descriptors;
+    const map = contextOf(file.context).descriptors;
     const fd = Math.max(map.size ? Math.max(...map.keys()) + 1 : 0, 4);
     map.set(fd, file);
     return fd;
@@ -380,12 +380,12 @@ export function toFD(file) {
  * @internal @hidden
  */
 export function fromFD($, fd) {
-    const map = $?.descriptors ?? defaultContext.descriptors;
+    const map = contextOf($).descriptors;
     const value = map.get(fd);
     if (!value)
         throw withErrno('EBADF');
     return value;
 }
 export function deleteFD($, fd) {
-    return ($?.descriptors ?? defaultContext.descriptors).delete(fd);
+    return contextOf($).descriptors.delete(fd);
 }

package/dist/vfs/shared.js

@@ -4,7 +4,7 @@ import { Errno, Exception, UV, withErrno } from 'kerium';
 import { alert, debug, err, info, notice, warn } from 'kerium/log';
 import { InMemory } from '../backends/memory.js';
 import { size_max } from '../constants.js';
-import { defaultContext } from '../internal/contexts.js';
+import { contextOf } from '../internal/contexts.js';
 import { credentialsAllowRoot } from '../internal/credentials.js';
 import { withExceptionContext } from '../internal/error.js';
 import { join, resolve } from '../path.js';
@@ -53,9 +53,10 @@ export function umount(mountPoint) {
  * @internal @hidden
  */
 export function resolveMount(path, ctx, extra) {
-    const root = ctx?.root || defaultContext.root;
+    const { root } = contextOf(ctx);
     const _exceptionContext = { path, ...extra };
-    path = normalizePath(join(root, path));
+    path = normalizePath(join(root, path), true);
+    path = resolve.call(ctx, path);
     const sortedMounts = [...mounts].sort((a, b) => (a[0].length > b[0].length ? -1 : 1)); // descending order of the string length
     for (const [mountPoint, fs] of sortedMounts) {
         // We know path is normalized, so it would be a substring of the mount point.
@@ -94,7 +95,7 @@ export function _statfs(fs, bigint) {
  * @category Backends and Configuration
  */
 export function chroot(path) {
-    const $ = this ?? defaultContext;
+    const $ = contextOf(this);
     if (!credentialsAllowRoot($.credentials))
         throw withErrno('EPERM', 'Can not chroot() as non-root user');
     $.root ??= '/';

package/dist/vfs/sync.js

@@ -1,7 +1,7 @@
 import { setUVMessage, UV } from 'kerium';
 import { decodeUTF8 } from 'utilium';
 import * as constants from '../constants.js';
-import { defaultContext } from '../internal/contexts.js';
+import { contextOf } from '../internal/contexts.js';
 import { hasAccess, isDirectory, isSymbolicLink } from '../internal/inode.js';
 import { basename, dirname, join, parse, resolve as resolvePath } from '../path.js';
 import { normalizeMode, normalizePath } from '../utils.js';
@@ -18,6 +18,7 @@ import { emitChange } from './watchers.js';
  * @internal @hidden
  */
 export function resolve($, path, preserveSymlinks, extra) {
+    path = resolvePath.call($, path);
     /* Try to resolve it directly. If this works,
     that means we don't need to perform any resolution for parent directories. */
     try {
@@ -87,7 +88,7 @@ export function open(path, opt) {
         if (checkAccess && !hasAccess(this, parentStats, constants.W_OK)) {
             throw UV('EACCES', 'open', path);
         }
-        const { euid: uid, egid: gid } = this?.credentials ?? defaultContext.credentials;
+        const { euid: uid, egid: gid } = contextOf(this).credentials;
         const inode = fs.createFileSync(resolved, {
             mode,
             uid: parentStats.mode & constants.S_ISUID ? parentStats.uid : uid,
@@ -124,7 +125,7 @@ export function readlink(path) {
 export function mkdir(path, options = {}) {
     path = normalizePath(path);
     const { fs, path: resolved } = resolve(this, path);
-    const { euid: uid, egid: gid } = this?.credentials ?? defaultContext.credentials;
+    const { euid: uid, egid: gid } = contextOf(this).credentials;
     const { mode = 0o777, recursive } = options;
     const __create = (path, resolved, parent) => {
         if (checkAccess && !hasAccess(this, parent, constants.W_OK))

package/dist/vfs/watchers.d.ts

@@ -75,5 +75,5 @@ export declare function removeWatcher(path: string, watcher: FSWatcher): void;
 /**
  * @internal @hidden
  */
-export declare function emitChange($: V_Context, eventType: fs.WatchEventType, filename: string): void;
+export declare function emitChange(context: V_Context, eventType: fs.WatchEventType, filename: string): void;
 export {};

package/dist/vfs/watchers.js

@@ -1,9 +1,10 @@
 import { EventEmitter } from 'eventemitter3';
 import { UV } from 'kerium';
-import { basename, dirname, join, relative } from '../path.js';
-import { normalizePath } from '../utils.js';
+import { contextOf } from '../internal/contexts.js';
 import { isStatsEqual } from '../node/stats.js';
 import { statSync } from '../node/sync.js';
+import { basename, dirname, join, relative } from '../path.js';
+import { normalizePath } from '../utils.js';
 /**
  * Base class for file system watchers.
  * Provides event handling capabilities for watching file system changes.
@@ -61,9 +62,10 @@ export class FSWatcher extends Watcher {
     options;
     realpath;
     constructor(context, path, options) {
-        super(context, path);
+        const $ = contextOf(context);
+        super($, path);
         this.options = options;
-        this.realpath = context?.root ? join(context.root, path) : path;
+        this.realpath = join($.root, path);
         addWatcher(this.realpath, this);
     }
     close() {
@@ -145,7 +147,8 @@ export function removeWatcher(path, watcher) {
 /**
  * @internal @hidden
  */
-export function emitChange($, eventType, filename) {
+export function emitChange(context, eventType, filename) {
+    const $ = contextOf(context);
     if ($)
         filename = join($.root ?? '/', filename);
     filename = normalizePath(filename);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.4.3",
+	"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');
+	});
+});

package/tests/common/context.test.ts

@@ -60,8 +60,7 @@ suite('Context', () => {
 		await promise;
 	});
 
-	test('Path resolution of / with context root and mount point being the same', async () => {
-		// @zenfs/core#226
+	test('Path resolution of / with context root and mount point being the same #226', async () => {
 		await configure({
 			mounts: { '/bananas': InMemory },
 		});
@@ -73,8 +72,7 @@ suite('Context', () => {
 		assert.deepEqual(bananas.fs.readdirSync('/'), ['yellow']);
 	});
 
-	test('Different working directory', { todo: true }, () => {
-		// @zenfs/core#263
+	test('Different working directory #263', () => {
 		ctx.mkdirSync('/test');
 		context.pwd = '/test';
 

package/tests/fs/links.test.ts

@@ -19,8 +19,7 @@ suite('Links', () => {
 		assert(stats.isSymbolicLink());
 	});
 
-	test('lstat file inside symlinked directory', async () => {
-		// @zenfs/core#241
+	test('lstat file inside symlinked directory #241', async () => {
 		await fs.promises.mkdir('/a');
 		await fs.promises.writeFile('/a/hello.txt', 'hello world');
 		await fs.promises.symlink('/a', '/b');

package/tests/fs/read.test.ts

@@ -70,8 +70,7 @@ suite('read', () => {
 		assert.equal(bytesRead, expected.length);
 	});
 
-	test('read using callback API', async () => {
-		// @zenfs/core#239
+	test('read using callback API #239', async () => {
 		const path = '/text.txt';
 
 		fs.writeFileSync(path, 'hello world');