@zenfs/core 0.5.12 → 0.7.0

package/dist/config.d.ts

@@ -1,23 +1,27 @@
-import type { Backend, BackendConfig } from './backends/backend.js';
+import type { Backend, BackendConfiguration } from './backends/backend.js';
 import { FileSystem } from './filesystem.js';
 /**
- * Initializes ZenFS with the given file systems.
+ * Configuration for a specific mount point
  */
-export declare function initialize(mounts: {
-    [point: string]: FileSystem;
-}, uid?: number, gid?: number): void;
+export type MountConfiguration<FS extends FileSystem = FileSystem> = FS | BackendConfiguration<FS> | Backend<FS>;
 /**
- * Defines a mapping of mount points to their configurations
+ * Retrieve a file system with the given configuration.
+ * @param config A BackendConfig object.
  */
-export interface ConfigMapping {
-    [mountPoint: string]: FileSystem | BackendConfig | Backend;
-}
+export declare function resolveMountConfig<FS extends FileSystem>(config: MountConfiguration<FS>, _depth?: number): Promise<FS>;
 /**
- * A configuration for ZenFS
+ *A mapping of mount points to their configurations
  */
-export type Configuration = FileSystem | BackendConfig | ConfigMapping;
+export type MappingConfiguration = Partial<{
+    uid: number;
+    gid: number;
+}> & Record<string, FileSystem | BackendConfiguration | Backend>;
+/**
+ * Configuration for the file systems
+ */
+export type Configuration = MountConfiguration | MappingConfiguration;
 /**
  * Creates filesystems with the given configuration, and initializes ZenFS with it.
- * See the Configuration type for more info on the configuration object.
+ * @see Configuration for more info on the configuration object.
  */
 export declare function configure(config: Configuration): Promise<void>;

package/dist/config.js

@@ -1,35 +1,66 @@
-import { isBackend, resolveBackend } from './backends/backend.js';
+import { ApiError, ErrorCode } from './ApiError.js';
+import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
 import * as fs from './emulation/index.js';
 import { setCred } from './emulation/shared.js';
 import { FileSystem } from './filesystem.js';
+function isMountConfig(arg) {
+    return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
+}
 /**
- * Initializes ZenFS with the given file systems.
+ * Retrieve a file system with the given configuration.
+ * @param config A BackendConfig object.
  */
-export function initialize(mounts, uid = 0, gid = 0) {
-    setCred({ uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
-    fs.initialize(mounts);
+export async function resolveMountConfig(config, _depth = 0) {
+    if (typeof config !== 'object' || config == null) {
+        throw new ApiError(ErrorCode.EINVAL, 'Invalid options on mount configuration');
+    }
+    if (!isMountConfig(config)) {
+        throw new ApiError(ErrorCode.EINVAL, 'Invalid mount configuration');
+    }
+    if (config instanceof FileSystem) {
+        return config;
+    }
+    if (isBackend(config)) {
+        config = { backend: config };
+    }
+    for (const [key, value] of Object.entries(config)) {
+        if (key == 'backend') {
+            continue;
+        }
+        if (!isMountConfig(value)) {
+            continue;
+        }
+        if (_depth > 10) {
+            throw new ApiError(ErrorCode.EINVAL, 'Invalid configuration, too deep and possibly infinite');
+        }
+        config[key] = await resolveMountConfig(value, ++_depth);
+    }
+    const { backend } = config;
+    if (!(await backend.isAvailable())) {
+        throw new ApiError(ErrorCode.EPERM, 'Backend not available: ' + backend);
+    }
+    checkOptions(backend, config);
+    const mount = backend.create(config);
+    await mount.ready();
+    return mount;
 }
 /**
  * Creates filesystems with the given configuration, and initializes ZenFS with it.
- * See the Configuration type for more info on the configuration object.
+ * @see Configuration for more info on the configuration object.
  */
 export async function configure(config) {
-    if ('backend' in config || config instanceof FileSystem) {
+    const uid = 'uid' in config ? +config.uid || 0 : 0;
+    const gid = 'gid' in config ? +config.gid || 0 : 0;
+    if (isMountConfig(config)) {
         // single FS
         config = { '/': config };
     }
-    for (let [point, value] of Object.entries(config)) {
-        if (typeof value == 'number') {
-            //should never happen
+    for (const [point, value] of Object.entries(config)) {
+        if (point == 'uid' || point == 'gid' || typeof value == 'number') {
             continue;
         }
-        if (value instanceof FileSystem) {
-            continue;
-        }
-        if (isBackend(value)) {
-            value = { backend: value };
-        }
-        config[point] = await resolveBackend(value);
+        config[point] = await resolveMountConfig(value);
     }
-    initialize(config);
+    fs.mountMapping(config);
+    setCred({ uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
 }

package/dist/emulation/index.d.ts

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

package/dist/emulation/index.js

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

package/dist/emulation/promises.js

@@ -5,7 +5,7 @@ import { BigIntStats, FileType } from '../stats.js';
 import { F_OK } from './constants.js';
 import { Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { cred, fd2file, fdMap, fixError, getFdForFile, mounts, normalizeMode, normalizeOptions, normalizePath, normalizeTime, resolveFS } from './shared.js';
+import { cred, fd2file, fdMap, fixError, getFdForFile, mounts, normalizeMode, normalizeOptions, normalizePath, normalizeTime, resolveMount } from './shared.js';
 export * as constants from './constants.js';
 export class FileHandle {
     constructor(
@@ -228,7 +228,7 @@ export class FileHandle {
 async function doOp(...[name, resolveSymlinks, rawPath, ...args]) {
     rawPath = normalizePath(rawPath);
     const _path = resolveSymlinks && (await exists(rawPath)) ? await realpath(rawPath) : rawPath;
-    const { fs, path } = resolveFS(_path);
+    const { fs, path } = resolveMount(_path);
     try {
         // @ts-expect-error 2556 (since ...args is not correctly picked up as being a tuple)
         return fs[name](path, ...args);
@@ -246,8 +246,8 @@ async function doOp(...[name, resolveSymlinks, rawPath, ...args]) {
 export async function rename(oldPath, newPath) {
     oldPath = normalizePath(oldPath);
     newPath = normalizePath(newPath);
-    const src = resolveFS(oldPath);
-    const dst = resolveFS(newPath);
+    const src = resolveMount(oldPath);
+    const dst = resolveMount(newPath);
     try {
         if (src.mountPoint == dst.mountPoint) {
             await src.fs.rename(src.path, dst.path, cred);
@@ -267,7 +267,7 @@ rename;
  */
 export async function exists(_path) {
     try {
-        const { fs, path } = resolveFS(await realpath(_path));
+        const { fs, path } = resolveMount(await realpath(_path));
         return await fs.exists(path, cred);
     }
     catch (e) {
@@ -395,7 +395,7 @@ async function _readFile(fname, flag, resolveSymlinks) {
     }
 }
 export async function readFile(filename, _options) {
-    const options = normalizeOptions(_options, null, 'r', null);
+    const options = normalizeOptions(_options, null, 'r', 0);
     const flag = parseFlag(options.flag);
     if (!isReadable(flag)) {
         throw new ApiError(ErrorCode.EINVAL, 'Flag passed must allow for reading.');
@@ -633,7 +633,7 @@ export async function realpath(path, options) {
     path = normalizePath(path);
     const { base, dir } = parse(path);
     const lpath = join(dir == '/' ? '/' : await realpath(dir), base);
-    const { fs, path: resolvedPath, mountPoint } = resolveFS(lpath);
+    const { fs, path: resolvedPath, mountPoint } = resolveMount(lpath);
     try {
         const stats = await fs.stat(resolvedPath, cred);
         if (!stats.isSymbolicLink()) {

package/dist/emulation/shared.d.ts

@@ -70,7 +70,7 @@ 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
  */
-export declare function resolveFS(path: string): {
+export declare function resolveMount(path: string): {
     fs: FileSystem;
     path: string;
     mountPoint: string;
@@ -84,7 +84,7 @@ export declare function fixPaths(text: string, paths: {
 export declare function fixError<E extends Error>(e: E, paths: {
     [from: string]: string;
 }): E;
-export declare function initialize(mountMapping: MountMapping): void;
+export declare function mountMapping(mountMapping: MountMapping): void;
 /**
  * Types supports as path parameters.
  *

package/dist/emulation/shared.js

@@ -153,7 +153,7 @@ export function umount(mountPoint) {
 /**
  * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
  */
-export function resolveFS(path) {
+export function resolveMount(path) {
     path = normalizePath(path);
     const sortedMounts = [...mounts].sort((a, b) => (a[0].length > b[0].length ? -1 : 1)); // decending order of the string length
     for (const [mountPoint, fs] of sortedMounts) {
@@ -184,7 +184,7 @@ export function fixError(e, paths) {
     e.message = fixPaths(e.message, paths);
     return e;
 }
-export function initialize(mountMapping) {
+export function mountMapping(mountMapping) {
     if ('/' in mountMapping) {
         umount('/');
     }

package/dist/emulation/sync.js

@@ -4,10 +4,10 @@ import { ActionType, isAppendable, isReadable, isWriteable, parseFlag, pathExist
 import { BigIntStats, FileType } from '../stats.js';
 import { Dirent } from './dir.js';
 import { dirname, join, parse } from './path.js';
-import { cred, fd2file, fdMap, fixError, getFdForFile, mounts, normalizeMode, normalizeOptions, normalizePath, normalizeTime, resolveFS } from './shared.js';
+import { cred, fd2file, fdMap, fixError, getFdForFile, mounts, normalizeMode, normalizeOptions, normalizePath, normalizeTime, resolveMount } from './shared.js';
 function doOp(...[name, resolveSymlinks, path, ...args]) {
     path = normalizePath(path);
-    const { fs, path: resolvedPath } = resolveFS(resolveSymlinks && existsSync(path) ? realpathSync(path) : path);
+    const { fs, path: resolvedPath } = resolveMount(resolveSymlinks && existsSync(path) ? realpathSync(path) : path);
     try {
         // @ts-expect-error 2556 (since ...args is not correctly picked up as being a tuple)
         return fs[name](resolvedPath, ...args);
@@ -24,8 +24,8 @@ function doOp(...[name, resolveSymlinks, path, ...args]) {
 export function renameSync(oldPath, newPath) {
     oldPath = normalizePath(oldPath);
     newPath = normalizePath(newPath);
-    const _old = resolveFS(oldPath);
-    const _new = resolveFS(newPath);
+    const _old = resolveMount(oldPath);
+    const _new = resolveMount(newPath);
     const paths = { [_old.path]: oldPath, [_new.path]: newPath };
     try {
         if (_old === _new) {
@@ -46,7 +46,7 @@ renameSync;
 export function existsSync(path) {
     path = normalizePath(path);
     try {
-        const { fs, path: resolvedPath } = resolveFS(realpathSync(path));
+        const { fs, path: resolvedPath } = resolveMount(realpathSync(path));
         return fs.existsSync(resolvedPath, cred);
     }
     catch (e) {
@@ -517,7 +517,7 @@ export function realpathSync(path, options) {
     path = normalizePath(path);
     const { base, dir } = parse(path);
     const lpath = join(dir == '/' ? '/' : realpathSync(dir), base);
-    const { fs, path: resolvedPath, mountPoint } = resolveFS(lpath);
+    const { fs, path: resolvedPath, mountPoint } = resolveMount(lpath);
     try {
         const stats = fs.statSync(resolvedPath, cred);
         if (!stats.isSymbolicLink()) {

package/dist/file.d.ts

@@ -187,12 +187,9 @@ export declare abstract class File {
  * An implementation of the File interface that operates on a file that is
  * completely in-memory. PreloadFiles are backed by a Uint8Array.
  *
- * This is also an abstract class, as it lacks an implementation of 'sync' and
- * 'close'. Each filesystem that wishes to use this file representation must
- * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
-export declare abstract class PreloadFile<FS extends FileSystem> extends File {
+export declare class PreloadFile<FS extends FileSystem> extends File {
     /**
      * The file system that created the file.
      */
@@ -246,6 +243,10 @@ export declare abstract class PreloadFile<FS extends FileSystem> extends File {
      * @param newPos new position
      */
     set position(newPos: number);
+    sync(): Promise<void>;
+    syncSync(): void;
+    close(): Promise<void>;
+    closeSync(): void;
     /**
      * Asynchronous `stat`.
      */
@@ -350,16 +351,6 @@ export declare abstract class PreloadFile<FS extends FileSystem> extends File {
     _setType(type: FileType): Promise<void>;
     _setTypeSync(type: FileType): void;
 }
-/**
- * For synchronous file systems
- */
-export declare class SyncFile<FS extends FileSystem> extends PreloadFile<FS> {
-    constructor(_fs: FS, _path: string, _flag: string, _stat: Stats, contents?: Uint8Array);
-    sync(): Promise<void>;
-    syncSync(): void;
-    close(): Promise<void>;
-    closeSync(): void;
-}
 /**
  * For the filesystems which do not sync to anything..
  */

package/dist/file.js

@@ -154,9 +154,6 @@ export class File {
  * An implementation of the File interface that operates on a file that is
  * completely in-memory. PreloadFiles are backed by a Uint8Array.
  *
- * This is also an abstract class, as it lacks an implementation of 'sync' and
- * 'close'. Each filesystem that wishes to use this file representation must
- * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
 export class PreloadFile extends File {
@@ -230,6 +227,26 @@ export class PreloadFile extends File {
     set position(newPos) {
         this._position = newPos;
     }
+    async sync() {
+        if (!this.isDirty()) {
+            return;
+        }
+        await this.fs.sync(this.path, this._buffer, this.stats);
+        this._dirty = false;
+    }
+    syncSync() {
+        if (!this.isDirty()) {
+            return;
+        }
+        this.fs.syncSync(this.path, this._buffer, this.stats);
+        this._dirty = false;
+    }
+    async close() {
+        await this.sync();
+    }
+    closeSync() {
+        this.syncSync();
+    }
     /**
      * Asynchronous `stat`.
      */
@@ -248,7 +265,7 @@ export class PreloadFile extends File {
      */
     truncate(len) {
         this.truncateSync(len);
-        if (isSynchronous(this.flag) && !this.fs.metadata().synchronous) {
+        if (isSynchronous(this.flag)) {
             return this.sync();
         }
     }
@@ -266,7 +283,7 @@ export class PreloadFile extends File {
             const buf = new Uint8Array(len - this._buffer.length);
             // Write will set stats.size for us.
             this.writeSync(buf, 0, buf.length, this._buffer.length);
-            if (isSynchronous(this.flag) && this.fs.metadata().synchronous) {
+            if (isSynchronous(this.flag)) {
                 this.syncSync();
             }
             return;
@@ -274,7 +291,7 @@ export class PreloadFile extends File {
         this.stats.size = len;
         // Truncate buffer to 'len'.
         this._buffer = this._buffer.subarray(0, len);
-        if (isSynchronous(this.flag) && this.fs.metadata().synchronous) {
+        if (isSynchronous(this.flag)) {
             this.syncSync();
         }
     }
@@ -445,29 +462,6 @@ export class PreloadFile extends File {
         this.syncSync();
     }
 }
-/**
- * For synchronous file systems
- */
-export class SyncFile extends PreloadFile {
-    constructor(_fs, _path, _flag, _stat, contents) {
-        super(_fs, _path, _flag, _stat, contents);
-    }
-    async sync() {
-        this.syncSync();
-    }
-    syncSync() {
-        if (this.isDirty()) {
-            this.fs.syncSync(this.path, this._buffer, this.stats);
-            this.resetDirty();
-        }
-    }
-    async close() {
-        this.closeSync();
-    }
-    closeSync() {
-        this.syncSync();
-    }
-}
 /**
  * For the filesystems which do not sync to anything..
  */

package/dist/filesystem.d.ts

@@ -1,7 +1,7 @@
 import { ApiError } from './ApiError.js';
 import type { Stats } from './stats.js';
-import type { File } from './file.js';
-import type { Cred } from './cred.js';
+import { type File } from './file.js';
+import { type Cred } from './cred.js';
 export type NoArgCallback = (e?: ApiError) => unknown;
 export type TwoArgCallback<T> = (e?: ApiError, rv?: T) => unknown;
 export type ThreeArgCallback<T, U> = (e?: ApiError, arg1?: T, arg2?: U) => unknown;
@@ -18,10 +18,6 @@ export interface FileSystemMetadata {
      * Wheter the FS is readonly or not
      */
     readonly: boolean;
-    /**
-     * Does the FS support synchronous operations
-     */
-    synchronous: boolean;
     /**
      * Does the FS support properties
      */
@@ -46,6 +42,9 @@ export interface FileSystemMetadata {
  * - All arguments are present. Any optional arguments at the Node API level have been passed in with their default values.
  */
 export declare abstract class FileSystem {
+    /**
+     * Get metadata about the current file syste,
+     */
     metadata(): FileSystemMetadata;
     constructor(options?: object);
     abstract ready(): Promise<this>;
@@ -178,8 +177,13 @@ export declare function Sync<T extends abstract new (...args: any[]) => FileSyst
 /**
  * @internal
  */
-declare abstract class AsyncFileSystem {
+declare abstract class AsyncFileSystem extends FileSystem {
+    /**
+     * @hidden
+     */
+    abstract _sync: FileSystem;
     metadata(): FileSystemMetadata;
+    ready(): Promise<this>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     statSync(path: string, cred: Cred): Stats;
     createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
@@ -191,11 +195,23 @@ declare abstract class AsyncFileSystem {
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
+/**
+ * Async() implements synchronous methods on an asynchronous file system
+ *
+ * Implementing classes must define a protected _sync property for the synchronous file system used as a cache.
+ * by:
+ *
+ * - Performing operations over the in-memory copy, while asynchronously pipelining them
+ *   to the backing store.
+ * - During application loading, the contents of the async file system can be reloaded into
+ *   the synchronous store, if desired.
+ *
+ */
 export declare function Async<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => AsyncFileSystem) & T;
 /**
  * @internal
  */
-declare abstract class ReadonlyFileSystem {
+declare abstract class ReadonlyFileSystem extends FileSystem {
     metadata(): FileSystemMetadata;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;