@zenfs/core 2.2.3 → 2.3.1

package/dist/internal/rpc.d.ts

@@ -0,0 +1,143 @@
+import type { ExceptionJSON } from 'kerium';
+import type { TransferListItem } from 'node:worker_threads';
+import type { WithOptional } from 'utilium';
+import type { Backend, FilesystemOf } from '../backends/backend.js';
+import type { PortFS } from '../backends/port.js';
+import type { CreationOptions, FileSystem, UsageInfo } from '../internal/filesystem.js';
+import '../polyfills.js';
+export interface WebMessagePort {
+    postMessage(value: unknown, transfer?: TransferListItem[]): void;
+    addEventListener(type: 'message', listener: (ev: {
+        data: any;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (ev: {
+        data: any;
+    }) => void): void;
+}
+export interface NodeMessagePort {
+    postMessage(value: unknown, transfer?: TransferListItem[]): void;
+    on(type: 'message', listener: (ev: any) => void): void;
+    off(type: 'message', listener: (ev: any) => void): void;
+}
+export type Channel = NodeMessagePort | WebMessagePort | WebSocket;
+/** @internal */
+export interface Port<T extends Channel = Channel> {
+    readonly channel: T;
+    /** Send a request */
+    send<M extends Message>(message: M, transfer?: TransferListItem[]): void;
+    /** Add a response handler */
+    addHandler<M extends Message>(handler: (message: M) => void): void;
+    /** Remove a response handler */
+    removeHandler<M extends Message>(handler: (message: M) => void): void;
+    /** Remove all handlers */
+    disconnect?(): void;
+}
+export declare function isPort<T extends Channel>(port: unknown): port is Port<T>;
+/**
+ * Creates a new RPC port from a `Worker` or `MessagePort` that extends `EventTarget`
+ */
+export declare function fromWeb<T extends WebMessagePort>(port: T): Port<T>;
+/**
+ * Creates a new RPC port from a Node.js `Worker` or `MessagePort`.
+ */
+export declare function fromNode<T extends NodeMessagePort>(port: T): Port<T>;
+/**
+ * Creates a new RPC port from a WebSocket.
+ * @experimental
+ */
+export declare function fromWebSocket<T extends WebSocket>(ws: T): Port<T>;
+export declare function from<T extends Channel>(port: T | Port<T>): Port<T>;
+/**
+ * The options for the RPC options
+ * @category Backends and Configuration
+ */
+export interface Options {
+    /**
+     * The target port that you want to connect to, or the current port if in a port context.
+     */
+    port: Port;
+    /**
+     * How long to wait for a request to complete
+     */
+    timeout?: number;
+}
+/**
+ * The API for remote procedure calls
+ * @category Internals
+ * @internal
+ */
+export interface Methods {
+    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(): 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 Method = keyof Methods;
+/**
+ * An RPC message
+ * @category Internals
+ * @internal
+ */
+export interface Message {
+    _zenfs: true;
+    id: string;
+    method: Method;
+    stack: string;
+}
+export interface Request<TMethod extends Method = Method> extends Message {
+    method: TMethod;
+    args: Parameters<Methods[TMethod]>;
+}
+export interface Response<TMethod extends Method = Method> extends Message {
+    error?: WithOptional<ExceptionJSON, 'code' | 'errno'>;
+    method: TMethod;
+    value: ReturnType<Methods[TMethod]>;
+}
+/**
+ * Encode a RPC message as a string using JSON.
+ * This is only done when structured cloning is not available.
+ * @internal
+ */
+export declare function encodeMessage(message: Message): string;
+/**
+ * Decode a RPC message from a string using JSON.
+ * This is only done when structured cloning is not available.
+ * @internal
+ */
+export declare function decodeMessage<T extends Message>(message: string): T;
+export declare function isMessage(arg: unknown): arg is Message;
+/**
+ * An RPC executor
+ * @internal @hidden
+ */
+export interface Executor extends PromiseWithResolvers<any> {
+    fs: PortFS;
+    timeout: ReturnType<typeof setTimeout>;
+}
+export declare function request<const TRequest extends Request, TValue>(request: Omit<TRequest, 'id' | 'stack' | '_zenfs'>, { port, timeout: ms, fs }: Partial<Options> & {
+    fs: PortFS;
+}): Promise<TValue>;
+export declare function handleResponse<const TMethod extends Method>(response: Response<TMethod>): void;
+export declare function attach<T extends Message>(port: Port, handler: (message: T) => unknown): void;
+export declare function detach<T extends Message>(port: Port, handler: (message: T) => unknown): void;
+export declare function catchMessages<T extends Backend>(port: Port): (fs: FilesystemOf<T>) => Promise<void>;
+/** @internal */
+export declare function handleRequest(port: Port, fs: FileSystem & {
+    _descriptors?: Map<number, File>;
+}, request: Request): Promise<void>;

package/dist/internal/rpc.js

@@ -0,0 +1,251 @@
+import { Errno, Exception, withErrno } from 'kerium';
+import { err, info, warn } from 'kerium/log';
+import { isJSON, pick } from 'utilium';
+import { Inode } from '../internal/inode.js';
+import '../polyfills.js';
+export function isPort(port) {
+    return port != null && typeof port == 'object' && 'channel' in port && 'send' in port && 'addHandler' in port && 'removeHandler' in port;
+}
+/**
+ * Creates a new RPC port from a `Worker` or `MessagePort` that extends `EventTarget`
+ */
+export function fromWeb(port) {
+    return {
+        channel: port,
+        send: port.postMessage.bind(port),
+        addHandler(handler) {
+            port.addEventListener('message', (event) => handler(event.data));
+        },
+        removeHandler(handler) {
+            port.removeEventListener('message', (event) => handler(event.data));
+        },
+    };
+}
+/**
+ * Creates a new RPC port from a Node.js `Worker` or `MessagePort`.
+ */
+export function fromNode(port) {
+    return {
+        channel: port,
+        send: port.postMessage.bind(port),
+        addHandler: port.on.bind(port, 'message'),
+        removeHandler: port.off.bind(port, 'message'),
+    };
+}
+/**
+ * Creates a new RPC port from a WebSocket.
+ * @experimental
+ */
+export function fromWebSocket(ws) {
+    return {
+        channel: ws,
+        send(message) {
+            ws.send(encodeMessage(message));
+        },
+        addHandler(handler) {
+            ws.addEventListener('message', event => {
+                handler(decodeMessage(event.data));
+            });
+        },
+        removeHandler(handler) {
+            ws.removeEventListener('message', event => {
+                handler(decodeMessage(event.data));
+            });
+        },
+    };
+}
+export function from(port) {
+    if (isPort(port))
+        return port;
+    if (port instanceof WebSocket)
+        return fromWebSocket(port);
+    if ('on' in port)
+        return fromNode(port);
+    if ('addEventListener' in port)
+        return fromWeb(port);
+    throw err(withErrno('EINVAL', 'Invalid port type'));
+}
+/*
+
+Notes on encoding:
+
+
+Buffer prefix ($):
+
+Used to mark when a Uint8Array is encoded into JSON using base64.
+These are encoded "special" since by default it becomes {"0":n,"1":n,...}
+It shouldn't be possible to forge this since all paths start with / and inodes are serialized as buffers
+
+Message prefix and version (Z...):
+
+Used to indicate that this is a ZenFS message, rather than some 3rd party message.
+Immediately following the message prefix is a plain-text version.
+This is used in case the encoding changes in the future, so a client and server with mismatched versions can detect it.
+*/
+const encodingVersion = 1;
+/**
+ * Encode a RPC message as a string using JSON.
+ * This is only done when structured cloning is not available.
+ * @internal
+ */
+export function encodeMessage(message) {
+    return `Z${encodingVersion}${JSON.stringify(message, (key, value) => {
+        if (key == '_zenfs')
+            return; // encoded differently
+        return value instanceof Uint8Array ? '$' + value.toBase64() : value;
+    })}`;
+}
+/**
+ * Decode a RPC message from a string using JSON.
+ * This is only done when structured cloning is not available.
+ * @internal
+ */
+export function decodeMessage(message) {
+    if (!message.startsWith('Z'))
+        return {}; // ignore not-ZenFS messages
+    message = message.slice(1);
+    const v = parseInt(message); // hack so we don't have to figure out how long the version is
+    if (isNaN(v)) {
+        warn('Ignoring encoded message with missing version');
+        return {};
+    }
+    message = message.slice(v.toString().length);
+    if (!isJSON(message)) {
+        warn('Ignoring encoded message with invalid JSON');
+        return {};
+    }
+    if (v != encodingVersion)
+        throw err(withErrno('EPROTONOSUPPORT', `Version mismatch in RPC message encoding (got ${v}, expected ${encodingVersion})`));
+    return {
+        ...JSON.parse(message, (key, value) => (typeof value == 'string' && value.startsWith('$') ? Uint8Array.fromBase64(value.slice(1)) : value)),
+        _zenfs: true,
+    };
+}
+export function isMessage(arg) {
+    return typeof arg == 'object' && arg != null && '_zenfs' in arg && !!arg._zenfs;
+}
+function disposeExecutors(id) {
+    const executor = executors.get(id);
+    if (!executor)
+        return;
+    if (executor.timeout) {
+        clearTimeout(executor.timeout);
+        if (typeof executor.timeout == 'object')
+            executor.timeout.unref();
+    }
+    executor.fs._executors.delete(id);
+    executors.delete(id);
+}
+/**
+ * A map of *all* outstanding RPC requests
+ */
+const executors = new Map();
+export function request(request, { port, timeout: ms = 1000, fs }) {
+    const stack = '\n' + new Error().stack.slice('Error:'.length);
+    if (!port)
+        throw err(withErrno('EINVAL', 'Can not make an RPC request without a port'));
+    const { resolve, reject, promise } = Promise.withResolvers();
+    const id = Math.random().toString(16).slice(10);
+    const timeout = setTimeout(() => {
+        const error = err(withErrno('EIO', 'RPC Failed'));
+        error.stack += stack;
+        disposeExecutors(id);
+        reject(error);
+    }, ms);
+    const executor = { resolve, reject, promise, fs, timeout };
+    fs._executors.set(id, executor);
+    executors.set(id, executor);
+    port.send({ ...request, _zenfs: true, id, stack });
+    return promise;
+}
+// Why Typescript, WHY does the type need to be asserted even when the method is explicitly checked?
+function __requestMethod(req) { }
+function __responseMethod(res, ...t) {
+    return t.includes(res.method);
+}
+export function handleResponse(response) {
+    if (!isMessage(response))
+        return;
+    if (!executors.has(response.id)) {
+        const error = err(withErrno('EIO', 'Invalid RPC id: ' + response.id));
+        error.stack += response.stack;
+        throw error;
+    }
+    const { resolve, reject } = executors.get(response.id);
+    if (response.error) {
+        const e = Exception.fromJSON({ code: 'EIO', errno: Errno.EIO, ...response.error });
+        e.stack += response.stack;
+        disposeExecutors(response.id);
+        reject(e);
+        return;
+    }
+    disposeExecutors(response.id);
+    resolve(__responseMethod(response, 'stat', 'createFile', 'mkdir') ? new Inode(response.value) : response.value);
+    return;
+}
+export function attach(port, handler) {
+    if (!port)
+        throw err(withErrno('EINVAL', 'Cannot attach to non-existent port'));
+    info('Attached handler to port: ' + handler.name);
+    port.addHandler(handler);
+}
+export function detach(port, handler) {
+    if (!port)
+        throw err(withErrno('EINVAL', 'Cannot detach from non-existent port'));
+    info('Detached handler from port: ' + handler.name);
+    port.removeHandler(handler);
+}
+export function catchMessages(port) {
+    const events = [];
+    const handler = events.push.bind(events);
+    attach(port, handler);
+    return async function (fs) {
+        detach(port, handler);
+        for (const event of events) {
+            const request = 'data' in event ? event.data : event;
+            await handleRequest(port, fs, request);
+        }
+    };
+}
+/** @internal */
+export async function handleRequest(port, fs, request) {
+    if (!isMessage(request))
+        return;
+    let value, error;
+    const transferList = [];
+    try {
+        switch (request.method) {
+            case 'read': {
+                __requestMethod(request);
+                const [path, buffer, start, end] = request.args;
+                await fs.read(path, buffer, start, end);
+                value = buffer;
+                break;
+            }
+            case 'stat':
+            case 'createFile':
+            case 'mkdir': {
+                __requestMethod(request);
+                // @ts-expect-error 2556
+                const md = await fs[request.method](...request.args);
+                const inode = md instanceof Inode ? md : new Inode(md);
+                value = new Uint8Array(inode.buffer, inode.byteOffset, inode.byteLength);
+                break;
+            }
+            case 'touch': {
+                __requestMethod(request);
+                const [path, metadata] = request.args;
+                await fs.touch(path, new Inode(metadata));
+                value = undefined;
+                break;
+            }
+            default:
+                // @ts-expect-error 2556
+                value = (await fs[request.method](...request.args));
+        }
+    }
+    catch (e) {
+        error = e instanceof Exception ? e.toJSON() : pick(e, 'message', 'stack');
+    }
+    port.send({ _zenfs: true, ...pick(request, 'id', 'method', 'stack'), error, value }, transferList);
+}

package/dist/mixins/async.js

@@ -28,15 +28,15 @@ export function Async(FS) {
         queueDone() {
             return this.sync();
         }
+        _promise = Promise.resolve();
         _async(promise) {
             this._promise = this._promise.then(() => promise);
         }
+        _isInitialized = false;
+        /** Tracks how many updates to the sync. cache we skipped during initialization */
+        _skippedCacheUpdates = 0;
         constructor(...args) {
             super(...args);
-            this._promise = Promise.resolve();
-            this._isInitialized = false;
-            /** Tracks how many updates to the sync. cache we skipped during initialization */
-            this._skippedCacheUpdates = 0;
             this._patchAsync();
         }
         async ready() {
@@ -191,7 +191,6 @@ export function Async(FS) {
                 // TS does not narrow the union based on the key
                 const originalMethod = this[key].bind(this);
                 this[key] = async (...args) => {
-                    var _a, _b;
                     const result = await originalMethod(...args);
                     const stack = new Error().stack.split('\n').slice(2).join('\n');
                     // From the async queue
@@ -206,7 +205,7 @@ export function Async(FS) {
                     }
                     try {
                         // @ts-expect-error 2556 - The type of `args` is not narrowed
-                        (_b = (_a = this._sync) === null || _a === void 0 ? void 0 : _a[`${key}Sync`]) === null || _b === void 0 ? void 0 : _b.call(_a, ...args);
+                        this._sync?.[`${key}Sync`]?.(...args);
                     }
                     catch (e) {
                         const stack = e.stack.split('\n').slice(3).join('\n');

package/dist/mixins/mutexed.js

@@ -58,17 +58,17 @@ import '../polyfills.js';
  * @internal
  */
 export class MutexLock {
+    previous;
+    current = Promise.withResolvers();
+    _isLocked = true;
     get isLocked() {
         return this._isLocked;
     }
     constructor(previous) {
         this.previous = previous;
-        this.current = Promise.withResolvers();
-        this._isLocked = true;
     }
     async done() {
-        var _a;
-        await ((_a = this.previous) === null || _a === void 0 ? void 0 : _a.done());
+        await this.previous?.done();
         await this.current.promise;
     }
     unlock() {
@@ -84,6 +84,10 @@ export class MutexLock {
  * @category Internals
  */
 export class _MutexedFS {
+    /**
+     * @internal
+     */
+    _fs;
     get type() {
         return this._fs.type;
     }
@@ -114,6 +118,10 @@ export class _MutexedFS {
     usage() {
         return this._fs.usage();
     }
+    /**
+     * The current locks
+     */
+    currentLock;
     /**
      * Adds a lock for a path
      */
@@ -134,11 +142,11 @@ export class _MutexedFS {
         setTimeout(() => {
             if (lock.isLocked) {
                 const error = withErrno('EDEADLK');
-                error.stack += stack === null || stack === void 0 ? void 0 : stack.slice('Error'.length);
+                error.stack += stack?.slice('Error'.length);
                 throw err(error);
             }
         }, 5000);
-        await (previous === null || previous === void 0 ? void 0 : previous.done());
+        await previous?.done();
         return lock;
     }
     /**
@@ -147,8 +155,7 @@ export class _MutexedFS {
      * @internal
      */
     lockSync() {
-        var _a;
-        if ((_a = this.currentLock) === null || _a === void 0 ? void 0 : _a.isLocked) {
+        if (this.currentLock?.isLocked) {
             throw err(withErrno('EBUSY'));
         }
         return this.addLock();
@@ -158,8 +165,7 @@ export class _MutexedFS {
      * @internal
      */
     get isLocked() {
-        var _a;
-        return !!((_a = this.currentLock) === null || _a === void 0 ? void 0 : _a.isLocked);
+        return !!this.currentLock?.isLocked;
     }
     /* eslint-disable @typescript-eslint/no-unused-vars */
     async rename(oldPath, newPath) {

package/dist/path.js

@@ -101,10 +101,9 @@ export function formatExt(ext) {
     return ext ? `${ext[0] === '.' ? '' : '.'}${ext}` : '';
 }
 export function resolve(...parts) {
-    var _a;
     let resolved = '';
-    for (const part of [...parts.reverse(), (_a = this === null || this === void 0 ? void 0 : this.pwd) !== null && _a !== void 0 ? _a : defaultContext.pwd]) {
-        if (!(part === null || part === void 0 ? void 0 : part.length))
+    for (const part of [...parts.reverse(), this?.pwd ?? defaultContext.pwd]) {
+        if (!part?.length)
             continue;
         resolved = `${part}/${resolved}`;
         if (part.startsWith('/')) {
@@ -144,7 +143,7 @@ export function join(...parts) {
     if (!parts.length)
         return '.';
     const joined = parts.join('/');
-    if (!(joined === null || joined === void 0 ? void 0 : joined.length))
+    if (!joined?.length)
         return '.';
     return normalize(joined);
 }

package/dist/polyfills.js

@@ -1,29 +1,58 @@
 /* node:coverage disable */
 /* eslint-disable @typescript-eslint/unbound-method */
-var _a, _b, _c, _d;
-var _e;
 import { warn } from 'kerium/log';
-(_a = Promise.withResolvers) !== null && _a !== void 0 ? _a : (Promise.withResolvers = (warn('Using a polyfill of Promise.withResolvers'),
-    function () {
-        let _resolve, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        _reject;
-        const promise = new Promise((resolve, reject) => {
-            _resolve = resolve;
-            _reject = reject;
+Promise.withResolvers ??=
+    (warn('Using a polyfill of Promise.withResolvers'),
+        function () {
+            let _resolve, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            _reject;
+            const promise = new Promise((resolve, reject) => {
+                _resolve = resolve;
+                _reject = reject;
+            });
+            return { promise, resolve: _resolve, reject: _reject };
         });
-        return { promise, resolve: _resolve, reject: _reject };
-    }));
 // @ts-expect-error 2540
-(_b = Symbol['dispose']) !== null && _b !== void 0 ? _b : (Symbol['dispose'] = (warn('Using a polyfill of Symbol.dispose'), Symbol('Symbol.dispose')));
+Symbol['dispose'] ??= (warn('Using a polyfill of Symbol.dispose'), Symbol('Symbol.dispose'));
 // @ts-expect-error 2540
-(_c = Symbol['asyncDispose']) !== null && _c !== void 0 ? _c : (Symbol['asyncDispose'] = (warn('Using a polyfill of Symbol.asyncDispose'), Symbol('Symbol.asyncDispose')));
-function randomUUID() {
-    const bytes = crypto.getRandomValues(new Uint8Array(16));
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('');
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-(_d = (_e = globalThis.crypto).randomUUID) !== null && _d !== void 0 ? _d : (_e.randomUUID = (warn('Using a polyfill of crypto.randomUUID'), randomUUID));
+Symbol['asyncDispose'] ??= (warn('Using a polyfill of Symbol.asyncDispose'), Symbol('Symbol.asyncDispose'));
+globalThis.crypto.randomUUID ??=
+    (warn('Using a polyfill of crypto.randomUUID'),
+        function randomUUID() {
+            const bytes = crypto.getRandomValues(new Uint8Array(16));
+            bytes[6] = (bytes[6] & 0x0f) | 0x40;
+            bytes[8] = (bytes[8] & 0x3f) | 0x80;
+            const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('');
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        });
+Uint8Array.prototype.toBase64 ??=
+    (warn('Using a polyfill of Uint8Array.prototype.toBase64'),
+        function toBase64() {
+            return btoa(String.fromCharCode(...this));
+        });
+Uint8Array.fromBase64 ??=
+    (warn('Using a polyfill of Uint8Array.fromBase64'),
+        function fromBase64(base64) {
+            const binaryString = atob(base64);
+            const bytes = new Uint8Array(binaryString.length);
+            for (let i = 0; i < binaryString.length; i++) {
+                bytes[i] = binaryString.charCodeAt(i);
+            }
+            return bytes;
+        });
+Uint8Array.prototype.toHex ??=
+    (warn('Using a polyfill of Uint8Array.prototype.toHex'),
+        function toHex() {
+            return [...this].map(b => b.toString(16).padStart(2, '0')).join('');
+        });
+Uint8Array.fromHex ??=
+    (warn('Using a polyfill of Uint8Array.fromHex'),
+        function fromHex(hex) {
+            const bytes = new Uint8Array(hex.length / 2);
+            for (let i = 0; i < hex.length; i += 2) {
+                bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+            }
+            return bytes;
+        });
 /* node:coverage enable */