@zenfs/core 1.2.7 → 1.2.9

package/dist/backends/backend.d.ts

@@ -12,8 +12,9 @@ export type OptionsConfig<T> = {
         type: OptionType | readonly OptionType[];
         /**
          * Description of the option. Used in error messages and documentation.
+         * @deprecated
          */
-        description: string;
+        description?: string;
         /**
          * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
          */

package/dist/backends/fetch.d.ts

@@ -6,6 +6,10 @@ import type { IndexData } from './file_index.js';
  * Configuration options for FetchFS.
  */
 export interface FetchOptions {
+    /**
+     * Options to pass through to fetch calls
+     */
+    requestInit?: RequestInit;
     /**
      * URL to a file index as a JSON file or the file index object itself.
      * Defaults to `index.json`.
@@ -37,8 +41,9 @@ export interface FetchOptions {
  */
 export declare class FetchFS extends IndexFS {
     readonly baseUrl: string;
+    readonly requestInit?: RequestInit;
     ready(): Promise<void>;
-    constructor({ index, baseUrl }: FetchOptions);
+    constructor({ index, baseUrl, requestInit }: FetchOptions);
     metadata(): FileSystemMetadata;
     /**
      * Preload the `path` into the index.
@@ -56,12 +61,14 @@ declare const _Fetch: {
         readonly index: {
             readonly type: readonly ["string", "object"];
             readonly required: false;
-            readonly description: "URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.";
         };
         readonly baseUrl: {
             readonly type: "string";
             readonly required: false;
-            readonly description: "Used as the URL prefix for fetched files. Default: Fetch files relative to the index.";
+        };
+        readonly requestInit: {
+            readonly type: "object";
+            readonly required: false;
         };
     };
     readonly isAvailable: () => boolean;

package/dist/backends/fetch.js

@@ -1,7 +1,7 @@
 import { Errno, ErrnoError } from '../error.js';
 import { IndexFS } from './file_index.js';
-async function fetchFile(path, type) {
-    const response = await fetch(path).catch((e) => {
+async function fetchFile(path, type, init) {
+    const response = await fetch(path, init).catch((e) => {
         throw new ErrnoError(Errno.EIO, e.message, path);
     });
     if (!response.ok) {
@@ -57,13 +57,14 @@ export class FetchFS extends IndexFS {
             await this.getData(path, stats);
         }
     }
-    constructor({ index = 'index.json', baseUrl = '' }) {
+    constructor({ index = 'index.json', baseUrl = '', requestInit }) {
         // prefix url must end in a directory separator.
         if (baseUrl.at(-1) != '/') {
             baseUrl += '/';
         }
-        super(typeof index != 'string' ? index : fetchFile(baseUrl + index, 'json'));
+        super(typeof index != 'string' ? index : fetchFile(baseUrl + index, 'json', requestInit));
         this.baseUrl = baseUrl;
+        this.requestInit = requestInit;
     }
     metadata() {
         return {
@@ -93,7 +94,7 @@ export class FetchFS extends IndexFS {
         if (stats.fileData) {
             return stats.fileData;
         }
-        const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer');
+        const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer', this.requestInit);
         stats.fileData = data;
         return data;
     }
@@ -107,16 +108,9 @@ export class FetchFS extends IndexFS {
 const _Fetch = {
     name: 'Fetch',
     options: {
-        index: {
-            type: ['string', 'object'],
-            required: false,
-            description: 'URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.',
-        },
-        baseUrl: {
-            type: 'string',
-            required: false,
-            description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
-        },
+        index: { type: ['string', 'object'], required: false },
+        baseUrl: { type: 'string', required: false },
+        requestInit: { type: 'object', required: false },
     },
     isAvailable() {
         return typeof globalThis.fetch == 'function';

package/dist/backends/memory.d.ts

@@ -22,7 +22,6 @@ declare const _InMemory: {
         readonly name: {
             readonly type: "string";
             readonly required: false;
-            readonly description: "The name of the store";
         };
     };
     readonly create: ({ name }: {

package/dist/backends/memory.js

@@ -26,11 +26,7 @@ const _InMemory = {
         return true;
     },
     options: {
-        name: {
-            type: 'string',
-            required: false,
-            description: 'The name of the store',
-        },
+        name: { type: 'string', required: false },
     },
     create({ name }) {
         const fs = new StoreFS(new InMemoryStore(name));

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

@@ -110,13 +110,11 @@ declare const _Port: {
         port: {
             type: "object";
             required: true;
-            description: string;
             validator(port: RPC.Port): void;
         };
         timeout: {
             type: "number";
             required: false;
-            description: string;
         };
     };
     isAvailable(): boolean;

package/dist/backends/port/fs.js

@@ -214,7 +214,6 @@ const _Port = {
         port: {
             type: 'object',
             required: true,
-            description: 'The target port that you want to connect to',
             validator(port) {
                 // Check for a `postMessage` function.
                 if (typeof port?.postMessage != 'function') {
@@ -225,7 +224,6 @@ const _Port = {
         timeout: {
             type: 'number',
             required: false,
-            description: 'How long to wait before the request times out',
         },
     },
     isAvailable() {

package/dist/backends/store/fs.js

@@ -642,17 +642,17 @@ export class StoreFS extends FileSystem {
     async commitNew(path, type, mode, data) {
         const env_15 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_15, this.store.transaction(), true);
-            const parentPath = dirname(path), parent = await this.findINode(tx, parentPath);
-            const fname = basename(path), listing = await this.getDirListing(tx, parent, parentPath);
             /*
                 The root always exists.
                 If we don't check this prior to taking steps below,
-                we will create a file with name '' in root should path == '/'.
+                we will create a file with name '' in root if path is '/'.
             */
-            if (path === '/') {
+            if (path == '/') {
                 throw ErrnoError.With('EEXIST', path, 'commitNew');
             }
+            const tx = __addDisposableResource(env_15, this.store.transaction(), true);
+            const parentPath = dirname(path), parent = await this.findINode(tx, parentPath);
+            const fname = basename(path), listing = await this.getDirListing(tx, parent, parentPath);
             // Check if file already exists.
             if (listing[fname]) {
                 await tx.abort();
@@ -693,17 +693,17 @@ export class StoreFS extends FileSystem {
     commitNewSync(path, type, mode, data = new Uint8Array()) {
         const env_16 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_16, this.store.transaction(), false);
-            const parentPath = dirname(path), parent = this.findINodeSync(tx, parentPath);
-            const fname = basename(path), listing = this.getDirListingSync(tx, parent, parentPath);
             /*
                 The root always exists.
                 If we don't check this prior to taking steps below,
-                we will create a file with name '' in root should p == '/'.
+                we will create a file with name '' in root if path is '/'.
             */
-            if (path === '/') {
+            if (path == '/') {
                 throw ErrnoError.With('EEXIST', path, 'commitNew');
             }
+            const tx = __addDisposableResource(env_16, this.store.transaction(), false);
+            const parentPath = dirname(path), parent = this.findINodeSync(tx, parentPath);
+            const fname = basename(path), listing = this.getDirListingSync(tx, parent, parentPath);
             // Check if file already exists.
             if (listing[fname]) {
                 throw ErrnoError.With('EEXIST', path, 'commitNew');

package/dist/config.js

@@ -1,9 +1,9 @@
 import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
 import { credentials } from './credentials.js';
-import { DeviceFS, fullDevice, nullDevice, randomDevice, zeroDevice } from './devices.js';
+import { DeviceFS } from './devices.js';
 import * as cache from './emulation/cache.js';
-import * as fs from './emulation/index.js';
 import { config } from './emulation/config.js';
+import * as fs from './emulation/index.js';
 import { Errno, ErrnoError } from './error.js';
 import { FileSystem } from './filesystem.js';
 function isMountConfig(arg) {
@@ -60,6 +60,26 @@ export async function configureSingle(configuration) {
     fs.umount('/');
     fs.mount('/', resolved);
 }
+/**
+ * Like `fs.mount`, but it also creates missing directories.
+ * @privateRemarks
+ * This is implemented as a separate function to avoid a circular dependency between emulation/shared.ts and other emulation layer files.
+ * @internal
+ */
+async function mount(path, mount) {
+    if (path == '/') {
+        fs.mount(path, mount);
+        return;
+    }
+    const stats = await fs.promises.stat(path).catch(() => null);
+    if (!stats) {
+        await fs.promises.mkdir(path, { recursive: true });
+    }
+    else if (!stats.isDirectory()) {
+        throw ErrnoError.With('ENOTDIR', path, 'configure');
+    }
+    fs.mount(path, mount);
+}
 /**
  * Configures ZenFS with `configuration`
  * @see Configuration
@@ -74,16 +94,15 @@ export async function configure(configuration) {
     config.syncImmediately = !configuration.onlySyncOnClose;
     if (configuration.addDevices) {
         const devfs = new DeviceFS();
-        devfs.createDevice('/null', nullDevice);
-        devfs.createDevice('/zero', zeroDevice);
-        devfs.createDevice('/full', fullDevice);
-        devfs.createDevice('/random', randomDevice);
+        devfs.addDefaults();
         await devfs.ready();
-        fs.mount('/dev', devfs);
+        await mount('/dev', devfs);
     }
     if (!configuration.mounts) {
         return;
     }
+    const toMount = [];
+    let unmountRoot = false;
     for (const [point, mountConfig] of Object.entries(configuration.mounts)) {
         if (!point.startsWith('/')) {
             throw new ErrnoError(Errno.EINVAL, 'Mount points must have absolute paths');
@@ -91,7 +110,11 @@ export async function configure(configuration) {
         if (isBackendConfig(mountConfig)) {
             mountConfig.disableAsyncCache ?? (mountConfig.disableAsyncCache = configuration.disableAsyncCache || false);
         }
-        configuration.mounts[point] = await resolveMountConfig(mountConfig);
+        if (point == '/')
+            unmountRoot = true;
+        toMount.push([point, await resolveMountConfig(mountConfig)]);
     }
-    fs.mountObject(configuration.mounts);
+    if (unmountRoot)
+        fs.umount('/');
+    await Promise.all(toMount.map(([point, fs]) => mount(point, fs)));
 }

package/dist/credentials.d.ts

@@ -12,4 +12,7 @@ export interface Credentials {
     egid: number;
 }
 export declare const credentials: Credentials;
+/**
+ * @deprecated
+ */
 export declare const rootCredentials: Credentials;

package/dist/credentials.js

@@ -6,6 +6,9 @@ export const credentials = {
     euid: 0,
     egid: 0,
 };
+/**
+ * @deprecated
+ */
 export const rootCredentials = {
     uid: 0,
     gid: 0,

package/dist/devices.d.ts

@@ -8,9 +8,10 @@ import type { Ino } from './inode.js';
 /**
  * A device
  * @todo Maybe add major/minor number or some other device information, like a UUID?
- * @experimental
+ * @privateRemarks
+ * UUIDs were considered, however they don't make sense without an easy mechanism for persistance
  */
-export interface Device {
+export interface Device<TData = any> {
     /**
      * The device's driver
      */
@@ -19,34 +20,64 @@ export interface Device {
      * Which inode the device is assigned
      */
     ino: Ino;
+    /**
+     * Data associated with a device.
+     * This is meant to be used by device drivers.
+     * @experimental
+     */
+    data: TData;
+    /**
+     * Major device number
+     * @experimental
+     */
+    major: number;
+    /**
+     * Minor device number
+     * @experimental
+     */
+    minor: number;
 }
 /**
  * A device driver
- * @experimental
  */
-export interface DeviceDriver {
+export interface DeviceDriver<TData = any> {
     /**
      * The name of the device driver
      */
     name: string;
     /**
      * Whether the device is buffered (a "block" device) or unbuffered (a "character" device)
+     * @default false
      */
-    isBuffered: boolean;
+    isBuffered?: boolean;
+    /**
+     * Initializes a new device.
+     * @returns `Device.data`
+     * @experimental
+     */
+    init?(ino: Ino): {
+        data?: TData;
+        minor?: number;
+        major?: number;
+    };
     /**
      * Synchronously read from the device
+     * @group File operations
      */
     read(file: DeviceFile, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
      * Synchronously write to the device
+     * @group File operations
      */
     write(file: DeviceFile, buffer: Uint8Array, offset: number, length: number, position?: number): number;
     /**
      * Sync the device
+     * @group File operations
      */
     sync?(file: DeviceFile): void;
     /**
      * Close the device
+     * @group File operations
      */
     close?(file: DeviceFile): void;
 }
@@ -55,7 +86,6 @@ export interface DeviceDriver {
  * This class only does some simple things:
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
- * @experimental
  */
 export declare class DeviceFile extends File {
     fs: DeviceFS;
@@ -86,11 +116,18 @@ export declare class DeviceFile extends File {
     _setTypeSync(): void;
 }
 /**
- * @experimental
+ * A temporary file system that manages and interfaces with devices
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
-    protected readonly devices: Map<string, Device>;
-    createDevice(path: string, driver: DeviceDriver): Device;
+    protected readonly devices: Map<string, Device<any>>;
+    /**
+     * Creates a new device at `path` relative to the `DeviceFS` root.
+     */
+    createDevice<TData = any>(path: string, driver: DeviceDriver<TData>): Device<TData | Record<string, never>>;
+    /**
+     * Adds default devices
+     */
+    addDefaults(): void;
     constructor();
     rename(oldPath: string, newPath: string): Promise<void>;
     renameSync(oldPath: string, newPath: string): void;
@@ -150,9 +187,9 @@ export declare const randomDevice: DeviceDriver;
  * @experimental
  */
 declare const _default: {
-    null: DeviceDriver;
-    zero: DeviceDriver;
-    full: DeviceDriver;
-    random: DeviceDriver;
+    null: DeviceDriver<any>;
+    zero: DeviceDriver<any>;
+    full: DeviceDriver<any>;
+    random: DeviceDriver<any>;
 };
 export default _default;

package/dist/devices.js

@@ -1,3 +1,6 @@
+/*
+This is a great resource: https://www.kernel.org/doc/html/latest/admin-guide/devices.html
+*/
 var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
     if (value !== null && value !== void 0) {
         if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
@@ -57,7 +60,6 @@ import { basename, dirname } from './emulation/path.js';
  * This class only does some simple things:
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
- * @experimental
  */
 export class DeviceFile extends File {
     constructor(fs, path, device) {
@@ -142,9 +144,12 @@ export class DeviceFile extends File {
     }
 }
 /**
- * @experimental
+ * A temporary file system that manages and interfaces with devices
  */
 export class DeviceFS extends StoreFS {
+    /**
+     * Creates a new device at `path` relative to the `DeviceFS` root.
+     */
     createDevice(path, driver) {
         if (this.existsSync(path)) {
             throw ErrnoError.With('EEXIST', path, 'mknod');
@@ -155,10 +160,23 @@ export class DeviceFS extends StoreFS {
         const dev = {
             driver,
             ino,
+            data: {},
+            minor: 0,
+            major: 0,
+            ...driver.init?.(ino),
         };
         this.devices.set(path, dev);
         return dev;
     }
+    /**
+     * Adds default devices
+     */
+    addDefaults() {
+        this.createDevice('/null', nullDevice);
+        this.createDevice('/zero', zeroDevice);
+        this.createDevice('/full', fullDevice);
+        this.createDevice('/random', randomDevice);
+    }
     constructor() {
         super(new InMemoryStore('devfs'));
         this.devices = new Map();
@@ -332,7 +350,9 @@ function defaultWrite(file, buffer, offset, length) {
  */
 export const nullDevice = {
     name: 'null',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 3 };
+    },
     read() {
         return 0;
     },
@@ -350,7 +370,9 @@ export const nullDevice = {
  */
 export const zeroDevice = {
     name: 'zero',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 5 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {
@@ -369,7 +391,9 @@ export const zeroDevice = {
  */
 export const fullDevice = {
     name: 'full',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 7 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {
@@ -390,7 +414,9 @@ export const fullDevice = {
  */
 export const randomDevice = {
     name: 'random',
-    isBuffered: false,
+    init() {
+        return { major: 1, minor: 8 };
+    },
     read(file, buffer, offset = 0, length = buffer.byteLength) {
         const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         for (let i = offset; i < offset + length; i++) {

package/dist/emulation/promises.js

@@ -53,11 +53,11 @@ import '../polyfills.js';
 import { BigIntStats } from '../stats.js';
 import { decodeUTF8, normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
 import * as cache from './cache.js';
+import { config } from './config.js';
 import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { _statfs, fd2file, fdMap, file2fd, fixError, mounts, resolveMount } from './shared.js';
-import { config } from './config.js';
+import { _statfs, fd2file, fdMap, file2fd, fixError, resolveMount } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
 import { FSWatcher, emitChange } from './watchers.js';
 export * as constants from './constants.js';
@@ -585,7 +585,7 @@ export async function rmdir(path) {
     try {
         const stats = await (cache.getStats(path) || fs.stat(resolved));
         if (!stats) {
-            throw ErrnoError.With('ENOENT', path, 'readdir');
+            throw ErrnoError.With('ENOENT', path, 'rmdir');
         }
         if (!stats.isDirectory()) {
             throw ErrnoError.With('ENOTDIR', resolved, 'rmdir');
@@ -655,16 +655,6 @@ export async function readdir(path, options) {
         throw ErrnoError.With('ENOTDIR', path, 'readdir');
     }
     const entries = await fs.readdir(resolved).catch(handleError);
-    for (const point of mounts.keys()) {
-        if (point.startsWith(path)) {
-            const entry = point.slice(path.length);
-            if (entry.includes('/') || entry.length == 0) {
-                // ignore FSs mounted in subdirectories and any FS mounted to `path`.
-                continue;
-            }
-            entries.push(entry);
-        }
-    }
     const values = [];
     const addEntry = async (entry) => {
         let entryStats;

package/dist/emulation/shared.d.ts

@@ -21,7 +21,7 @@ export declare function mount(mountPoint: string, fs: FileSystem): void;
  */
 export declare function umount(mountPoint: string): void;
 /**
- * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root
  */
 export declare function resolveMount(path: string): {
     fs: FileSystem;
@@ -38,6 +38,9 @@ export declare function fixPaths(text: string, paths: Record<string, string>): s
  * @hidden
  */
 export declare function fixError<E extends ErrnoError>(e: E, paths: Record<string, string>): E;
+/**
+ * @deprecated
+ */
 export declare function mountObject(mounts: MountObject): void;
 /**
  * @hidden

package/dist/emulation/shared.js

@@ -43,7 +43,7 @@ export function mount(mountPoint, fs) {
  */
 export function umount(mountPoint) {
     if (mountPoint[0] !== '/') {
-        mountPoint = `/${mountPoint}`;
+        mountPoint = '/' + mountPoint;
     }
     mountPoint = resolve(mountPoint);
     if (!mounts.has(mountPoint)) {
@@ -52,11 +52,10 @@ export function umount(mountPoint) {
     mounts.delete(mountPoint);
 }
 /**
- * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ * Gets the internal `FileSystem` for the path, then returns it along with the path relative to the FS' root
  */
 export function resolveMount(path) {
     path = normalizePath(path);
-    // Maybe do something for devices here
     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.
@@ -91,6 +90,9 @@ export function fixError(e, paths) {
     e.message = fixPaths(e.message, paths);
     return e;
 }
+/**
+ * @deprecated
+ */
 export function mountObject(mounts) {
     if ('/' in mounts) {
         umount('/');

package/dist/emulation/sync.js

@@ -50,13 +50,13 @@ import { Errno, ErrnoError } from '../error.js';
 import { flagToMode, isAppendable, isExclusive, isReadable, isTruncating, isWriteable, parseFlag } from '../file.js';
 import { BigIntStats } from '../stats.js';
 import { decodeUTF8, normalizeMode, normalizeOptions, normalizePath, normalizeTime } from '../utils.js';
+import * as cache from './cache.js';
+import { config } from './config.js';
 import * as constants from './constants.js';
 import { Dir, Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { _statfs, fd2file, fdMap, file2fd, fixError, mounts, resolveMount } from './shared.js';
-import { config } from './config.js';
+import { _statfs, fd2file, fdMap, file2fd, fixError, resolveMount } from './shared.js';
 import { emitChange } from './watchers.js';
-import * as cache from './cache.js';
 export function renameSync(oldPath, newPath) {
     oldPath = normalizePath(oldPath);
     newPath = normalizePath(newPath);
@@ -459,17 +459,6 @@ export function readdirSync(path, options) {
     catch (e) {
         throw fixError(e, { [resolved]: path });
     }
-    for (const mount of mounts.keys()) {
-        if (!mount.startsWith(path)) {
-            continue;
-        }
-        const entry = mount.slice(path.length);
-        if (entry.includes('/') || entry.length == 0) {
-            // ignore FSs mounted in subdirectories and any FS mounted to `path`.
-            continue;
-        }
-        entries.push(entry);
-    }
     // Iterate over entries and handle recursive case if needed
     const values = [];
     for (const entry of entries) {

package/dist/mixins/async.js

@@ -90,8 +90,8 @@ export function Async(FS) {
                 const sync = this._sync['store'].transaction();
                 const async = this['store'].transaction();
                 const promises = [];
-                for (const key of sync.keysSync()) {
-                    promises.push(async.set(key, sync.getSync(key)));
+                for (const key of await async.keys()) {
+                    promises.push(async.get(key).then(data => sync.setSync(key, data)));
                 }
                 await Promise.all(promises);
                 this._isInitialized = true;