@zenfs/dom 1.0.7 → 1.1.1

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/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.7",
+	"version": "1.1.1",
 	"description": "DOM backends for ZenFS",
 	"funding": {
 		"type": "individual",
@@ -47,6 +47,8 @@
 	"devDependencies": {
 		"@eslint/js": "^9.12.0",
 		"eslint": "^9.12.0",
+		"fake-indexeddb": "^6.0.0",
+		"file-system-access": "^1.0.4",
 		"globals": "^15.10.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.2",
@@ -57,10 +59,6 @@
 	"peerDependencies": {
 		"@zenfs/core": "^1.6.4"
 	},
-	"optionalDependencies": {
-		"fake-indexeddb": "^6.0.0",
-		"file-system-access": "^1.0.4"
-	},
 	"keywords": [
 		"filesystem",
 		"node",

package/readme.md

@@ -2,23 +2,20 @@
 
 [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
 
--   `WebStorage`: Stores files in a `Storage` object, like `localStorage` and `sessionStorage`.
--   `IndexedDB`: Stores files into an `IndexedDB` object database.
--   `WebAccess`: Store files using the [File System Access API](https://developer.mozilla.org/Web/API/File_System_API).
+-   `WebStorage` stores files in a `Storage` object, like `localStorage` and `sessionStorage`.
+-   `IndexedDB` stores files into an `IndexedDB` object database.
+-   `WebAccess` uses the [File System Access API](https://developer.mozilla.org/Web/API/File_System_API).
+-   `XML` uses an `XMLDocument` to store files, which can be appended to the DOM.
 
 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 +30,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.