@zenfs/core 1.9.1 → 1.9.3

package/dist/backends/backend.d.ts

@@ -3,6 +3,7 @@ import type { FileSystem } from '../internal/filesystem.js';
 type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | (abstract new (...args: any[]) => any);
 /**
  * Resolves the type of Backend.options from the options interface
+ * @category Backends and Configuration
  */
 export type OptionsConfig<T> = {
     [K in keyof T]: {
@@ -29,6 +30,7 @@ export type OptionsConfig<T> = {
 };
 /**
  * Configuration options shared by backends and `Configuration`
+ * @category Backends and Configuration
  */
 export interface SharedConfig {
     /**
@@ -38,6 +40,7 @@ export interface SharedConfig {
 }
 /**
  * A backend
+ * @category Backends and Configuration
  */
 export interface Backend<FS extends FileSystem = FileSystem, TOptions extends object = object> {
     /**
@@ -65,18 +68,24 @@ export interface Backend<FS extends FileSystem = FileSystem, TOptions extends ob
 }
 /**
  * Gets the options type of a backend
+ * @category Backends and Configuration
  * @internal
  */
 export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
 /**
  * Gets the FileSystem type for a backend
+ * @category Backends and Configuration
  * @internal
  */
 export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
-/** @internal */
+/**
+ * @category Backends and Configuration
+ * @internal
+ */
 export declare function isBackend(arg: unknown): arg is Backend;
 /**
  * Checks that `options` object is valid for the file system options.
+ * @category Backends and Configuration
  * @internal
  */
 export declare function checkOptions<T extends Backend>(backend: T, options: Record<string, unknown>): Promise<void>;
@@ -86,10 +95,15 @@ export declare function checkOptions<T extends Backend>(backend: T, options: Rec
  * Individual options can recursively contain BackendConfiguration objects for values that require file systems.
  *
  * The configuration for each file system corresponds to that file system's option object passed to its `create()` method.
+ *
+ * @category Backends and Configuration
  */
 export type BackendConfiguration<T extends Backend> = OptionsOf<T> & Partial<SharedConfig> & {
     backend: T;
 };
-/** @internal */
+/**
+ * @internal
+ * @category Backends and Configuration
+ */
 export declare function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T>;
 export {};

package/dist/backends/backend.js

@@ -1,11 +1,15 @@
 import { Errno, ErrnoError } from '../internal/error.js';
 import { debug, err } from '../internal/log.js';
-/** @internal */
+/**
+ * @category Backends and Configuration
+ * @internal
+ */
 export function isBackend(arg) {
     return arg != null && typeof arg == 'object' && 'create' in arg && typeof arg.create == 'function';
 }
 /**
  * Checks that `options` object is valid for the file system options.
+ * @category Backends and Configuration
  * @internal
  */
 export async function checkOptions(backend, options) {
@@ -37,7 +41,10 @@ export async function checkOptions(backend, options) {
         // Otherwise: All good!
     }
 }
-/** @internal */
+/**
+ * @internal
+ * @category Backends and Configuration
+ */
 export function isBackendConfig(arg) {
     return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
 }

package/dist/backends/fetch.d.ts

@@ -4,6 +4,7 @@ import { IndexFS } from '../internal/index_fs.js';
 import type { SharedConfig } from './backend.js';
 /**
  * Configuration options for FetchFS.
+ * @category Backends and Configuration
  */
 export interface FetchOptions extends SharedConfig {
     /**
@@ -33,6 +34,11 @@ export declare class FetchFS extends IndexFS {
     protected baseUrl: string;
     protected requestInit: RequestInit;
     protected remoteWrite?: boolean | undefined;
+    /**
+     * @internal @hidden
+     */
+    _asyncDone: Promise<unknown>;
+    protected _async(p: Promise<unknown>): void;
     constructor(index: Index, baseUrl: string, requestInit?: RequestInit, remoteWrite?: boolean | undefined);
     protected remove(path: string): Promise<void>;
     protected removeSync(path: string): void;

package/dist/backends/fetch.js

@@ -27,17 +27,24 @@ function parseError(path, fs) {
  * @internal
  */
 export class FetchFS extends IndexFS {
+    _async(p) {
+        this._asyncDone = this._asyncDone.then(() => p);
+    }
     constructor(index, baseUrl, requestInit = {}, remoteWrite) {
         super(0x206e6673, 'nfs', index);
         this.baseUrl = baseUrl;
         this.requestInit = requestInit;
         this.remoteWrite = remoteWrite;
+        /**
+         * @internal @hidden
+         */
+        this._asyncDone = Promise.resolve();
     }
     async remove(path) {
         await requests.remove(this.baseUrl + path, { warn, cacheOnly: !this.remoteWrite }, this.requestInit);
     }
     removeSync(path) {
-        void requests.remove(this.baseUrl + path, { warn, cacheOnly: !this.remoteWrite }, this.requestInit);
+        this._async(requests.remove(this.baseUrl + path, { warn, cacheOnly: !this.remoteWrite }, this.requestInit));
     }
     async read(path, buffer, offset = 0, end) {
         const inode = this.index.get(path);
@@ -65,7 +72,7 @@ export class FetchFS extends IndexFS {
         if (!data)
             throw ErrnoError.With('ENODATA', path, 'read');
         if (missing.length) {
-            void requests.get(this.baseUrl + path, { start: offset, end, size: inode.size, warn });
+            this._async(requests.get(this.baseUrl + path, { start: offset, end, size: inode.size, warn }));
             throw ErrnoError.With('EAGAIN', path, 'read');
         }
         buffer.set(data);
@@ -74,7 +81,7 @@ export class FetchFS extends IndexFS {
         await requests.set(this.baseUrl + path, data, { offset, warn, cacheOnly: !this.remoteWrite }, this.requestInit).catch(parseError(path, this));
     }
     writeSync(path, data, offset) {
-        void requests.set(this.baseUrl + path, data, { offset, warn, cacheOnly: !this.remoteWrite }, this.requestInit).catch(parseError(path, this));
+        this._async(requests.set(this.baseUrl + path, data, { offset, warn, cacheOnly: !this.remoteWrite }, this.requestInit).catch(parseError(path, this)));
     }
 }
 const _Fetch = {

package/dist/backends/memory.d.ts

@@ -2,6 +2,7 @@ import { StoreFS } from './store/fs.js';
 import { SyncMapTransaction, type SyncMapStore } from './store/map.js';
 /**
  * A simple in-memory store
+ * @category Stores and Transactions
  */
 export declare class InMemoryStore extends Map<number, Uint8Array> implements SyncMapStore {
     readonly label?: string | undefined;

package/dist/backends/memory.js

@@ -2,6 +2,7 @@ import { StoreFS } from './store/fs.js';
 import { SyncMapTransaction } from './store/map.js';
 /**
  * A simple in-memory store
+ * @category Stores and Transactions
  */
 export class InMemoryStore extends Map {
     constructor(label) {

package/dist/backends/overlay.d.ts

@@ -5,6 +5,7 @@ import type { InodeLike } from '../internal/inode.js';
 import { FileSystem } from '../internal/filesystem.js';
 /**
  * Configuration options for OverlayFS instances.
+ * @category Backends and Configuration
  */
 export interface OverlayOptions {
     /**

package/dist/backends/passthrough.d.ts

@@ -4,6 +4,10 @@ import { FileSystem } from '../internal/filesystem.js';
 import type { InodeLike } from '../internal/inode.js';
 import { Stats } from '../stats.js';
 export type NodeFS = typeof fs;
+/**
+ * Passthrough backend options
+ * @category Backends and Configuration
+ */
 export interface PassthroughOptions {
     fs: NodeFS;
     prefix?: string;

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

@@ -12,6 +12,7 @@ import { WrappedTransaction, type Store } from './store.js';
  *
  * @todo Introduce Node ID caching?
  * @todo Check modes?
+ * @category Stores and Transactions
  * @internal
  */
 export declare class StoreFS<T extends Store = Store> extends FileSystem {

package/dist/backends/store/fs.js

@@ -69,6 +69,7 @@ import { WrappedTransaction } from './store.js';
  *
  * @todo Introduce Node ID caching?
  * @todo Check modes?
+ * @category Stores and Transactions
  * @internal
  */
 export class StoreFS extends FileSystem {

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

@@ -2,6 +2,7 @@ import type { Store } from './store.js';
 import { AsyncTransaction, SyncTransaction } from './store.js';
 /**
  * An interface for simple synchronous stores that don't have special support for transactions and such, based on `Map`
+ * @category Stores and Transactions
  */
 export interface SyncMapStore extends Store {
     keys(): Iterable<number>;
@@ -12,6 +13,7 @@ export interface SyncMapStore extends Store {
 }
 /**
  * Transaction for map stores.
+ * @category Stores and Transactions
  * @see SyncMapStore
  */
 export declare class SyncMapTransaction extends SyncTransaction<SyncMapStore> {
@@ -24,6 +26,7 @@ export declare class SyncMapTransaction extends SyncTransaction<SyncMapStore> {
 }
 /**
  * An interface for simple asynchronous stores that don't have special support for transactions and such, based on `Map`.
+ * @category Stores and Transactions
  */
 export interface AsyncMap {
     keys(): Iterable<number>;
@@ -32,6 +35,9 @@ export interface AsyncMap {
     set(id: number, data: Uint8Array, offset?: number): Promise<void>;
     delete(id: number): Promise<void>;
 }
+/**
+ * @category Stores and Transactions
+ */
 export declare class AsyncMapTransaction<T extends Store & AsyncMap = Store & AsyncMap> extends AsyncTransaction<T> {
     keys(): Promise<Iterable<number>>;
     get(id: number, offset?: number, end?: number): Promise<Uint8Array | undefined>;

package/dist/backends/store/map.js

@@ -1,6 +1,7 @@
 import { AsyncTransaction, SyncTransaction } from './store.js';
 /**
  * Transaction for map stores.
+ * @category Stores and Transactions
  * @see SyncMapStore
  */
 export class SyncMapTransaction extends SyncTransaction {
@@ -22,6 +23,9 @@ export class SyncMapTransaction extends SyncTransaction {
         this.store.delete(id);
     }
 }
+/**
+ * @category Stores and Transactions
+ */
 export class AsyncMapTransaction extends AsyncTransaction {
     async keys() {
         await this.asyncDone;

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

@@ -2,14 +2,17 @@ import type { AsyncMap, SyncMapStore } from './map.js';
 import { SyncMapTransaction } from './map.js';
 import type { Store } from './store.js';
 /**
+ * @category Stores and Transactions
  * @deprecated Use `MapStore` instead.
  */
 export type SimpleSyncStore = SyncMapStore;
 /**
+ * @category Stores and Transactions
  * @deprecated Use `AsyncMapStore` instead.
  */
 export type SimpleAsyncStore = AsyncMap & Store;
 /**
+ * @category Stores and Transactions
  * @deprecated Use `MapTransaction` instead.
  */
 export declare class SimpleTransaction extends SyncMapTransaction {

package/dist/backends/store/simple.js

@@ -1,6 +1,7 @@
 import { log_deprecated } from '../../internal/log.js';
 import { SyncMapTransaction } from './map.js';
 /**
+ * @category Stores and Transactions
  * @deprecated Use `MapTransaction` instead.
  */
 export class SimpleTransaction extends SyncMapTransaction {

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

@@ -1,11 +1,15 @@
 import { Resource } from 'utilium/cache.js';
 import '../../polyfills.js';
 import type { StoreFS } from './fs.js';
+/**
+ * @category Stores and Transactions
+ */
 export type StoreFlag = 
 /** The store supports partial reads and writes */
 'partial';
 /**
  * Represents a key-value store.
+ * @category Stores and Transactions
  */
 export interface Store {
     /**
@@ -51,6 +55,7 @@ export interface Store {
 }
 /**
  * A transaction for a store.
+ * @category Stores and Transactions
  */
 export declare abstract class Transaction<T extends Store = Store> {
     readonly store: T;
@@ -96,19 +101,24 @@ export declare abstract class Transaction<T extends Store = Store> {
 }
 /**
  * Transaction that implements asynchronous operations with synchronous ones
+ * @category Stores and Transactions
  */
 export declare abstract class SyncTransaction<T extends Store = Store> extends Transaction<T> {
     get(id: number, offset: number, end?: number): Promise<Uint8Array | undefined>;
     set(id: number, data: Uint8Array, offset: number): Promise<void>;
     remove(id: number): Promise<void>;
 }
+/**
+ * @category Stores and Transactions
+ */
 export interface AsyncStore extends Store {
     cache?: Map<number, Resource<number>>;
 }
 /**
  * Transaction that implements synchronous operations with a cache
- * @implementors You *must* update the cache and wait for `store.asyncDone` in your asynchronous methods.
+ * Implementors: You *must* update the cache and wait for `store.asyncDone` in your asynchronous methods.
  * @todo Make sure we handle abortions correctly, especially since the cache is shared between transactions.
+ * @category Stores and Transactions
  */
 export declare abstract class AsyncTransaction<T extends AsyncStore = AsyncStore> extends Transaction<T> {
     protected asyncDone: Promise<unknown>;
@@ -132,6 +142,7 @@ export declare abstract class AsyncTransaction<T extends AsyncStore = AsyncStore
 /**
  * Wraps a transaction with the ability to roll-back changes, among other things.
  * This is used by `StoreFS`
+ * @category Stores and Transactions
  * @internal @hidden
  */
 export declare class WrappedTransaction<T extends Store = Store> {

package/dist/backends/store/store.js

@@ -4,6 +4,7 @@ import { err, warn } from '../../internal/log.js';
 import '../../polyfills.js';
 /**
  * A transaction for a store.
+ * @category Stores and Transactions
  */
 export class Transaction {
     constructor(store) {
@@ -12,6 +13,7 @@ export class Transaction {
 }
 /**
  * Transaction that implements asynchronous operations with synchronous ones
+ * @category Stores and Transactions
  */
 export class SyncTransaction extends Transaction {
     /* eslint-disable @typescript-eslint/require-await */
@@ -27,8 +29,9 @@ export class SyncTransaction extends Transaction {
 }
 /**
  * Transaction that implements synchronous operations with a cache
- * @implementors You *must* update the cache and wait for `store.asyncDone` in your asynchronous methods.
+ * Implementors: You *must* update the cache and wait for `store.asyncDone` in your asynchronous methods.
  * @todo Make sure we handle abortions correctly, especially since the cache is shared between transactions.
+ * @category Stores and Transactions
  */
 export class AsyncTransaction extends Transaction {
     constructor() {
@@ -89,6 +92,7 @@ export class AsyncTransaction extends Transaction {
 /**
  * Wraps a transaction with the ability to roll-back changes, among other things.
  * This is used by `StoreFS`
+ * @category Stores and Transactions
  * @internal @hidden
  */
 export class WrappedTransaction {

package/dist/config.d.ts

@@ -3,21 +3,25 @@ import type { Device, DeviceDriver } from './internal/devices.js';
 import type { LogConfiguration } from './internal/log.js';
 /**
  * Configuration for a specific mount point
+ * @category Backends and Configuration
  */
 export type MountConfiguration<T extends Backend> = FilesystemOf<T> | BackendConfiguration<T> | T;
 /**
  * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
  * @see MountConfiguration
  */
 export declare function resolveMountConfig<T extends Backend>(configuration: MountConfiguration<T>, _depth?: number): Promise<FilesystemOf<T>>;
 /**
  * An object mapping mount points to backends
+ * @category Backends and Configuration
  */
 export interface ConfigMounts {
     [K: string]: Backend;
 }
 /**
  * Configuration
+ * @category Backends and Configuration
  */
 export interface Configuration<T extends ConfigMounts> extends SharedConfig {
     /**
@@ -88,11 +92,16 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
 }
 /**
  * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
  */
 export declare function configureSingle<T extends Backend>(configuration: MountConfiguration<T>): Promise<void>;
+/**
+ * @category Backends and Configuration
+ */
 export declare function addDevice(driver: DeviceDriver, options?: object): Device;
 /**
  * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
  * @see Configuration
  */
 export declare function configure<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): Promise<void>;

package/dist/config.js

@@ -13,6 +13,7 @@ function isMountConfig(arg) {
 }
 /**
  * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
  * @see MountConfiguration
  */
 export async function resolveMountConfig(configuration, _depth = 0) {
@@ -53,6 +54,7 @@ export async function resolveMountConfig(configuration, _depth = 0) {
 }
 /**
  * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
  */
 export async function configureSingle(configuration) {
     if (!isBackendConfig(configuration)) {
@@ -82,6 +84,9 @@ async function mount(path, mount) {
     }
     fs.mount(path, mount);
 }
+/**
+ * @category Backends and Configuration
+ */
 export function addDevice(driver, options) {
     const devfs = mounts.get('/dev');
     if (!(devfs instanceof DeviceFS))
@@ -90,6 +95,7 @@ export function addDevice(driver, options) {
 }
 /**
  * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
  * @see Configuration
  */
 export async function configure(configuration) {

package/dist/context.d.ts

@@ -2,7 +2,7 @@ import type { CredentialInit, Credentials } from './internal/credentials.js';
 import * as fs from './vfs/index.js';
 /**
  * Represents some context used for FS operations
- * @experimental
+ * @category Backends and Configuration
  */
 export interface FSContext {
     root: string;
@@ -10,12 +10,11 @@ export interface FSContext {
 }
 /**
  * maybe an FS context
- * @experimental @hidden
  */
 export type V_Context = void | (Partial<FSContext> & object);
 /**
  * Allows you to restrict operations to a specific root path and set of credentials.
- * @experimental
+ * @category Backends and Configuration
  */
 export interface BoundContext extends FSContext {
     fs: typeof fs;
@@ -23,6 +22,6 @@ export interface BoundContext extends FSContext {
 /**
  * Allows you to restrict operations to a specific root path and set of credentials.
  * Note that the default credentials of a bound context are copied from the global credentials.
- * @experimental
+ * @category Backends and Configuration
  */
 export declare function bindContext(root: string, credentials?: CredentialInit): BoundContext;

package/dist/context.js

@@ -10,7 +10,7 @@ function _bindFunctions(fns, thisValue) {
 /**
  * Allows you to restrict operations to a specific root path and set of credentials.
  * Note that the default credentials of a bound context are copied from the global credentials.
- * @experimental
+ * @category Backends and Configuration
  */
 export function bindContext(root, credentials = structuredClone(defaultCredentials)) {
     const ctx = {

package/dist/internal/credentials.d.ts

@@ -1,6 +1,7 @@
 /**
  * Credentials used for various operations.
  * Similar to Linux's cred struct.
+ * @category Internals
  * @see https://github.com/torvalds/linux/blob/master/include/linux/cred.h
  */
 export interface Credentials {
@@ -15,16 +16,24 @@ export interface Credentials {
      */
     groups: number[];
 }
+/**
+ * @category Internals
+ */
 export declare const credentials: Credentials;
 /**
  * Initialization for a set of credentials
+ * @category Internals
  */
 export interface CredentialInit extends Partial<Credentials> {
     uid: number;
     gid: number;
 }
+/**
+ * @category Internals
+ */
 export declare function createCredentials(source: CredentialInit): Credentials;
 /**
  * Uses credentials from the provided uid and gid.
+ * @category Internals
  */
 export declare function useCredentials(source: CredentialInit): void;

package/dist/internal/credentials.js

@@ -1,3 +1,6 @@
+/**
+ * @category Internals
+ */
 export const credentials = {
     uid: 0,
     gid: 0,
@@ -7,6 +10,9 @@ export const credentials = {
     egid: 0,
     groups: [],
 };
+/**
+ * @category Internals
+ */
 export function createCredentials(source) {
     return {
         suid: source.uid,
@@ -19,6 +25,7 @@ export function createCredentials(source) {
 }
 /**
  * Uses credentials from the provided uid and gid.
+ * @category Internals
  */
 export function useCredentials(source) {
     Object.assign(credentials, createCredentials(source));

package/dist/internal/devices.d.ts

@@ -8,6 +8,7 @@ import { Inode } from './inode.js';
 /**
  * A device
  * @todo Maybe add some other device information, like a UUID?
+ * @category Internals
  * @privateRemarks
  * UUIDs were considered, however they don't make sense without an easy mechanism for persistence
  */
@@ -34,6 +35,9 @@ export interface Device<TData = any> {
      */
     minor: number;
 }
+/**
+ * @category Internals
+ */
 export interface DeviceInit<TData = any> {
     data?: TData;
     minor?: number;
@@ -42,6 +46,7 @@ export interface DeviceInit<TData = any> {
 }
 /**
  * A device driver
+ * @category Internals
  */
 export interface DeviceDriver<TData = any> {
     /**
@@ -108,6 +113,8 @@ export interface DeviceDriver<TData = any> {
  * 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.
+ * @category Internals
+ * @internal
  */
 export declare class DeviceFile<TData = any> extends File {
     fs: DeviceFS;
@@ -137,6 +144,7 @@ export declare class DeviceFile<TData = any> extends File {
 }
 /**
  * A temporary file system that manages and interfaces with devices
+ * @category Internals
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
     protected readonly devices: Map<string, Device<any>>;
@@ -184,6 +192,7 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
  * Simulates the `/dev/null` device.
  * - Reads return 0 bytes (EOF).
  * - Writes discard data, advancing the file position.
+ * @category Internals
  * @internal
  */
 export declare const nullDevice: DeviceDriver;
@@ -195,6 +204,7 @@ export declare const nullDevice: DeviceDriver;
  * - Reads fill the buffer with zeroes.
  * - Writes discard data but update the file position.
  * - Provides basic file metadata, treating it as a character device.
+ * @category Internals
  * @internal
  */
 export declare const zeroDevice: DeviceDriver;
@@ -202,6 +212,7 @@ export declare const zeroDevice: DeviceDriver;
  * Simulates the `/dev/full` device.
  * - Reads behave like `/dev/zero` (returns zeroes).
  * - Writes always fail with ENOSPC (no space left on device).
+ * @category Internals
  * @internal
  */
 export declare const fullDevice: DeviceDriver;
@@ -209,11 +220,14 @@ export declare const fullDevice: DeviceDriver;
  * Simulates the `/dev/random` device.
  * - Reads return random bytes.
  * - Writes discard data, advancing the file position.
+ * @category Internals
  * @internal
  */
 export declare const randomDevice: DeviceDriver;
 /**
  * Shortcuts for importing.
+ * @category Internals
+ * @internal
  */
 export declare const devices: {
     null: DeviceDriver<any>;