@zenfs/core 1.0.10 → 1.1.0

package/dist/backends/backend.d.ts

@@ -72,15 +72,13 @@ export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer T
  * @internal
  */
 export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
-/**
- * @internal
- */
+/** @internal */
 export declare function isBackend(arg: unknown): arg is Backend;
 /**
- * Checks that the given options object is valid for the file system options.
+ * Checks that `options` object is valid for the file system options.
  * @internal
  */
-export declare function checkOptions<T extends Backend>(backend: T, opts: Record<string, unknown>): Promise<void>;
+export declare function checkOptions<T extends Backend>(backend: T, options: Record<string, unknown>): Promise<void>;
 /**
  * Specifies a file system backend type and its options.
  *
@@ -91,8 +89,6 @@ export declare function checkOptions<T extends Backend>(backend: T, opts: Record
 export type BackendConfiguration<T extends Backend> = OptionsOf<T> & Partial<SharedConfig> & {
     backend: T;
 };
-/**
- * @internal
- */
+/** @internal */
 export declare function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T>;
 export {};

package/dist/backends/backend.js

@@ -1,22 +1,20 @@
 import { ErrnoError, Errno } from '../error.js';
 import { levenshtein } from '../utils.js';
-/**
- * @internal
- */
+/** @internal */
 export function isBackend(arg) {
     return arg != null && typeof arg == 'object' && 'isAvailable' in arg && typeof arg.isAvailable == 'function' && 'create' in arg && typeof arg.create == 'function';
 }
 /**
- * Checks that the given options object is valid for the file system options.
+ * Checks that `options` object is valid for the file system options.
  * @internal
  */
-export async function checkOptions(backend, opts) {
-    if (typeof opts != 'object' || opts === null) {
+export async function checkOptions(backend, options) {
+    if (typeof options != 'object' || options === null) {
         throw new ErrnoError(Errno.EINVAL, 'Invalid options');
     }
     // Check for required options.
     for (const [optName, opt] of Object.entries(backend.options)) {
-        const providedValue = opts?.[optName];
+        const providedValue = options?.[optName];
         if (providedValue === undefined || providedValue === null) {
             if (!opt.required) {
                 continue;
@@ -24,7 +22,7 @@ export async function checkOptions(backend, opts) {
             /* Required option not provided.
             if any incorrect options provided, which ones are close to the provided one?
             (edit distance 5 === close)*/
-            const incorrectOptions = Object.keys(opts)
+            const incorrectOptions = Object.keys(options)
                 .filter(o => !(o in backend.options))
                 .map((a) => {
                 return { str: a, distance: levenshtein(optName, a) };
@@ -44,9 +42,7 @@ export async function checkOptions(backend, opts) {
         // Otherwise: All good!
     }
 }
-/**
- * @internal
- */
+/** @internal */
 export function isBackendConfig(arg) {
     return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
 }

package/dist/backends/fetch.d.ts

@@ -41,9 +41,7 @@ export declare class FetchFS extends IndexFS {
     constructor({ index, baseUrl }: FetchOptions);
     metadata(): FileSystemMetadata;
     /**
-     * Preload the given file into the index.
-     * @param path
-     * @param buffer
+     * Preload the `path` into the index.
      */
     preload(path: string, buffer: Uint8Array): void;
     /**
@@ -70,7 +68,7 @@ declare const _Fetch: {
     readonly create: (options: FetchOptions) => FetchFS;
 };
 type _Fetch = typeof _Fetch;
-interface Fetch extends _Fetch {
+export interface Fetch extends _Fetch {
 }
 export declare const Fetch: Fetch;
 export {};

package/dist/backends/fetch.js

@@ -73,9 +73,7 @@ export class FetchFS extends IndexFS {
         };
     }
     /**
-     * Preload the given file into the index.
-     * @param path
-     * @param buffer
+     * Preload the `path` into the index.
      */
     preload(path, buffer) {
         const stats = this.index.get(path);

package/dist/backends/file_index.js

@@ -6,7 +6,7 @@ import { NoSyncFile, isWriteable } from '../file.js';
 import { FileSystem } from '../filesystem.js';
 import { Readonly } from '../mixins/readonly.js';
 import { Stats } from '../stats.js';
-import { decode, encode } from '../utils.js';
+import { decodeUTF8, encodeUTF8 } from '../utils.js';
 export const version = 1;
 /**
  * An index of files
@@ -64,7 +64,7 @@ export class Index extends Map {
         for (const [path, data] of Object.entries(json.entries)) {
             const stats = new Stats(data);
             if (stats.isDirectory()) {
-                stats.fileData = encode(JSON.stringify(this.dirEntries(path)));
+                stats.fileData = encodeUTF8(JSON.stringify(this.dirEntries(path)));
             }
             this.set(path, stats);
         }
@@ -154,7 +154,7 @@ export class IndexFS extends Readonly(FileSystem) {
         if (!stats.isDirectory()) {
             throw ErrnoError.With('ENOTDIR', path, 'readdir');
         }
-        const content = JSON.parse(decode(stats.fileData));
+        const content = JSON.parse(decodeUTF8(stats.fileData));
         if (!Array.isArray(content)) {
             throw ErrnoError.With('ENODATA', path, 'readdir');
         }

package/dist/backends/memory.d.ts

@@ -30,7 +30,7 @@ declare const _InMemory: {
     }) => StoreFS<InMemoryStore>;
 };
 type _InMemory = typeof _InMemory;
-interface InMemory extends _InMemory {
+export interface InMemory extends _InMemory {
 }
 export declare const InMemory: InMemory;
 export {};

package/dist/backends/overlay.d.ts

@@ -69,10 +69,14 @@ export declare class UnmutexedOverlayFS extends FileSystem {
     private checkInitialized;
     private checkPath;
     /**
-     * With the given path, create the needed parent directories on the writable storage
-     * should they not exist. Use modes from the read-only storage.
+     * Create the needed parent directories on the writable storage should they not exist.
+     * Use modes from the read-only storage.
      */
     private createParentDirectoriesSync;
+    /**
+     * Create the needed parent directories on the writable storage should they not exist.
+     * Use modes from the read-only storage.
+     */
     private createParentDirectories;
     /**
      * Helper function:
@@ -117,7 +121,7 @@ declare const _Overlay: {
     readonly create: (options: OverlayOptions) => OverlayFS;
 };
 type _Overlay = typeof _Overlay;
-interface Overlay extends _Overlay {
+export interface Overlay extends _Overlay {
 }
 export declare const Overlay: Overlay;
 export {};

package/dist/backends/overlay.js

@@ -1,7 +1,7 @@
 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.");
-        var dispose;
+        var dispose, inner;
         if (async) {
             if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
             dispose = value[Symbol.asyncDispose];
@@ -9,8 +9,10 @@ var __addDisposableResource = (this && this.__addDisposableResource) || function
         if (dispose === void 0) {
             if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
             dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
         }
         if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
         env.stack.push({ value: value, dispose: dispose, async: async });
     }
     else if (async) {
@@ -49,10 +51,8 @@ import { PreloadFile, parseFlag } from '../file.js';
 import { FileSystem } from '../filesystem.js';
 import { Mutexed } from '../mixins/mutexed.js';
 import { Stats } from '../stats.js';
-import { decode, encode } from '../utils.js';
-/**
- * @internal
- */
+import { decodeUTF8, encodeUTF8 } from '../utils.js';
+/** @internal */
 const deletionLogPath = '/.deleted';
 /**
  * OverlayFS makes a read-only filesystem writable by storing writes on a second, writable file system.
@@ -115,7 +115,7 @@ export class UnmutexedOverlayFS extends FileSystem {
             const file = await this.writable.openFile(deletionLogPath, parseFlag('r'));
             const { size } = await file.stat();
             const { buffer } = await file.read(new Uint8Array(size));
-            this._deleteLog = decode(buffer);
+            this._deleteLog = decodeUTF8(buffer);
         }
         catch (err) {
             if (err.errno !== Errno.ENOENT) {
@@ -379,7 +379,7 @@ export class UnmutexedOverlayFS extends FileSystem {
         this._deleteLogUpdatePending = true;
         const log = await this.writable.openFile(deletionLogPath, parseFlag('w'));
         try {
-            await log.write(encode(this._deleteLog));
+            await log.write(encodeUTF8(this._deleteLog));
             if (this._deleteLogUpdateNeeded) {
                 this._deleteLogUpdateNeeded = false;
                 await this.updateLog('');
@@ -419,8 +419,8 @@ export class UnmutexedOverlayFS extends FileSystem {
         }
     }
     /**
-     * With the given path, create the needed parent directories on the writable storage
-     * should they not exist. Use modes from the read-only storage.
+     * Create the needed parent directories on the writable storage should they not exist.
+     * Use modes from the read-only storage.
      */
     createParentDirectoriesSync(path) {
         let parent = dirname(path);
@@ -433,6 +433,10 @@ export class UnmutexedOverlayFS extends FileSystem {
             this.writable.mkdirSync(path, this.statSync(path).mode);
         }
     }
+    /**
+     * Create the needed parent directories on the writable storage should they not exist.
+     * Use modes from the read-only storage.
+     */
     async createParentDirectories(path) {
         let parent = dirname(path);
         const toCreate = [];

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

@@ -1,5 +1,3 @@
-/// <reference types="node" resolution-mode="require"/>
-/// <reference types="node" resolution-mode="require"/>
 import type { FileReadResult } from 'node:fs/promises';
 import type { ExtractProperties } from 'utilium';
 import { type MountConfiguration } from '../../config.js';
@@ -10,7 +8,8 @@ import type { Backend, FilesystemOf } from '../backend.js';
 import * as RPC from './rpc.js';
 type FileMethods = Omit<ExtractProperties<File, (...args: any[]) => Promise<any>>, typeof Symbol.asyncDispose>;
 type FileMethod = keyof FileMethods;
-interface FileRequest<TMethod extends FileMethod = FileMethod> extends RPC.Request {
+/** @internal */
+export interface FileRequest<TMethod extends FileMethod = FileMethod> extends RPC.Request {
     fd: number;
     scope: 'file';
     method: TMethod;
@@ -46,13 +45,14 @@ export declare class PortFile extends File {
 }
 type FSMethods = ExtractProperties<FileSystem, (...args: any[]) => Promise<any> | FileSystemMetadata>;
 type FSMethod = keyof FSMethods;
-interface FSRequest<TMethod extends FSMethod = FSMethod> extends RPC.Request {
+/** @internal */
+export interface FSRequest<TMethod extends FSMethod = FSMethod> extends RPC.Request {
     scope: 'fs';
     method: TMethod;
     args: Parameters<FSMethods[TMethod]>;
 }
 declare const PortFS_base: import("../../index.js").Mixin<typeof FileSystem, {
-    _sync?: FileSystem | undefined;
+    _sync?: FileSystem;
     queueDone(): Promise<void>;
     ready(): Promise<void>;
     renameSync(oldPath: string, newPath: string): void;
@@ -67,10 +67,10 @@ declare const PortFS_base: import("../../index.js").Mixin<typeof FileSystem, {
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }>;
 /**
- * PortFS lets you access a ZenFS instance that is running in a port, or the other way around.
+ * PortFS lets you access an FS instance that is running in a port, or the other way around.
  *
- * Note that synchronous operations are not permitted on the PortFS, regardless
- * of the configuration option of the remote FS.
+ * Note that *direct* synchronous operations are not permitted on the PortFS,
+ * regardless of the configuration option of the remote FS.
  */
 export declare class PortFS extends PortFS_base {
     readonly options: RPC.Options;
@@ -80,8 +80,7 @@ export declare class PortFS extends PortFS_base {
      */
     _sync: import("../store/fs.js").StoreFS<import("../memory.js").InMemoryStore>;
     /**
-     * Constructs a new PortFS instance that connects with ZenFS running on
-     * the specified port.
+     * Constructs a new PortFS instance that connects with the FS running on `options.port`.
      */
     constructor(options: RPC.Options);
     metadata(): FileSystemMetadata;
@@ -99,13 +98,9 @@ export declare class PortFS extends PortFS_base {
     exists(path: string): Promise<boolean>;
     link(srcpath: string, dstpath: string): Promise<void>;
 }
-/**
- * @internal
- */
+/** @internal */
 export type FileOrFSRequest = FSRequest | FileRequest;
-/**
- * @internal
- */
+/** @internal */
 export declare function handleRequest(port: RPC.Port, fs: FileSystem, request: FileOrFSRequest): Promise<void>;
 export declare function attachFS(port: RPC.Port, fs: FileSystem): void;
 export declare function detachFS(port: RPC.Port, fs: FileSystem): void;
@@ -128,7 +123,7 @@ declare const _Port: {
     create(options: RPC.Options): PortFS;
 };
 type _Port = typeof _Port;
-interface Port extends _Port {
+export interface Port extends _Port {
 }
 export declare const Port: Port;
 export declare function resolveRemoteMount<T extends Backend>(port: RPC.Port, config: MountConfiguration<T>, _depth?: number): Promise<FilesystemOf<T>>;

package/dist/backends/port/fs.js

@@ -87,15 +87,14 @@ export class PortFile extends File {
     }
 }
 /**
- * PortFS lets you access a ZenFS instance that is running in a port, or the other way around.
+ * PortFS lets you access an FS instance that is running in a port, or the other way around.
  *
- * Note that synchronous operations are not permitted on the PortFS, regardless
- * of the configuration option of the remote FS.
+ * Note that *direct* synchronous operations are not permitted on the PortFS,
+ * regardless of the configuration option of the remote FS.
  */
 export class PortFS extends Async(FileSystem) {
     /**
-     * Constructs a new PortFS instance that connects with ZenFS running on
-     * the specified port.
+     * Constructs a new PortFS instance that connects with the FS running on `options.port`.
      */
     constructor(options) {
         super();
@@ -160,9 +159,7 @@ export class PortFS extends Async(FileSystem) {
 }
 let nextFd = 0;
 const descriptors = new Map();
-/**
- * @internal
- */
+/** @internal */
 export async function handleRequest(port, fs, request) {
     if (!RPC.isMessage(request)) {
         return;

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

@@ -1,10 +1,10 @@
-/// <reference types="node" resolution-mode="require"/>
 import { type ErrnoErrorJSON } from '../../error.js';
 import type { Backend, FilesystemOf } from '../backend.js';
 import { type PortFS } from './fs.js';
 type _MessageEvent<T = any> = T | {
     data: T;
 };
+/** @internal */
 export interface Port {
     postMessage(value: unknown): void;
     on?(event: 'message', listener: (value: unknown) => void): this;

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

@@ -1,8 +1,8 @@
-import { PreloadFile } from '../../file.js';
 import { FileSystem, type FileSystemMetadata } from '../../filesystem.js';
 import { type Ino, Inode } from '../../inode.js';
 import type { FileType, Stats } from '../../stats.js';
 import type { Store, Transaction } from './store.js';
+import type { File } from '../../file.js';
 /**
  * A file system which uses a key-value store.
  *
@@ -34,10 +34,10 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
     renameSync(oldPath: string, newPath: string): void;
     stat(path: string): Promise<Stats>;
     statSync(path: string): Stats;
-    createFile(path: string, flag: string, mode: number): Promise<PreloadFile<this>>;
-    createFileSync(path: string, flag: string, mode: number): PreloadFile<this>;
-    openFile(path: string, flag: string): Promise<PreloadFile<this>>;
-    openFileSync(path: string, flag: string): PreloadFile<this>;
+    createFile(path: string, flag: string, mode: number): Promise<File>;
+    createFileSync(path: string, flag: string, mode: number): File;
+    openFile(path: string, flag: string): Promise<File>;
+    openFileSync(path: string, flag: string): File;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     rmdir(path: string): Promise<void>;
@@ -47,12 +47,12 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
     readdir(path: string): Promise<string[]>;
     readdirSync(path: string): string[];
     /**
-     * Updated the inode and data node at the given path
+     * Updated the inode and data node at `path`
      * @todo Ensure mtime updates properly, and use that to determine if a data update is required.
      */
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
     /**
-     * Updated the inode and data node at the given path
+     * Updated the inode and data node at `path`
      * @todo Ensure mtime updates properly, and use that to determine if a data update is required.
      */
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
@@ -82,13 +82,13 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
      */
     protected _findINodeSync(tx: Transaction, parent: string, filename: string, visited?: Set<string>): Ino;
     /**
-     * Finds the Inode of the given path.
+     * Finds the Inode of `path`.
      * @param path The path to look up.
      * @todo memoize/cache
      */
     private findINode;
     /**
-     * Finds the Inode of the given path.
+     * Finds the Inode of `path`.
      * @param path The path to look up.
      * @return The Inode of the path p.
      * @todo memoize/cache
@@ -131,18 +131,16 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
      */
     protected addNewSync(tx: Transaction, data: Uint8Array, path: string): Ino;
     /**
-     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with
-     * the given mode.
+     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with `mode`.
      * Note: This will commit the transaction.
      * @param path The path to the new file.
      * @param type The type of the new file.
      * @param mode The mode to create the new file with.
-     * @param cred The UID/GID to create the file with
      * @param data The data to store at the file's data node.
      */
     private commitNew;
     /**
-     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with the given mode.
+     * Commits a new file (well, a FILE or a DIRECTORY) to the file system with `mode`.
      * Note: This will commit the transaction.
      * @param path The path to the new file.
      * @param type The type of the new file.
@@ -152,14 +150,14 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
      */
     protected commitNewSync(path: string, type: FileType, mode: number, data?: Uint8Array): Inode;
     /**
-     * Remove all traces of the given path from the file system.
+     * Remove all traces of `path` from the file system.
      * @param path The path to remove from the file system.
      * @param isDir Does the path belong to a directory, or a file?
      * @todo Update mtime.
      */
     private remove;
     /**
-     * Remove all traces of the given path from the file system.
+     * Remove all traces of `path` from the file system.
      * @param path The path to remove from the file system.
      * @param isDir Does the path belong to a directory, or a file?
      * @todo Update mtime.