@zenfs/core 1.11.3 → 2.0.0

package/dist/backends/passthrough.d.ts

@@ -1,8 +1,7 @@
 import type * as fs from 'node:fs';
-import { File } from '../internal/file.js';
-import { FileSystem, type UsageInfo } from '../internal/filesystem.js';
-import type { InodeLike } from '../internal/inode.js';
-import { Stats } from '../stats.js';
+import type { CreationOptions, UsageInfo } from '../internal/filesystem.js';
+import { FileSystem } from '../internal/filesystem.js';
+import { type InodeLike } from '../internal/inode.js';
 export type NodeFS = typeof fs;
 /**
  * Passthrough backend options
@@ -10,7 +9,7 @@ export type NodeFS = typeof fs;
  */
 export interface PassthroughOptions {
     fs: NodeFS;
-    prefix?: string;
+    prefix: string;
 }
 export declare class PassthroughFS extends FileSystem {
     readonly nodeFS: NodeFS;
@@ -30,19 +29,13 @@ export declare class PassthroughFS extends FileSystem {
     /**
      * Get file statistics.
      */
-    stat(path: string): Promise<Stats>;
+    stat(path: string): Promise<InodeLike>;
     /**
      * Get file statistics synchronously.
      */
-    statSync(path: string): Stats;
-    /**
-     * Open a file.
-     */
-    openFile(path: string, flag: string): Promise<File>;
-    /**
-     * Open a file synchronously.
-     */
-    openFileSync(path: string, flag: string): File;
+    statSync(path: string): InodeLike;
+    touch(path: string, metadata: InodeLike): Promise<void>;
+    touchSync(path: string, metadata: InodeLike): void;
     /**
      * Unlink (delete) a file.
      */
@@ -54,11 +47,11 @@ export declare class PassthroughFS extends FileSystem {
     /**
      * Create a directory.
      */
-    mkdir(path: string, mode: number): Promise<void>;
+    mkdir(path: string, options: CreationOptions): Promise<InodeLike>;
     /**
      * Create a directory synchronously.
      */
-    mkdirSync(path: string, mode: number): void;
+    mkdirSync(path: string, options: CreationOptions): InodeLike;
     /**
      * Read the contents of a directory.
      */
@@ -70,11 +63,11 @@ export declare class PassthroughFS extends FileSystem {
     /**
      * Create a file.
      */
-    createFile(path: string, flag: string, mode: number): Promise<File>;
+    createFile(path: string, options: CreationOptions): Promise<InodeLike>;
     /**
      * Create a file synchronously.
      */
-    createFileSync(path: string, flag: string, mode: number): File;
+    createFileSync(path: string, options: CreationOptions): InodeLike;
     /**
      * Remove a directory.
      */
@@ -86,11 +79,11 @@ export declare class PassthroughFS extends FileSystem {
     /**
      * Synchronize data to the file system.
      */
-    sync(path: string, data: Uint8Array, stats: Readonly<InodeLike>): Promise<void>;
+    sync(path: string): Promise<void>;
     /**
      * Synchronize data to the file system synchronously.
      */
-    syncSync(path: string, data: Uint8Array, stats: Readonly<InodeLike>): void;
+    syncSync(path: string): void;
     /**
      * Create a hard link.
      */
@@ -113,12 +106,16 @@ declare const _Passthrough: {
         };
         readonly prefix: {
             readonly type: "string";
-            readonly required: false;
+            readonly required: true;
         };
     };
     readonly create: ({ fs, prefix }: PassthroughOptions) => PassthroughFS;
 };
 type _Passthrough = typeof _Passthrough;
+/**
+ * A file system that passes through to another FS
+ * @category Backends and Configuration
+ */
 export interface Passthrough extends _Passthrough {
 }
 /**

package/dist/backends/passthrough.js

@@ -51,90 +51,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { ErrnoError } from '../internal/error.js';
-import { File } from '../internal/file.js';
 import { FileSystem } from '../internal/filesystem.js';
-import { Stats } from '../stats.js';
-import { join, resolve } from '../vfs/path.js';
-class PassthroughFile extends File {
-    constructor(fs, path, fd) {
-        super(fs, path);
-        this.fd = fd;
-        this.node = fs.nodeFS;
-        this.nodePath = fs.path(path);
-    }
-    error(err) {
-        const error = err;
-        return ErrnoError.With(error.code, this.path, error.syscall);
-    }
-    get position() {
-        // Placeholder: Implement proper position tracking if needed.
-        return 0;
-    }
-    async stat() {
-        const { resolve, reject, promise } = Promise.withResolvers();
-        this.node.fstat(this.fd, (err, stats) => (err ? reject(this.error(err)) : resolve(new Stats(stats))));
-        return promise;
-    }
-    statSync() {
-        return new Stats(this.node.fstatSync(this.fd));
-    }
-    close() {
-        const { resolve, reject, promise } = Promise.withResolvers();
-        this.node.close(this.fd, err => (err ? reject(this.error(err)) : resolve()));
-        return promise;
-    }
-    closeSync() {
-        this.node.closeSync(this.fd);
-    }
-    async truncate(len) {
-        await this.node.promises.truncate(this.nodePath, len);
-    }
-    truncateSync(len) {
-        this.node.ftruncateSync(this.fd, len);
-    }
-    async sync() {
-        const { resolve, reject, promise } = Promise.withResolvers();
-        this.node.fsync(this.fd, err => (err ? reject(this.error(err)) : resolve()));
-        return promise;
-    }
-    syncSync() {
-        this.node.fsyncSync(this.fd);
-    }
-    async write(buffer, offset, length, position) {
-        const { resolve, reject, promise } = Promise.withResolvers();
-        this.node.write(this.fd, buffer, offset, length, position, (err, written) => (err ? reject(this.error(err)) : resolve(written)));
-        return promise;
-    }
-    writeSync(buffer, offset, length, position) {
-        return this.node.writeSync(this.fd, buffer, offset, length, position);
-    }
-    async read(buffer, offset = 0, length, position = null) {
-        const { resolve, reject, promise } = Promise.withResolvers();
-        this.node.read(this.fd, buffer, offset, length || (await this.stat()).size, position, (err, bytesRead, buffer) => err ? reject(this.error(err)) : resolve({ bytesRead, buffer }));
-        return promise;
-    }
-    readSync(buffer, offset = 0, length = this.statSync().size, position = null) {
-        return this.node.readSync(this.fd, buffer, offset, length, position);
-    }
-    async chmod(mode) {
-        await this.node.promises.chmod(this.nodePath, mode);
-    }
-    chmodSync(mode) {
-        this.node.fchmodSync(this.fd, mode);
-    }
-    async chown(uid, gid) {
-        await this.node.promises.chown(this.nodePath, uid, gid);
-    }
-    chownSync(uid, gid) {
-        this.node.fchownSync(this.fd, uid, gid);
-    }
-    async utimes(atime, mtime) {
-        await this.node.promises.utimes(this.nodePath, atime, mtime);
-    }
-    utimesSync(atime, mtime) {
-        this.node.futimesSync(this.fd, atime, mtime);
-    }
-}
+import { isDirectory } from '../internal/inode.js';
+import { resolve } from '../path.js';
+import { warn } from '../internal/log.js';
 export class PassthroughFS extends FileSystem {
     constructor(nodeFS, prefix) {
         super(0x6e6f6465, 'nodefs');
@@ -149,7 +69,7 @@ export class PassthroughFS extends FileSystem {
         };
     }
     path(path) {
-        return join(this.prefix, path.slice(1));
+        return this.prefix + path;
     }
     error(err, path) {
         const error = err;
@@ -182,7 +102,7 @@ export class PassthroughFS extends FileSystem {
      */
     async stat(path) {
         try {
-            return new Stats(await this.nodeFS.promises.stat(this.path(path)));
+            return await this.nodeFS.promises.stat(this.path(path));
         }
         catch (err) {
             this.error(err, path);
@@ -193,31 +113,40 @@ export class PassthroughFS extends FileSystem {
      */
     statSync(path) {
         try {
-            return new Stats(this.nodeFS.statSync(this.path(path)));
+            return this.nodeFS.statSync(this.path(path));
         }
         catch (err) {
             this.error(err, path);
         }
     }
-    /**
-     * Open a file.
-     */
-    async openFile(path, flag) {
+    async touch(path, metadata) {
         try {
-            const { fd } = await this.nodeFS.promises.open(this.path(path), flag);
-            return new PassthroughFile(this, path, fd);
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const handle = __addDisposableResource(env_1, await this.nodeFS.promises.open(this.path(path), 'w'), true);
+                await handle.chmod(metadata.mode);
+                await handle.chown(metadata.uid, metadata.gid);
+                await handle.utimes(metadata.atimeMs, metadata.mtimeMs);
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
+            }
         }
         catch (err) {
             this.error(err, path);
         }
     }
-    /**
-     * Open a file synchronously.
-     */
-    openFileSync(path, flag) {
+    touchSync(path, metadata) {
         try {
-            const fd = this.nodeFS.openSync(this.path(path), flag);
-            return new PassthroughFile(this, path, fd);
+            this.nodeFS.chmodSync(this.path(path), metadata.mode);
+            this.nodeFS.chownSync(this.path(path), metadata.uid, metadata.gid);
+            this.nodeFS.utimesSync(this.path(path), metadata.atimeMs, metadata.mtimeMs);
         }
         catch (err) {
             this.error(err, path);
@@ -248,9 +177,10 @@ export class PassthroughFS extends FileSystem {
     /**
      * Create a directory.
      */
-    async mkdir(path, mode) {
+    async mkdir(path, options) {
         try {
-            await this.nodeFS.promises.mkdir(this.path(path), { mode });
+            await this.nodeFS.promises.mkdir(this.path(path), options);
+            return await this.nodeFS.promises.stat(this.path(path));
         }
         catch (err) {
             this.error(err, path);
@@ -259,9 +189,10 @@ export class PassthroughFS extends FileSystem {
     /**
      * Create a directory synchronously.
      */
-    mkdirSync(path, mode) {
+    mkdirSync(path, options) {
         try {
-            this.nodeFS.mkdirSync(this.path(path), { mode });
+            this.nodeFS.mkdirSync(this.path(path), options);
+            return this.nodeFS.statSync(this.path(path));
         }
         catch (err) {
             this.error(err, path);
@@ -292,10 +223,28 @@ export class PassthroughFS extends FileSystem {
     /**
      * Create a file.
      */
-    async createFile(path, flag, mode) {
+    async createFile(path, options) {
         try {
-            const { fd } = await this.nodeFS.promises.open(this.path(path), flag, mode);
-            return new PassthroughFile(this, path, fd);
+            if (isDirectory(options)) {
+                await this.nodeFS.promises.mkdir(this.path(path), { mode: options.mode });
+            }
+            else {
+                const env_2 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const handle = __addDisposableResource(env_2, await this.nodeFS.promises.open(this.path(path), 'wx'), true);
+                    await handle.close();
+                }
+                catch (e_2) {
+                    env_2.error = e_2;
+                    env_2.hasError = true;
+                }
+                finally {
+                    const result_2 = __disposeResources(env_2);
+                    if (result_2)
+                        await result_2;
+                }
+            }
+            return await this.nodeFS.promises.stat(this.path(path));
         }
         catch (err) {
             this.error(err, path);
@@ -304,10 +253,16 @@ export class PassthroughFS extends FileSystem {
     /**
      * Create a file synchronously.
      */
-    createFileSync(path, flag, mode) {
+    createFileSync(path, options) {
         try {
-            const fd = this.nodeFS.openSync(this.path(path), flag, mode);
-            return new PassthroughFile(this, path, fd);
+            if (isDirectory(options)) {
+                this.nodeFS.mkdirSync(this.path(path), { mode: options.mode });
+            }
+            else {
+                const fd = this.nodeFS.openSync(this.path(path), 'wx');
+                this.nodeFS.closeSync(fd);
+            }
+            return this.nodeFS.statSync(this.path(path));
         }
         catch (err) {
             this.error(err, path);
@@ -338,44 +293,14 @@ export class PassthroughFS extends FileSystem {
     /**
      * Synchronize data to the file system.
      */
-    async sync(path, data, stats) {
-        try {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const handle = __addDisposableResource(env_1, await this.nodeFS.promises.open(this.path(path), 'w'), true);
-                await handle.writeFile(data);
-                await handle.chmod(stats.mode);
-                await handle.chown(stats.uid, stats.gid);
-                await handle.utimes(stats.atimeMs, stats.mtimeMs);
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                const result_1 = __disposeResources(env_1);
-                if (result_1)
-                    await result_1;
-            }
-        }
-        catch (err) {
-            this.error(err, path);
-        }
+    async sync(path) {
+        warn('Sync on passthrough is unnecessary');
     }
     /**
      * Synchronize data to the file system synchronously.
      */
-    syncSync(path, data, stats) {
-        try {
-            const p = this.path(path);
-            this.nodeFS.writeFileSync(p, data);
-            this.nodeFS.chmodSync(p, stats.mode);
-            this.nodeFS.chownSync(p, stats.uid, stats.gid);
-            this.nodeFS.utimesSync(p, stats.atimeMs, stats.mtimeMs);
-        }
-        catch (err) {
-            this.error(err, path);
-        }
+    syncSync(path) {
+        warn('Sync on passthrough is unnecessary');
     }
     /**
      * Create a hard link.
@@ -401,19 +326,19 @@ export class PassthroughFS extends FileSystem {
     }
     async read(path, buffer, offset, end) {
         try {
-            const env_2 = { stack: [], error: void 0, hasError: false };
+            const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                const handle = __addDisposableResource(env_2, await this.nodeFS.promises.open(this.path(path), 'r'), true);
+                const handle = __addDisposableResource(env_3, await this.nodeFS.promises.open(this.path(path), 'r'), true);
                 await handle.read({ buffer, offset, length: end - offset });
             }
-            catch (e_2) {
-                env_2.error = e_2;
-                env_2.hasError = true;
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
             }
             finally {
-                const result_2 = __disposeResources(env_2);
-                if (result_2)
-                    await result_2;
+                const result_3 = __disposeResources(env_3);
+                if (result_3)
+                    await result_3;
             }
         }
         catch (err) {
@@ -436,19 +361,19 @@ export class PassthroughFS extends FileSystem {
     }
     async write(path, buffer, offset) {
         try {
-            const env_3 = { stack: [], error: void 0, hasError: false };
+            const env_4 = { stack: [], error: void 0, hasError: false };
             try {
-                const handle = __addDisposableResource(env_3, await this.nodeFS.promises.open(this.path(path), 'w'), true);
+                const handle = __addDisposableResource(env_4, await this.nodeFS.promises.open(this.path(path), 'w'), true);
                 await handle.write(buffer, offset);
             }
-            catch (e_3) {
-                env_3.error = e_3;
-                env_3.hasError = true;
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
             }
             finally {
-                const result_3 = __disposeResources(env_3);
-                if (result_3)
-                    await result_3;
+                const result_4 = __disposeResources(env_4);
+                if (result_4)
+                    await result_4;
             }
         }
         catch (err) {
@@ -474,9 +399,9 @@ const _Passthrough = {
     name: 'Passthrough',
     options: {
         fs: { type: 'object', required: true },
-        prefix: { type: 'string', required: false },
+        prefix: { type: 'string', required: true },
     },
-    create({ fs, prefix = '/' }) {
+    create({ fs, prefix }) {
         return new PassthroughFS(fs, resolve(prefix));
     },
 };

package/dist/backends/port.d.ts

@@ -0,0 +1,207 @@
+import type { TransferListItem } from 'node:worker_threads';
+import type { MountConfiguration } from '../config.js';
+import type { CreationOptions, UsageInfo } from '../internal/filesystem.js';
+import type { InodeLike } from '../internal/inode.js';
+import type { Backend, FilesystemOf } from './backend.js';
+import { FileSystem } from '../internal/filesystem.js';
+import { Inode } from '../internal/inode.js';
+import '../polyfills.js';
+type _MessageEvent<T = any> = T | {
+    data: T;
+};
+/** @internal */
+export interface RPCPort {
+    postMessage(value: unknown, transfer?: TransferListItem[]): void;
+    on?(event: 'message' | 'online', listener: (value: unknown) => void): this;
+    off?(event: 'message', listener: (value: unknown) => void): this;
+    addEventListener?(type: 'message', listener: (ev: _MessageEvent) => void): void;
+    removeEventListener?(type: 'message', listener: (ev: _MessageEvent) => void): void;
+}
+/**
+ * The options for the Port backend
+ * @category Backends and Configuration
+ */
+export interface PortOptions {
+    /**
+     * The target port that you want to connect to, or the current port if in a port context.
+     */
+    port: RPCPort;
+    /**
+     * How long to wait for a request to complete
+     */
+    timeout?: number;
+}
+/**
+ * The API for remote procedure calls
+ * @category Internals
+ * @internal
+ */
+export interface RPCMethods {
+    usage(): UsageInfo;
+    ready(): void;
+    rename(oldPath: string, newPath: string): void;
+    createFile(path: string, options: CreationOptions): Uint8Array;
+    unlink(path: string): void;
+    rmdir(path: string): void;
+    mkdir(path: string, options: CreationOptions): Uint8Array;
+    readdir(path: string): string[];
+    touch(path: string, metadata: Uint8Array): void;
+    exists(path: string): boolean;
+    link(target: string, link: string): void;
+    sync(path: string): void;
+    read(path: string, buffer: Uint8Array, start: number, end: number): Uint8Array;
+    write(path: string, buffer: Uint8Array, offset: number): void;
+    stat(path: string): Uint8Array;
+}
+/**
+ * The methods that can be called on the RPC port
+ * @category Internals
+ * @internal
+ */
+export type RPCMethod = keyof RPCMethods;
+/**
+ * An RPC message
+ * @category Internals
+ * @internal
+ */
+export interface RPCMessage {
+    _zenfs: true;
+    id: string;
+    method: RPCMethod;
+    stack: string;
+}
+interface RPCRequest<TMethod extends RPCMethod = RPCMethod> extends RPCMessage {
+    method: TMethod;
+    args: Parameters<RPCMethods[TMethod]>;
+}
+export declare function attach<T extends RPCMessage>(port: RPCPort, handler: (message: T) => unknown): void;
+export declare function detach<T extends RPCMessage>(port: RPCPort, handler: (message: T) => unknown): void;
+export declare function catchMessages<T extends Backend>(port: RPCPort): (fs: FilesystemOf<T>) => Promise<void>;
+/**
+ * @internal
+ */
+export declare function waitOnline(port: RPCPort): Promise<void>;
+declare const PortFS_base: import("../index.js").Mixin<typeof FileSystem, import("../mixins/async.js").AsyncMixin>;
+/**
+ * PortFS lets you access an FS instance that is running in a port, or the other way around.
+ *
+ * Note that *direct* synchronous operations are not permitted on the PortFS,
+ * regardless of the configuration option of the remote FS.
+ * @category Internals
+ * @internal
+ */
+export declare class PortFS extends PortFS_base {
+    readonly options: PortOptions;
+    readonly port: RPCPort;
+    /**`
+     * @hidden
+     */
+    _sync: import("./index.js").StoreFS<import("./memory.js").InMemoryStore>;
+    /**
+     * Constructs a new PortFS instance that connects with the FS running on `options.port`.
+     */
+    constructor(options: PortOptions);
+    protected rpc<const T extends RPCMethod>(method: T, ...args: Parameters<RPCMethods[T]>): Promise<Awaited<ReturnType<RPCMethods[T]>>>;
+    ready(): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    stat(path: string): Promise<Inode>;
+    touch(path: string, metadata: InodeLike | Inode): Promise<void>;
+    sync(path: string): Promise<void>;
+    createFile(path: string, options: CreationOptions): Promise<Inode>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    mkdir(path: string, options: CreationOptions): Promise<Inode>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    link(srcpath: string, dstpath: string): Promise<void>;
+    read(path: string, buffer: Uint8Array, start: number, end: number): Promise<void>;
+    write(path: string, buffer: Uint8Array, offset: number): Promise<void>;
+}
+/** @internal */
+export declare function handleRequest(port: RPCPort, fs: FileSystem & {
+    _descriptors?: Map<number, File>;
+}, request: RPCRequest): Promise<void>;
+export declare function attachFS(port: RPCPort, fs: FileSystem): void;
+export declare function detachFS(port: RPCPort, fs: FileSystem): void;
+declare const _Port: {
+    name: string;
+    options: {
+        port: {
+            type: (arg: RPCPort) => boolean;
+            required: true;
+        };
+        timeout: {
+            type: string;
+            required: false;
+        };
+    };
+    create(options: PortOptions): PortFS;
+};
+type _Port = typeof _Port;
+/**
+ * @category Backends and Configuration
+ */
+export interface Port extends _Port {
+}
+/**
+ * A backend for usage with ports and workers. See the examples below.
+ *
+ * #### Accessing an FS on a remote Worker from the main thread
+ *
+ * Main:
+ *
+ * ```ts
+ * import { configure } from '@zenfs/core';
+ * import { Port } from '@zenfs/port';
+ * import { Worker } from 'node:worker_threads';
+ *
+ * const worker = new Worker('worker.js');
+ *
+ * await configure({
+ * 	mounts: {
+ * 		'/worker': {
+ * 			backend: Port,
+ * 			port: worker,
+ * 		},
+ * 	},
+ * });
+ * ```
+ *
+ * Worker:
+ *
+ * ```ts
+ * import { InMemory, resolveRemoteMount, attachFS } from '@zenfs/core';
+ * import { parentPort } from 'node:worker_threads';
+ *
+ * await resolveRemoteMount(parentPort, { backend: InMemory, name: 'tmp' });
+ * ```
+ *
+ * If you are using using web workers, you would use `self` instead of importing `parentPort` in the worker, and would not need to import `Worker` in the main thread.
+ *
+ * #### Using with multiple ports on the same thread
+ *
+ * ```ts
+ * import { InMemory, fs, resolveMountConfig, resolveRemoteMount, Port } from '@zenfs/core';
+ * import { MessageChannel } from 'node:worker_threads';
+ *
+ * const { port1: localPort, port2: remotePort } = new MessageChannel();
+ *
+ * fs.mount('/remote', await resolveRemoteMount(remotePort, { backend: InMemory, name: 'tmp' }));
+ * fs.mount('/port', await resolveMountConfig({ backend: Port, port: localPort }));
+ *
+ * const content = 'FS is in a port';
+ *
+ * await fs.promises.writeFile('/port/test', content);
+ *
+ * fs.readFileSync('/remote/test', 'utf8'); // FS is in a port
+ * await fs.promises.readFile('/port/test', 'utf8'); // FS is in a port
+ * ```
+ *
+ * @category Backends and Configuration
+ */
+export declare const Port: Port;
+/**
+ * @category Backends and Configuration
+ */
+export declare function resolveRemoteMount<T extends Backend>(port: RPCPort, config: MountConfiguration<T>, _depth?: number): Promise<FilesystemOf<T>>;
+export {};