@zenfs/core 0.3.4 → 0.4.0

package/dist/FileIndex.d.ts

@@ -211,10 +211,15 @@ declare const SyncFileIndexFS_base: (abstract new (...args: any[]) => {
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }) & (abstract new (index: ListingTree) => FileIndexFS<unknown>);
 export declare abstract class SyncFileIndexFS<TIndex> extends SyncFileIndexFS_base {
+    _index: FileIndex<TIndex>;
     protected statFileInode(inode: IndexFileInode<TIndex>, path: string): Promise<Stats>;
     protected openFileInode(inode: IndexFileInode<TIndex>, path: string, flag: FileFlag): Promise<NoSyncFile<this>>;
 }
 declare const AsyncFileIndexFS_base: (abstract new (...args: any[]) => {
+    /**
+     * Returns the inode for the indicated item, or null if it does not exist.
+     * @param path Name of item in this directory.
+     */
     metadata(): import("./filesystem.js").FileSystemMetadata;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     statSync(path: string, cred: Cred): Stats;
@@ -228,6 +233,7 @@ declare const AsyncFileIndexFS_base: (abstract new (...args: any[]) => {
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }) & (abstract new (index: ListingTree) => FileIndexFS<unknown>);
 export declare abstract class AsyncFileIndexFS<TIndex> extends AsyncFileIndexFS_base {
+    _index: FileIndex<TIndex>;
     protected statFileInodeSync(): Stats;
     protected openFileInodeSync(): NoSyncFile<this>;
 }

package/dist/FileIndex.js

@@ -40,7 +40,7 @@ export class FileIndex {
                 }
                 else {
                     // This inode doesn't have correct size information, noted with -1.
-                    inode = new IndexFileInode(new Stats(FileType.FILE, -1, 0o555));
+                    inode = new IndexFileInode(new Stats({ mode: FileType.FILE | 0o555 }));
                 }
                 if (!parent) {
                     continue;
@@ -219,7 +219,7 @@ export class IndexFileInode extends IndexInode {
         return false;
     }
     toStats() {
-        return new Stats(FileType.FILE, 4096, 0o666);
+        return new Stats({ mode: FileType.FILE | 0o666, size: 4096 });
     }
 }
 /**
@@ -244,7 +244,7 @@ export class IndexDirInode extends IndexInode {
      * @todo Should probably remove this at some point. This isn't the responsibility of the FileIndex.
      */
     get stats() {
-        return new Stats(FileType.DIRECTORY, 4096, 0o555);
+        return new Stats({ mode: FileType.DIRECTORY | 0o555, size: 4096 });
     }
     /**
      * Alias of getStats()

package/dist/backends/AsyncMirror.d.ts

@@ -1,12 +1,13 @@
 import { FileSystem, FileSystemMetadata } from '../filesystem.js';
 import { File, FileFlag, PreloadFile } from '../file.js';
-import { Stats } from '../stats.js';
+import type { Stats } from '../stats.js';
 import { Cred } from '../cred.js';
 import type { Backend } from './backend.js';
 /**
  * We define our own file to interpose on syncSync() for mirroring purposes.
+ * @internal
  */
-declare class MirrorFile extends PreloadFile<AsyncMirrorFS> {
+export declare class MirrorFile extends PreloadFile<AsyncMirrorFS> {
     constructor(fs: AsyncMirrorFS, path: string, flag: FileFlag, stat: Stats, data: Uint8Array);
     sync(): Promise<void>;
     syncSync(): void;
@@ -41,9 +42,6 @@ declare const AsyncMirrorFS_base: (abstract new (...args: any[]) => {
     link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    /**
-     * Queue of pending asynchronous operations.
-     */
     statSync(path: string, cred: Cred): Stats;
     openFileSync(path: string, flag: FileFlag, cred: Cred): File;
     createFileSync(path: string, flag: FileFlag, mode: number, cred: Cred): File;

package/dist/backends/AsyncMirror.js

@@ -5,8 +5,9 @@ import { join } from '../emulation/path.js';
 import { Cred } from '../cred.js';
 /**
  * We define our own file to interpose on syncSync() for mirroring purposes.
+ * @internal
  */
-class MirrorFile extends PreloadFile {
+export class MirrorFile extends PreloadFile {
     constructor(fs, path, flag, stat, data) {
         super(fs, path, flag, stat, data);
     }
@@ -153,8 +154,8 @@ export class AsyncMirrorFS extends Sync(FileSystem) {
      * @internal
      */
     async crossCopyFile(p, mode) {
-        const asyncFile = await this._async.openFile(p, FileFlag.FromString('r'), Cred.Root);
-        const syncFile = this._sync.createFileSync(p, FileFlag.FromString('w'), mode, Cred.Root);
+        const asyncFile = await this._async.openFile(p, FileFlag.Get('r'), Cred.Root);
+        const syncFile = this._sync.createFileSync(p, FileFlag.Get('w'), mode, Cred.Root);
         try {
             const { size } = await asyncFile.stat();
             const buffer = new Uint8Array(size);
@@ -230,9 +231,9 @@ export const AsyncMirror = {
         sync: {
             type: 'object',
             description: 'The synchronous file system to mirror the asynchronous file system to.',
-            validator: async (v) => {
-                if (!v?.metadata().synchronous) {
-                    throw new ApiError(ErrorCode.EINVAL, `'sync' option must be a file system that supports synchronous operations`);
+            validator: async (backend) => {
+                if ('metadata' in backend && !backend.metadata().synchronous) {
+                    throw new ApiError(ErrorCode.EINVAL, '"sync" option must be a file system that supports synchronous operations');
                 }
             },
         },

package/dist/backends/AsyncStore.d.ts

@@ -1,8 +1,8 @@
-import { Cred } from '../cred.js';
+import type { Cred } from '../cred.js';
 import { PreloadFile, File, FileFlag } from '../file.js';
 import { FileSystem, type FileSystemMetadata } from '../filesystem.js';
 import { type Ino } from '../inode.js';
-import { Stats } from '../stats.js';
+import { type Stats } from '../stats.js';
 /**
  * Represents an *asynchronous* key-value store.
  */
@@ -62,6 +62,10 @@ export interface AsyncRWTransaction extends AsyncROTransaction {
      */
     abort(): Promise<void>;
 }
+/**
+ * Async preload file for usage with AsyncStore
+ * @internal
+ */
 export declare class AsyncFile extends PreloadFile<AsyncStoreFS> {
     constructor(_fs: AsyncStoreFS, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
     sync(): Promise<void>;
@@ -93,8 +97,9 @@ declare const AsyncStoreFS_base: (abstract new (...args: any[]) => {
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }) & typeof FileSystem;
 /**
- * An "Asynchronous key-value file system". Stores data to/retrieves data from
- * an underlying asynchronous key-value store.
+ * An asynchronous file system which uses an async store to store its data.
+ * @see AsyncStore
+ * @internal
  */
 export declare class AsyncStoreFS extends AsyncStoreFS_base {
     protected store: AsyncStore;

package/dist/backends/AsyncStore.js

@@ -44,6 +44,10 @@ class LRUCache {
         this.cache = [];
     }
 }
+/**
+ * Async preload file for usage with AsyncStore
+ * @internal
+ */
 export class AsyncFile extends PreloadFile {
     constructor(_fs, _path, _flag, _stat, contents) {
         super(_fs, _path, _flag, _stat, contents);
@@ -66,8 +70,9 @@ export class AsyncFile extends PreloadFile {
     }
 }
 /**
- * An "Asynchronous key-value file system". Stores data to/retrieves data from
- * an underlying asynchronous key-value store.
+ * An asynchronous file system which uses an async store to store its data.
+ * @see AsyncStore
+ * @internal
  */
 export class AsyncStoreFS extends Async(FileSystem) {
     ready() {

package/dist/backends/Locked.d.ts

@@ -1,8 +1,7 @@
-import { FileSystem, FileSystemMetadata } from '../filesystem.js';
-import { FileFlag } from '../file.js';
-import { Stats } from '../stats.js';
-import { File } from '../file.js';
-import { Cred } from '../cred.js';
+import type { Cred } from '../cred.js';
+import type { File, FileFlag } from '../file.js';
+import type { FileSystem, FileSystemMetadata } from '../filesystem.js';
+import type { Stats } from '../stats.js';
 /**
  * This class serializes access to an underlying async filesystem.
  * For example, on an OverlayFS instance with an async lower
@@ -11,11 +10,12 @@ import { Cred } from '../cred.js';
  * are not executed in a single atomic step.  OverlayFS uses this
  * LockedFS to avoid having to reason about the correctness of
  * multiple requests interleaving.
+ * @internal
  */
-export declare class LockedFS<T extends FileSystem> implements FileSystem {
-    readonly fs: T;
+export declare class LockedFS<FS extends FileSystem> implements FileSystem {
+    readonly fs: FS;
     private _mu;
-    constructor(fs: T);
+    constructor(fs: FS);
     ready(): Promise<this>;
     metadata(): FileSystemMetadata;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;

package/dist/backends/Locked.js

@@ -1,4 +1,4 @@
-import Mutex from '../mutex.js';
+import { Mutex } from '../mutex.js';
 /**
  * This class serializes access to an underlying async filesystem.
  * For example, on an OverlayFS instance with an async lower
@@ -7,6 +7,7 @@ import Mutex from '../mutex.js';
  * are not executed in a single atomic step.  OverlayFS uses this
  * LockedFS to avoid having to reason about the correctness of
  * multiple requests interleaving.
+ * @internal
  */
 export class LockedFS {
     constructor(fs) {

package/dist/backends/Overlay.d.ts

@@ -1,9 +1,20 @@
 import { FileSystem, FileSystemMetadata } from '../filesystem.js';
-import { File, FileFlag } from '../file.js';
+import { File, FileFlag, PreloadFile } from '../file.js';
 import { Stats } from '../stats.js';
 import { LockedFS } from './Locked.js';
 import { Cred } from '../cred.js';
 import type { Backend } from './backend.js';
+/**
+ * Overlays a RO file to make it writable.
+ * @internal
+ */
+export declare class OverlayFile extends PreloadFile<UnlockedOverlayFS> implements File {
+    constructor(fs: UnlockedOverlayFS, path: string, flag: FileFlag, stats: Stats, data: Uint8Array);
+    sync(): Promise<void>;
+    syncSync(): void;
+    close(): Promise<void>;
+    closeSync(): void;
+}
 /**
  * Configuration options for OverlayFS instances.
  */
@@ -95,6 +106,7 @@ export declare class UnlockedOverlayFS extends FileSystem {
  * OverlayFS makes a read-only filesystem writable by storing writes on a second,
  * writable file system. Deletes are persisted via metadata stored on the writable
  * file system.
+ * @internal
  */
 export declare class OverlayFS extends LockedFS<UnlockedOverlayFS> {
     ready(): Promise<this>;

package/dist/backends/Overlay.js

@@ -12,8 +12,9 @@ import { decode, encode } from '../utils.js';
 const deletionLogPath = '/.deleted';
 /**
  * Overlays a RO file to make it writable.
+ * @internal
  */
-class OverlayFile extends PreloadFile {
+export class OverlayFile extends PreloadFile {
     constructor(fs, path, flag, stats, data) {
         super(fs, path, flag, stats, data);
     }
@@ -103,7 +104,7 @@ export class UnlockedOverlayFS extends FileSystem {
         }
         // Read deletion log, process into metadata.
         try {
-            const file = await this._writable.openFile(deletionLogPath, FileFlag.FromString('r'), Cred.Root);
+            const file = await this._writable.openFile(deletionLogPath, FileFlag.Get('r'), Cred.Root);
             const { size } = await file.stat();
             const { buffer } = await file.read(new Uint8Array(size));
             this._deleteLog = decode(buffer);
@@ -159,9 +160,8 @@ export class UnlockedOverlayFS extends FileSystem {
             if (this._deletedFiles.has(p)) {
                 throw ApiError.ENOENT(p);
             }
-            const oldStat = Stats.clone(await this._readable.stat(p, cred));
-            // Make the oldStat's mode writable. Preserve the topmost part of the
-            // mode, which specifies if it is a file or a directory.
+            const oldStat = new Stats(await this._readable.stat(p, cred));
+            // Make the oldStat's mode writable. Preserve the topmost part of the mode, which specifies the type
             oldStat.mode |= 0o222;
             return oldStat;
         }
@@ -175,9 +175,8 @@ export class UnlockedOverlayFS extends FileSystem {
             if (this._deletedFiles.has(p)) {
                 throw ApiError.ENOENT(p);
             }
-            const oldStat = Stats.clone(this._readable.statSync(p, cred));
-            // Make the oldStat's mode writable. Preserve the topmost part of the
-            // mode, which specifies if it is a file or a directory.
+            const oldStat = new Stats(this._readable.statSync(p, cred));
+            // Make the oldStat's mode writable. Preserve the topmost part of the mode, which specifies the type.
             oldStat.mode |= 0o222;
             return oldStat;
         }
@@ -187,8 +186,8 @@ export class UnlockedOverlayFS extends FileSystem {
             return this._writable.openFile(path, flag, cred);
         }
         // Create an OverlayFile.
-        const file = await this._readable.openFile(path, FileFlag.FromString('r'), cred);
-        const stats = Stats.clone(await file.stat());
+        const file = await this._readable.openFile(path, FileFlag.Get('r'), cred);
+        const stats = new Stats(await file.stat());
         const { buffer } = await file.read(new Uint8Array(stats.size));
         return new OverlayFile(this, path, flag, stats, buffer);
     }
@@ -197,7 +196,7 @@ export class UnlockedOverlayFS extends FileSystem {
             return this._writable.openFileSync(path, flag, cred);
         }
         // Create an OverlayFile.
-        const file = this._readable.openFileSync(path, FileFlag.FromString('r'), cred);
+        const file = this._readable.openFileSync(path, FileFlag.Get('r'), cred);
         const stats = Stats.clone(file.statSync());
         const data = new Uint8Array(stats.size);
         file.readSync(data);
@@ -368,7 +367,7 @@ export class UnlockedOverlayFS extends FileSystem {
             return;
         }
         this._deleteLogUpdatePending = true;
-        const log = await this._writable.openFile(deletionLogPath, FileFlag.FromString('w'), cred);
+        const log = await this._writable.openFile(deletionLogPath, FileFlag.Get('w'), cred);
         try {
             await log.write(encode(this._deleteLog));
             if (this._deleteLogUpdateNeeded) {
@@ -470,10 +469,10 @@ export class UnlockedOverlayFS extends FileSystem {
             return;
         }
         const data = new Uint8Array(stats.size);
-        const readable = this._readable.openFileSync(p, FileFlag.FromString('r'), cred);
+        const readable = this._readable.openFileSync(p, FileFlag.Get('r'), cred);
         readable.readSync(data);
         readable.closeSync();
-        const writable = this._writable.openFileSync(p, FileFlag.FromString('w'), cred);
+        const writable = this._writable.openFileSync(p, FileFlag.Get('w'), cred);
         writable.writeSync(data);
         writable.closeSync();
     }
@@ -484,10 +483,10 @@ export class UnlockedOverlayFS extends FileSystem {
             return;
         }
         const data = new Uint8Array(stats.size);
-        const readable = await this._readable.openFile(p, FileFlag.FromString('r'), cred);
+        const readable = await this._readable.openFile(p, FileFlag.Get('r'), cred);
         await readable.read(data);
         await readable.close();
-        const writable = await this._writable.openFile(p, FileFlag.FromString('w'), cred);
+        const writable = await this._writable.openFile(p, FileFlag.Get('w'), cred);
         await writable.write(data);
         await writable.close();
     }
@@ -496,6 +495,7 @@ export class UnlockedOverlayFS extends FileSystem {
  * OverlayFS makes a read-only filesystem writable by storing writes on a second,
  * writable file system. Deletes are persisted via metadata stored on the writable
  * file system.
+ * @internal
  */
 export class OverlayFS extends LockedFS {
     async ready() {

package/dist/backends/SyncStore.d.ts

@@ -2,7 +2,7 @@ import { Cred } from '../cred.js';
 import { FileFlag, PreloadFile } from '../file.js';
 import { type FileSystemMetadata, FileSystem } from '../filesystem.js';
 import { type Ino, Inode } from '../inode.js';
-import { Stats, FileType } from '../stats.js';
+import { type Stats, FileType } from '../stats.js';
 /**
  * Represents a *synchronous* key-value store.
  */
@@ -112,6 +112,10 @@ export interface SyncStoreOptions {
      */
     store: SyncStore;
 }
+/**
+ * File backend by a SyncStoreFS
+ * @internal
+ */
 export declare class SyncStoreFile extends PreloadFile<SyncStoreFS> {
     constructor(_fs: SyncStoreFS, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
     sync(): Promise<void>;
@@ -146,13 +150,12 @@ declare const SyncStoreFS_base: (abstract new (...args: any[]) => {
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }) & typeof FileSystem;
 /**
- * A "Synchronous key-value file system". Stores data to/retrieves data from an
- * underlying key-value store.
+ * A synchronous key-value file system. Uses a SyncStore to store the data.
  *
- * We use a unique ID for each node in the file system. The root node has a
- * fixed ID.
+ * We use a unique ID for each node in the file system. The root node has a fixed ID.
  * @todo Introduce Node ID caching.
  * @todo Check modes.
+ * @internal
  */
 export declare class SyncStoreFS extends SyncStoreFS_base {
     protected store: SyncStore;

package/dist/backends/SyncStore.js

@@ -76,6 +76,10 @@ export class SimpleSyncRWTransaction {
         }
     }
 }
+/**
+ * File backend by a SyncStoreFS
+ * @internal
+ */
 export class SyncStoreFile extends PreloadFile {
     constructor(_fs, _path, _flag, _stat, contents) {
         super(_fs, _path, _flag, _stat, contents);
@@ -97,13 +101,12 @@ export class SyncStoreFile extends PreloadFile {
     }
 }
 /**
- * A "Synchronous key-value file system". Stores data to/retrieves data from an
- * underlying key-value store.
+ * A synchronous key-value file system. Uses a SyncStore to store the data.
  *
- * We use a unique ID for each node in the file system. The root node has a
- * fixed ID.
+ * We use a unique ID for each node in the file system. The root node has a fixed ID.
  * @todo Introduce Node ID caching.
  * @todo Check modes.
+ * @internal
  */
 export class SyncStoreFS extends Sync(FileSystem) {
     constructor(options) {
@@ -347,7 +350,8 @@ export class SyncStoreFS extends Sync(FileSystem) {
         if (!data) {
             throw ApiError.ENOENT(p);
         }
-        return new Inode(data.buffer);
+        const inode = new Inode(data.buffer);
+        return inode;
     }
     /**
      * Given the Inode of a directory, retrieves the corresponding directory listing.

package/dist/backends/backend.js

@@ -16,7 +16,7 @@ export async function checkOptions(backend, opts) {
     }
     // Check for required options.
     for (const [optName, opt] of Object.entries(backend.options)) {
-        const providedValue = opts && opt;
+        const providedValue = opts?.[optName];
         if (providedValue === undefined || providedValue === null) {
             if (!opt.required) {
                 continue;
@@ -36,7 +36,7 @@ export async function checkOptions(backend, opts) {
         // Option provided, check type.
         const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
         if (!typeMatches) {
-            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : opt.type}, but received ${typeof providedValue}\nOption description: ${opt.description}`);
+            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : opt.type}, but received ${typeof providedValue}`);
         }
         if (opt.validator) {
             await opt.validator(providedValue);
@@ -60,13 +60,13 @@ export function isBackendConfig(arg) {
  * @param config A BackendConfig object.
  */
 export async function resolveBackendConfig(options) {
-    const { backend } = options;
-    if (!backend) {
-        throw new ApiError(ErrorCode.EPERM, 'Missing backend');
-    }
     if (typeof options !== 'object' || options == null) {
         throw new ApiError(ErrorCode.EINVAL, 'Invalid options on configuration object.');
     }
+    const { backend } = options;
+    if (!isBackend(backend)) {
+        throw new ApiError(ErrorCode.EINVAL, 'Missing or invalid backend');
+    }
     const props = Object.keys(options).filter(k => k != 'backend');
     for (const prop of props) {
         let option = options[prop];
@@ -77,8 +77,8 @@ export async function resolveBackendConfig(options) {
             options[prop] = await resolveBackendConfig(option);
         }
     }
-    if (!backend) {
-        throw new ApiError(ErrorCode.EPERM, `Backend "${backend}" is not available`);
+    if (!backend.isAvailable()) {
+        throw new ApiError(ErrorCode.EPERM, 'Backend not available: ' + backend);
     }
     checkOptions(backend, options);
     const fs = backend.create(options);