@zenfs/dom 1.0.6 → 1.1.0

package/dist/IndexedDB.d.ts

@@ -1,5 +1,5 @@
-import type { SharedConfig, Store } from '@zenfs/core';
-import { Async, AsyncTransaction, StoreFS } from '@zenfs/core';
+import type { AsyncMixin, SharedConfig, Store } from '@zenfs/core';
+import { AsyncTransaction, StoreFS } from '@zenfs/core';
 /**
  * @hidden
  */
@@ -53,10 +53,10 @@ declare const _IndexedDB: {
         };
     };
     readonly isAvailable: (idbFactory?: IDBFactory) => Promise<boolean>;
-    readonly create: (options: IndexedDBOptions & Partial<SharedConfig>) => Promise<Async & StoreFS<IndexedDBStore>>;
+    readonly create: (options: IndexedDBOptions & Partial<SharedConfig>) => Promise<AsyncMixin & StoreFS<IndexedDBStore>>;
 };
 type _IndexedDB = typeof _IndexedDB;
-interface IndexedDB extends _IndexedDB {
+export interface IndexedDB extends _IndexedDB {
 }
 export declare const IndexedDB: IndexedDB;
 export {};

package/dist/access.d.ts

@@ -1,9 +1,9 @@
 import type { FileSystemMetadata } from '@zenfs/core';
-import { Async, FileSystem, PreloadFile, Stats } from '@zenfs/core';
+import { FileSystem, PreloadFile, Stats } from '@zenfs/core';
 export interface WebAccessOptions {
     handle: FileSystemDirectoryHandle;
 }
-declare const WebAccessFS_base: import("@zenfs/core").Mixin<typeof FileSystem, Async>;
+declare const WebAccessFS_base: import("@zenfs/core").Mixin<typeof FileSystem, import("@zenfs/core").AsyncMixin>;
 export declare class WebAccessFS extends WebAccessFS_base {
     private _handles;
     /**
@@ -31,14 +31,13 @@ declare const _WebAccess: {
         readonly handle: {
             readonly type: "object";
             readonly required: true;
-            readonly description: "The directory handle to use for the root";
         };
     };
     readonly isAvailable: () => boolean;
     readonly create: (options: WebAccessOptions) => WebAccessFS;
 };
 type _WebAccess = typeof _WebAccess;
-interface WebAccess extends _WebAccess {
+export interface WebAccess extends _WebAccess {
 }
 export declare const WebAccess: WebAccess;
 export {};

package/dist/access.js

@@ -2,6 +2,13 @@ import { Async, Errno, ErrnoError, FileSystem, InMemory, PreloadFile, Stats } fr
 import { S_IFDIR, S_IFREG } from '@zenfs/core/emulation/constants.js';
 import { basename, dirname, join } from '@zenfs/core/emulation/path.js';
 import { convertException } from './utils.js';
+function isResizable(buffer) {
+    if (buffer instanceof ArrayBuffer)
+        return buffer.resizable;
+    if (buffer instanceof SharedArrayBuffer)
+        return buffer.growable;
+    return false;
+}
 export class WebAccessFS extends Async(FileSystem) {
     constructor(handle) {
         super();
@@ -55,7 +62,7 @@ export class WebAccessFS extends Async(FileSystem) {
         await this.unlink(oldPath);
     }
     async writeFile(path, data) {
-        if (data.buffer.resizable) {
+        if (isResizable(data.buffer)) {
             throw new ErrnoError(Errno.EINVAL, 'Resizable buffers can not be written', path, 'write');
         }
         const handle = await this.getHandle(dirname(path));
@@ -171,11 +178,7 @@ export class WebAccessFS extends Async(FileSystem) {
 const _WebAccess = {
     name: 'WebAccess',
     options: {
-        handle: {
-            type: 'object',
-            required: true,
-            description: 'The directory handle to use for the root',
-        },
+        handle: { type: 'object', required: true },
     },
     isAvailable() {
         return typeof FileSystemHandle == 'function';

package/dist/devices/dsp.js

@@ -40,14 +40,15 @@ export async function dsp(options = {}) {
     });
     return {
         name: 'dsp',
-        init() {
+        singleton: true,
+        init(ino, options) {
             return { data: dsp, major: 14, minor: 3 };
         },
         read() {
             return 0;
         },
         write(file, data) {
-            dsp.port.postMessage(data.buffer);
+            file.device.data.port.postMessage(data.buffer);
             return data.byteLength;
         },
     };

package/dist/devices/framebuffer.d.ts

@@ -2,4 +2,12 @@ import type { DeviceDriver } from '@zenfs/core';
 export interface FramebufferOptions {
     canvas?: HTMLCanvasElement | null;
 }
-export declare function framebuffer({ canvas }?: FramebufferOptions): DeviceDriver<CanvasRenderingContext2D>;
+/**
+ * A frame buffer
+ *
+ * Setup:
+ * ```
+ * addDevice(framebuffer, { canvas: document.querySelector('#your-canvas') })
+ * ```
+ */
+export declare const framebuffer: DeviceDriver<CanvasRenderingContext2D>;

package/dist/devices/framebuffer.js

@@ -1,30 +1,36 @@
-/* Credit: David Konsumer */
 import { Errno, ErrnoError } from '@zenfs/core';
 let framebufferN = 0;
-export function framebuffer({ canvas } = {}) {
-    if (!canvas) {
-        canvas = document.createElement('canvas');
-        document.body.appendChild(canvas);
-    }
-    const ctx = canvas.getContext('2d');
-    if (!ctx) {
-        throw new ErrnoError(Errno.EIO, 'Could not get context from canvas whilst initializing frame buffer.');
-    }
-    return {
-        name: 'framebuffer',
-        init() {
-            return { data: ctx, major: 29, minor: framebufferN++ };
-        },
-        read() {
+/**
+ * A frame buffer
+ *
+ * Setup:
+ * ```
+ * addDevice(framebuffer, { canvas: document.querySelector('#your-canvas') })
+ * ```
+ */
+export const framebuffer = {
+    name: 'framebuffer',
+    init(ino, { canvas } = {}) {
+        if (!canvas) {
+            canvas = document.createElement('canvas');
+            document.body.appendChild(canvas);
+        }
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new ErrnoError(Errno.EIO, 'Could not get context from canvas whilst initializing frame buffer.');
+        }
+        return { data: ctx, major: 29, minor: framebufferN++, name: 'fb' };
+    },
+    read() {
+        return 0;
+    },
+    write(file, data) {
+        const { width, height } = file.device.data.canvas;
+        if (data.byteLength < 4 * width * height) {
             return 0;
-        },
-        write(file, data) {
-            if (data.byteLength < 4 * canvas.width * canvas.height) {
-                return 0;
-            }
-            const imageData = new ImageData(new Uint8ClampedArray(data), canvas.width, canvas.height);
-            ctx.putImageData(imageData, 0, 0);
-            return data.byteLength;
-        },
-    };
-}
+        }
+        const imageData = new ImageData(new Uint8ClampedArray(data), width, height);
+        file.device.data.putImageData(imageData, 0, 0);
+        return data.byteLength;
+    },
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './access.js';
 export * from './IndexedDB.js';
-export * from './Storage.js';
+export * from './storage.js';
+export * from './xml.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './access.js';
 export * from './IndexedDB.js';
-export * from './Storage.js';
+export * from './storage.js';
+export * from './xml.js';

package/dist/{Storage.d.ts → storage.d.ts}

@@ -34,7 +34,6 @@ declare const _WebStorage: {
         readonly storage: {
             readonly type: "object";
             readonly required: false;
-            readonly description: "The Storage to use. Defaults to globalThis.localStorage.";
         };
     };
     /**
@@ -44,7 +43,7 @@ declare const _WebStorage: {
     readonly create: ({ storage }: WebStorageOptions) => StoreFS<WebStorageStore>;
 };
 type _WebStorage = typeof _WebStorage;
-interface WebStorage extends _WebStorage {
+export interface WebStorage extends _WebStorage {
 }
 export declare const WebStorage: WebStorage;
 export {};

package/dist/{Storage.js → storage.js}

@@ -9,6 +9,7 @@ export class WebStorageStore {
     constructor(storage) {
         this.storage = storage;
     }
+    /* node:coverage ignore next 10 */
     clear() {
         this.storage.clear();
     }
@@ -17,7 +18,6 @@ export class WebStorageStore {
     }
     async sync() { }
     transaction() {
-        // No need to differentiate.
         return new SimpleTransaction(this);
     }
     keys() {
@@ -53,11 +53,7 @@ export class WebStorageStore {
 const _WebStorage = {
     name: 'WebStorage',
     options: {
-        storage: {
-            type: 'object',
-            required: false,
-            description: 'The Storage to use. Defaults to globalThis.localStorage.',
-        },
+        storage: { type: 'object', required: false },
     },
     /**
      * @todo Consider replacing `instanceof` with a duck-typing check?

package/dist/xml.d.ts

@@ -0,0 +1,54 @@
+import type { File, StatsLike } from '@zenfs/core';
+import { FileSystem, Stats } from '@zenfs/core';
+export interface XMLOptions {
+    /**
+     * The root `fs` element
+     */
+    root?: Element;
+}
+declare const XMLFS_base: import("@zenfs/core").Mixin<typeof FileSystem, import("utilium").ExtractProperties<FileSystem, (...args: any[]) => Promise<unknown>>>;
+export declare class XMLFS extends XMLFS_base {
+    /**
+     * @inheritdoc XMLOptions.root
+     */
+    readonly root: Element;
+    constructor(
+    /**
+     * @inheritdoc XMLOptions.root
+     */
+    root?: Element);
+    renameSync(oldPath: string, newPath: string): void;
+    statSync(path: string): Stats;
+    openFileSync(path: string, flag: string): File;
+    createFileSync(path: string, flag: string, mode: number): File;
+    unlinkSync(path: string): void;
+    rmdirSync(path: string): void;
+    mkdirSync(path: string, mode: number): void;
+    readdirSync(path: string): string[];
+    linkSync(target: string, link: string): void;
+    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+    toString(): string;
+    protected get(syscall: string, path: string): Element;
+    protected create(syscall: string, path: string, stats?: Partial<StatsLike<number>>): Element;
+    protected add(syscall: string, node: Element, path: string, contents?: boolean): void;
+    protected remove(syscall: string, node: Element, path: string, contents?: boolean): void;
+}
+declare const _XML: {
+    name: string;
+    options: {
+        root: {
+            type: "object";
+            required: false;
+        };
+    };
+    isAvailable(): boolean;
+    create(options: XMLOptions): XMLFS;
+};
+type _XML = typeof _XML;
+export interface XML extends _XML {
+}
+/**
+ * @experimental
+ */
+export declare const XML: XML;
+export {};

package/dist/xml.js

@@ -0,0 +1,177 @@
+import { decodeRaw, encodeRaw, Errno, ErrnoError, FileSystem, PreloadFile, Stats, Sync } from '@zenfs/core';
+import { S_IFDIR, S_IFREG } from '@zenfs/core/emulation/constants.js';
+import { basename, dirname } from '@zenfs/core/path';
+const statsLikeKeys = ['size', 'mode', 'atimeMs', 'mtimeMs', 'ctimeMs', 'birthtimeMs', 'uid', 'gid', 'ino', 'nlink'];
+function get_stats(node) {
+    const stats = {};
+    for (const key of statsLikeKeys) {
+        const value = node.getAttribute(key);
+        stats[key] = value != null ? parseInt(value, 16) : undefined;
+    }
+    return new Stats(stats);
+}
+function set_stats(node, stats) {
+    for (const key of statsLikeKeys) {
+        if (stats[key] != undefined) {
+            node.setAttribute(key, stats[key].toString(16));
+        }
+    }
+}
+function get_paths(node, contents = false) {
+    let paths;
+    try {
+        const raw = contents ? node.textContent : node.getAttribute('paths');
+        paths = JSON.parse(raw || '[]');
+    }
+    catch {
+        paths = [];
+    }
+    return paths;
+}
+export class XMLFS extends Sync(FileSystem) {
+    constructor(
+    /**
+     * @inheritdoc XMLOptions.root
+     */
+    root = new DOMParser().parseFromString('<fs></fs>', 'application/xml').documentElement) {
+        super();
+        this.root = root;
+        try {
+            this.mkdirSync('/', 0o777);
+        }
+        catch (e) {
+            const error = e;
+            if (error.code != 'EEXIST')
+                throw error;
+        }
+    }
+    renameSync(oldPath, newPath) {
+        const node = this.get('rename', oldPath);
+        this.remove('rename', node, oldPath);
+        this.add('rename', node, newPath);
+    }
+    statSync(path) {
+        return get_stats(this.get('stat', path));
+    }
+    openFileSync(path, flag) {
+        const node = this.get('openFile', path);
+        return new PreloadFile(this, path, flag, get_stats(node), encodeRaw(node.textContent));
+    }
+    createFileSync(path, flag, mode) {
+        const stats = new Stats({ mode: mode | S_IFREG });
+        this.create('createFile', path, stats);
+        return new PreloadFile(this, path, flag, stats);
+    }
+    unlinkSync(path) {
+        const node = this.get('unlink', path);
+        if (get_stats(node).isDirectory())
+            throw ErrnoError.With('EISDIR', path, 'unlink');
+        this.remove('unlink', node, path);
+    }
+    rmdirSync(path) {
+        const node = this.get('rmdir', path);
+        if (node.textContent?.length)
+            throw ErrnoError.With('ENOTEMPTY', path, 'rmdir');
+        if (!get_stats(node).isDirectory())
+            throw ErrnoError.With('ENOTDIR', path, 'rmdir');
+        this.remove('rmdir', node, path);
+    }
+    mkdirSync(path, mode) {
+        const node = this.create('mkdir', path, { mode: mode | S_IFDIR });
+        node.textContent = '[]';
+    }
+    readdirSync(path) {
+        const node = this.get('readdir', path);
+        if (!get_stats(node).isDirectory())
+            throw ErrnoError.With('ENOTDIR', path, 'rmdir');
+        try {
+            return JSON.parse(node.textContent);
+        }
+        catch (e) {
+            throw new ErrnoError(Errno.EIO, 'Invalid directory listing: ' + e, path, 'readdir');
+        }
+    }
+    linkSync(target, link) {
+        const node = this.get('link', target);
+        this.add('link', node, link);
+    }
+    syncSync(path, data, stats) {
+        const node = this.get('sync', path);
+        node.textContent = decodeRaw(data);
+        set_stats(node, stats);
+    }
+    toString() {
+        return new XMLSerializer().serializeToString(this.root);
+    }
+    get(syscall, path) {
+        const nodes = this.root.children;
+        if (!nodes)
+            throw ErrnoError.With('EIO', path, syscall);
+        for (let i = 0; i < nodes.length; i++) {
+            if (get_paths(nodes[i]).includes(path))
+                return nodes[i];
+        }
+        throw ErrnoError.With('ENOENT', path, syscall);
+    }
+    create(syscall, path, stats = {}) {
+        if (this.existsSync(path))
+            throw ErrnoError.With('EEXIST', path, syscall);
+        const node = document.createElement('file');
+        this.add(syscall, node, path);
+        set_stats(node, new Stats(stats));
+        this.root.append(node);
+        return node;
+    }
+    add(syscall, node, path, contents = false) {
+        const paths = get_paths(node, contents);
+        paths.push(path);
+        if (contents) {
+            node.textContent = JSON.stringify(paths);
+            return;
+        }
+        node.setAttribute('paths', JSON.stringify(paths));
+        node.setAttribute('nlink', paths.length.toString(16));
+        if (path != '/') {
+            const parent = this.get(syscall, dirname(path));
+            this.add(syscall, parent, basename(path), true);
+        }
+    }
+    remove(syscall, node, path, contents = false) {
+        const paths = get_paths(node, contents);
+        const i = paths.indexOf(path);
+        if (i == -1)
+            return;
+        paths.splice(i, 1);
+        if (contents) {
+            node.textContent = JSON.stringify(paths);
+            return;
+        }
+        if (!paths.length) {
+            node.remove();
+        }
+        else {
+            node.setAttribute('paths', JSON.stringify(paths));
+            node.setAttribute('nlink', paths.length.toString(16));
+        }
+        if (path != '/') {
+            const parent = this.get(syscall, dirname(path));
+            this.remove(syscall, parent, basename(path), true);
+        }
+    }
+}
+const _XML = {
+    name: 'XML',
+    options: {
+        root: { type: 'object', required: false },
+    },
+    isAvailable() {
+        return true;
+    },
+    create(options) {
+        return new XMLFS(options.root);
+    },
+};
+/**
+ * @experimental
+ */
+export const XML = _XML;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/dom",
-	"version": "1.0.6",
+	"version": "1.1.0",
 	"description": "DOM backends for ZenFS",
 	"funding": {
 		"type": "individual",
@@ -50,12 +50,12 @@
 		"globals": "^15.10.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.2",
-		"typedoc": "^0.26.10",
-		"typescript": "^5.5.0",
+		"typedoc": "^0.27.2",
+		"typescript": "^5.7.2",
 		"typescript-eslint": "^8.8.1"
 	},
 	"peerDependencies": {
-		"@zenfs/core": "^1.3.0"
+		"@zenfs/core": "^1.6.4"
 	},
 	"optionalDependencies": {
 		"fake-indexeddb": "^6.0.0",

package/readme.md

@@ -2,8 +2,7 @@
 
 [ZenFS](https://github.com/zen-fs/core) backends for DOM APIs. DOM APIs are _only_ available natively in browsers.
 
-> [!IMPORTANT]
-> Please read the ZenFS core documentation!
+Please read the ZenFS core documentation!
 
 ## Backends
 
@@ -15,10 +14,7 @@ For more information, see the [API documentation](https://zen-fs.github.io/dom).
 
 ## Usage
 
-> [!NOTE]
-> The examples are written in ESM.  
-> For CJS, you can `require` the package.  
-> If using a browser environment, you can use a `<script>` with `type=module` (you may need to use import maps)
+You can use the backends from `@zenfs/dom` just like the backends from `@zenfs/core`:
 
 ```js
 import { configure, fs } from '@zenfs/core';
@@ -33,3 +29,42 @@ if (!fs.existsSync('/test.txt')) {
 const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
 ```
+
+#### `XML`
+
+The `XML` backend can be used to create a file system which lives in the DOM:
+
+```html
+<!-- ... -->
+<fs />
+<!-- ... -->
+```
+
+```js
+import { configure, fs } from '@zenfs/core';
+import { XML } from '@zenfs/dom';
+
+await configureSingle({
+	backend: XML,
+	root: document.querySelector('fs'), // root is optional
+});
+
+fs.writeFileSync('/test.txt', 'This is in the DOM!');
+```
+
+If you choose to add the root element to the DOM by appending it, you will likely want to hide its contents (`display:none` works well).
+
+The `root` option is not required. If you choose not to pass in a `root`, you can always append it to the DOM later:
+
+```js
+import { configure, fs, mounts } from '@zenfs/core';
+import { XML } from '@zenfs/dom';
+
+await configureSingle({ backend: XML });
+
+const { root } = mounts.get('/');
+
+document.body.append(root);
+```
+
+This may disrupt use cases that involve saving the HTML file locally and loading it later, since a new element is created when configuring. In contrast, when using an existing element and passing in a `root`, the existing element's contents will be preserved.