@zenfs/dom 0.2.0 → 0.2.2

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+import { ApiError } from '@zenfs/core';
+/**
+ * Handles converting errors, then rethrowing them
+ */
+export declare function convertException(ex: Error | ApiError | DOMException, path?: string, syscall?: string): ApiError;

package/dist/utils.js

@@ -0,0 +1,67 @@
+import { ApiError, ErrorCode } from '@zenfs/core';
+/**
+ * Converts a DOMException into an ErrorCode
+ * @see https://developer.mozilla.org/Web/API/DOMException
+ */
+function errnoForDOMException(ex) {
+    switch (ex.name) {
+        case 'IndexSizeError':
+        case 'HierarchyRequestError':
+        case 'InvalidCharacterError':
+        case 'InvalidStateError':
+        case 'SyntaxError':
+        case 'NamespaceError':
+        case 'TypeMismatchError':
+        case 'ConstraintError':
+        case 'VersionError':
+        case 'URLMismatchError':
+        case 'InvalidNodeTypeError':
+            return 'EINVAL';
+        case 'WrongDocumentError':
+            return 'EXDEV';
+        case 'NoModificationAllowedError':
+        case 'InvalidModificationError':
+        case 'InvalidAccessError':
+        case 'SecurityError':
+        case 'NotAllowedError':
+            return 'EACCES';
+        case 'NotFoundError':
+            return 'ENOENT';
+        case 'NotSupportedError':
+            return 'ENOTSUP';
+        case 'InUseAttributeError':
+            return 'EBUSY';
+        case 'NetworkError':
+            return 'ENETDOWN';
+        case 'AbortError':
+            return 'EINTR';
+        case 'QuotaExceededError':
+            return 'ENOSPC';
+        case 'TimeoutError':
+            return 'ETIMEDOUT';
+        case 'ReadOnlyError':
+            return 'EROFS';
+        case 'DataCloneError':
+        case 'EncodingError':
+        case 'NotReadableError':
+        case 'DataError':
+        case 'TransactionInactiveError':
+        case 'OperationError':
+        case 'UnknownError':
+        default:
+            return 'EIO';
+    }
+}
+/**
+ * Handles converting errors, then rethrowing them
+ */
+export function convertException(ex, path, syscall) {
+    if (ex instanceof ApiError) {
+        return ex;
+    }
+    const code = ex instanceof DOMException ? ErrorCode[errnoForDOMException(ex)] : ErrorCode.EIO;
+    const error = new ApiError(code, ex.message, path, syscall);
+    error.stack = ex.stack;
+    error.cause = ex.cause;
+    return error;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@zenfs/dom",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "DOM backends for ZenFS",
 	"main": "dist/index.js",
-	"types": "dist",
+	"types": "src/index.ts",
 	"keywords": [
 		"filesystem",
 		"node",
@@ -27,13 +27,6 @@
 		".": "./dist/index.js",
 		"./*": "./dist/*"
 	},
-	"typesVersions": {
-		"*": {
-			"*": [
-				"./dist/*"
-			]
-		}
-	},
 	"scripts": {
 		"format": "prettier --write .",
 		"format:check": "prettier --check .",
@@ -44,8 +37,8 @@
 	},
 	"devDependencies": {
 		"@fal-works/esbuild-plugin-global-externals": "^2.1.2",
-		"@typescript-eslint/eslint-plugin": "^5.55.0",
-		"@typescript-eslint/parser": "^5.55.0",
+		"@typescript-eslint/eslint-plugin": "^7.7.0",
+		"@typescript-eslint/parser": "^7.7.0",
 		"esbuild": "^0.17.18",
 		"eslint": "^8.36.0",
 		"prettier": "^3.2.5",
@@ -53,6 +46,6 @@
 		"typescript": "5.2.2"
 	},
 	"peerDependencies": {
-		"@zenfs/core": "^0.7.0"
+		"@zenfs/core": "^0.8.1"
 	}
 }

package/readme.md

@@ -7,9 +7,9 @@
 
 ## Backends
 
--   `Storage`: Stores files in a `Storage` object, like `localStorage` and `sessionStorage`.
+-   `WebStorage`: Stores files in a `Storage` object, like `localStorage` and `sessionStorage`.
 -   `IndexedDB`: Stores files into an `IndexedDB` object database.
--   `FileSystemAccess`: Store files using the [Web File System API](https://developer.mozilla.org/Web/API/File_System_API).
+-   `WebAccess`: Store files using the [Web File System API](https://developer.mozilla.org/Web/API/File_System_API).
 
 For more information, see the [API documentation](https://zen-fs.github.io/dom).
 
@@ -20,9 +20,9 @@ For more information, see the [API documentation](https://zen-fs.github.io/dom).
 
 ```js
 import { configure, fs } from '@zenfs/core';
-import { Storage } from '@zenfs/dom';
+import { WebStorage } from '@zenfs/dom';
 
-await configure({ backend: Storage, storage: localStorage });
+await configure({ backend: WebStorage, storage: localStorage });
 
 if (!fs.existsSync('/test.txt')) {
 	fs.writeFileSync('/test.txt', 'This will persist across reloads!');

package/src/IndexedDB.ts

@@ -0,0 +1,149 @@
+import type { AsyncStore, AsyncStoreOptions, AsyncTransaction, Backend, Ino } from '@zenfs/core';
+import { AsyncStoreFS } from '@zenfs/core';
+import { convertException } from './utils.js';
+
+function wrap<T>(request: IDBRequest<T>): Promise<T> {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = e => {
+			e.preventDefault();
+			reject(convertException(request.error));
+		};
+	});
+}
+
+/**
+ * @hidden
+ */
+export class IndexedDBTransaction implements AsyncTransaction {
+	constructor(
+		public tx: IDBTransaction,
+		public store: IDBObjectStore
+	) {}
+
+	public get(key: Ino): Promise<Uint8Array> {
+		return wrap<Uint8Array>(this.store.get(key.toString()));
+	}
+
+	/**
+	 * @todo return false when add has a key conflict (no error)
+	 */
+	public async put(key: Ino, data: Uint8Array, overwrite: boolean): Promise<boolean> {
+		await wrap(this.store[overwrite ? 'put' : 'add'](data, key.toString()));
+		return true;
+	}
+
+	public remove(key: Ino): Promise<void> {
+		return wrap(this.store.delete(key.toString()));
+	}
+
+	public async commit(): Promise<void> {
+		return;
+	}
+
+	public async abort(): Promise<void> {
+		try {
+			this.tx.abort();
+		} catch (e) {
+			throw convertException(e);
+		}
+	}
+}
+
+export class IndexedDBStore implements AsyncStore {
+	public static async create(storeName: string, indexedDB: IDBFactory = globalThis.indexedDB): Promise<IndexedDBStore> {
+		const req: IDBOpenDBRequest = indexedDB.open(storeName, 1);
+
+		req.onupgradeneeded = () => {
+			const db: IDBDatabase = req.result;
+			// This should never happen; we're at version 1. Why does another database exist?
+			if (db.objectStoreNames.contains(storeName)) {
+				db.deleteObjectStore(storeName);
+			}
+			db.createObjectStore(storeName);
+		};
+
+		const result = await wrap(req);
+		return new IndexedDBStore(result, storeName);
+	}
+
+	constructor(
+		protected db: IDBDatabase,
+		protected storeName: string
+	) {}
+
+	public get name(): string {
+		return IndexedDB.name + ':' + this.storeName;
+	}
+
+	public clear(): Promise<void> {
+		return wrap(this.db.transaction(this.storeName, 'readwrite').objectStore(this.storeName).clear());
+	}
+
+	public beginTransaction(): IndexedDBTransaction {
+		const tx = this.db.transaction(this.storeName, 'readwrite');
+		return new IndexedDBTransaction(tx, tx.objectStore(this.storeName));
+	}
+}
+
+/**
+ * Configuration options for the IndexedDB file system.
+ */
+export interface IndexedDBOptions extends Omit<AsyncStoreOptions, 'store'> {
+	/**
+	 * The name of this file system. You can have multiple IndexedDB file systems operating at once, but each must have a different name.
+	 */
+	storeName?: string;
+
+	/**
+	 * The IDBFactory to use. Defaults to `globalThis.indexedDB`.
+	 */
+	idbFactory?: IDBFactory;
+}
+
+/**
+ * A file system that uses the IndexedDB key value file system.
+ */
+
+export const IndexedDB = {
+	name: 'IndexedDB',
+
+	options: {
+		storeName: {
+			type: 'string',
+			required: false,
+			description: 'The name of this file system. You can have multiple IndexedDB file systems operating at once, but each must have a different name.',
+		},
+		cacheSize: {
+			type: 'number',
+			required: false,
+			description: 'The size of the inode cache. Defaults to 100. A size of 0 or below disables caching.',
+		},
+		idbFactory: {
+			type: 'object',
+			required: false,
+			description: 'The IDBFactory to use. Defaults to globalThis.indexedDB.',
+		},
+	},
+
+	async isAvailable(idbFactory: IDBFactory = globalThis.indexedDB): Promise<boolean> {
+		try {
+			if (!(idbFactory instanceof IDBFactory)) {
+				return false;
+			}
+			const req = idbFactory.open('__zenfs_test');
+			await wrap(req);
+			idbFactory.deleteDatabase('__zenfs_test');
+			return true;
+		} catch (e) {
+			idbFactory.deleteDatabase('__zenfs_test');
+			return false;
+		}
+	},
+
+	create(options: IndexedDBOptions) {
+		const store = IndexedDBStore.create(options.storeName || 'zenfs', options.idbFactory);
+		const fs = new AsyncStoreFS({ ...options, store });
+		return fs;
+	},
+} as const satisfies Backend;

package/src/Storage.ts

@@ -0,0 +1,85 @@
+import type { Backend, Ino, SimpleSyncStore, SyncStore } from '@zenfs/core';
+import { ApiError, ErrorCode, SimpleSyncTransaction, SyncStoreFS, decode, encode } from '@zenfs/core';
+
+/**
+ * A synchronous key-value store backed by Storage.
+ */
+export class WebStorageStore implements SyncStore, SimpleSyncStore {
+	public get name(): string {
+		return WebStorage.name;
+	}
+
+	constructor(protected _storage: Storage) {}
+
+	public clear(): void {
+		this._storage.clear();
+	}
+
+	public beginTransaction(): SimpleSyncTransaction {
+		// No need to differentiate.
+		return new SimpleSyncTransaction(this);
+	}
+
+	public get(key: Ino): Uint8Array | undefined {
+		const data = this._storage.getItem(key.toString());
+		if (typeof data != 'string') {
+			return;
+		}
+
+		return encode(data);
+	}
+
+	public put(key: Ino, data: Uint8Array, overwrite: boolean): boolean {
+		try {
+			if (!overwrite && this._storage.getItem(key.toString()) !== null) {
+				// Don't want to overwrite the key!
+				return false;
+			}
+			this._storage.setItem(key.toString(), decode(data));
+			return true;
+		} catch (e) {
+			throw new ApiError(ErrorCode.ENOSPC, 'Storage is full.');
+		}
+	}
+
+	public remove(key: Ino): void {
+		try {
+			this._storage.removeItem(key.toString());
+		} catch (e) {
+			throw new ApiError(ErrorCode.EIO, 'Unable to delete key ' + key + ': ' + e);
+		}
+	}
+}
+
+/**
+ * Options to pass to the StorageFileSystem
+ */
+export interface WebStorageOptions {
+	/**
+	 * The Storage to use. Defaults to globalThis.localStorage.
+	 */
+	storage?: Storage;
+}
+
+/**
+ * A synchronous file system backed by a `Storage` (e.g. localStorage).
+ */
+export const WebStorage = {
+	name: 'WebStorage',
+
+	options: {
+		storage: {
+			type: 'object',
+			required: false,
+			description: 'The Storage to use. Defaults to globalThis.localStorage.',
+		},
+	},
+
+	isAvailable(storage: Storage = globalThis.localStorage): boolean {
+		return storage instanceof globalThis.Storage;
+	},
+
+	create({ storage = globalThis.localStorage }: WebStorageOptions) {
+		return new SyncStoreFS({ store: new WebStorageStore(storage) });
+	},
+} as const satisfies Backend;

package/src/access.ts

@@ -0,0 +1,228 @@
+import type { Backend, FileSystemMetadata } from '@zenfs/core';
+import { ApiError, Async, ErrorCode, FileSystem, FileType, InMemory, PreloadFile, Stats } from '@zenfs/core';
+import { basename, dirname, join } from '@zenfs/core/emulation/path.js';
+import { convertException } from './utils.js';
+
+declare global {
+	interface FileSystemDirectoryHandle {
+		[Symbol.iterator](): IterableIterator<[string, FileSystemHandle]>;
+		entries(): IterableIterator<[string, FileSystemHandle]>;
+		keys(): IterableIterator<string>;
+		values(): IterableIterator<FileSystemHandle>;
+	}
+}
+
+export interface WebAccessOptions {
+	handle: FileSystemDirectoryHandle;
+}
+
+export class WebAccessFS extends Async(FileSystem) {
+	private _handles: Map<string, FileSystemHandle> = new Map();
+
+	/**
+	 * @hidden
+	 */
+	_sync: FileSystem;
+
+	public async ready(): Promise<this> {
+		return this;
+	}
+
+	public constructor({ handle }: WebAccessOptions) {
+		super();
+		this._handles.set('/', handle);
+		this._sync = InMemory.create({ name: 'accessfs-cache' });
+	}
+
+	public metadata(): FileSystemMetadata {
+		return {
+			...super.metadata(),
+			name: 'WebAccess',
+		};
+	}
+
+	public async sync(p: string, data: Uint8Array, stats: Stats): Promise<void> {
+		const currentStats = await this.stat(p);
+		if (stats.mtime !== currentStats!.mtime) {
+			await this.writeFile(p, data);
+		}
+	}
+
+	public async rename(oldPath: string, newPath: string): Promise<void> {
+		try {
+			const handle = await this.getHandle(oldPath);
+			if (handle instanceof FileSystemDirectoryHandle) {
+				const files = await this.readdir(oldPath);
+
+				await this.mkdir(newPath);
+				if (files.length == 0) {
+					await this.unlink(oldPath);
+				} else {
+					for (const file of files) {
+						await this.rename(join(oldPath, file), join(newPath, file));
+						await this.unlink(oldPath);
+					}
+				}
+			}
+			if (!(handle instanceof FileSystemFileHandle)) {
+				return;
+			}
+			const oldFile = await handle.getFile(),
+				destFolder = await this.getHandle(dirname(newPath));
+			if (!(destFolder instanceof FileSystemDirectoryHandle)) {
+				return;
+			}
+			const newFile = await destFolder.getFileHandle(basename(newPath), { create: true });
+			const writable = await newFile.createWritable();
+			const buffer = await oldFile.arrayBuffer();
+			await writable.write(buffer);
+
+			writable.close();
+			await this.unlink(oldPath);
+		} catch (ex) {
+			throw convertException(ex, oldPath, 'rename');
+		}
+	}
+
+	public async writeFile(fname: string, data: Uint8Array): Promise<void> {
+		const handle = await this.getHandle(dirname(fname));
+		if (!(handle instanceof FileSystemDirectoryHandle)) {
+			return;
+		}
+
+		const file = await handle.getFileHandle(basename(fname), { create: true });
+		const writable = await file.createWritable();
+		await writable.write(data);
+		await writable.close();
+	}
+
+	public async createFile(path: string, flag: string): Promise<PreloadFile<this>> {
+		await this.writeFile(path, new Uint8Array());
+		return this.openFile(path, flag);
+	}
+
+	public async stat(path: string): Promise<Stats> {
+		const handle = await this.getHandle(path);
+		if (!handle) {
+			throw ApiError.With('ENOENT', path, 'stat');
+		}
+		if (handle instanceof FileSystemDirectoryHandle) {
+			return new Stats({ mode: 0o777 | FileType.DIRECTORY, size: 4096 });
+		}
+		if (handle instanceof FileSystemFileHandle) {
+			const { lastModified, size } = await handle.getFile();
+			return new Stats({ mode: 0o777 | FileType.FILE, size, mtimeMs: lastModified });
+		}
+	}
+
+	public async openFile(path: string, flag: string): Promise<PreloadFile<this>> {
+		const handle = await this.getHandle(path);
+		if (handle instanceof FileSystemFileHandle) {
+			const file = await handle.getFile();
+			const data = new Uint8Array(await file.arrayBuffer());
+			const stats = new Stats({ mode: 0o777 | FileType.FILE, size: file.size, mtimeMs: file.lastModified });
+			return new PreloadFile(this, path, flag, stats, data);
+		}
+	}
+
+	public async unlink(path: string): Promise<void> {
+		const handle = await this.getHandle(dirname(path));
+		if (handle instanceof FileSystemDirectoryHandle) {
+			try {
+				await handle.removeEntry(basename(path), { recursive: true });
+			} catch (ex) {
+				throw convertException(ex, path, 'unlink');
+			}
+		}
+	}
+
+	public async link(srcpath: string): Promise<void> {
+		throw ApiError.With('ENOSYS', srcpath, 'WebAccessFS.link');
+	}
+
+	public async rmdir(path: string): Promise<void> {
+		return this.unlink(path);
+	}
+
+	public async mkdir(path: string): Promise<void> {
+		const existingHandle = await this.getHandle(path);
+		if (existingHandle) {
+			throw ApiError.With('EEXIST', path, 'mkdir');
+		}
+
+		const handle = await this.getHandle(dirname(path));
+		if (handle instanceof FileSystemDirectoryHandle) {
+			await handle.getDirectoryHandle(basename(path), { create: true });
+		}
+	}
+
+	public async readdir(path: string): Promise<string[]> {
+		const handle = await this.getHandle(path);
+		if (!(handle instanceof FileSystemDirectoryHandle)) {
+			throw ApiError.With('ENOTDIR', path, 'readdir');
+		}
+		const _keys: string[] = [];
+		for await (const key of handle.keys()) {
+			_keys.push(join(path, key));
+		}
+		return _keys;
+	}
+
+	protected async getHandle(path: string): Promise<FileSystemHandle> {
+		if (this._handles.has(path)) {
+			return this._handles.get(path);
+		}
+
+		let walked = '/';
+
+		for (const part of path.split('/').slice(1)) {
+			const handle = this._handles.get(walked);
+			if (!(handle instanceof FileSystemDirectoryHandle)) {
+				throw ApiError.With('ENOTDIR', walked, 'getHandle');
+			}
+			walked = join(walked, part);
+
+			try {
+				const dirHandle = await handle.getDirectoryHandle(part);
+				this._handles.set(walked, dirHandle);
+			} catch (ex) {
+				if (ex.name == 'TypeMismatchError') {
+					try {
+						const fileHandle = await handle.getFileHandle(part);
+						this._handles.set(walked, fileHandle);
+					} catch (ex) {
+						convertException(ex, walked, 'getHandle');
+					}
+				}
+
+				if (ex.name === 'TypeError') {
+					throw new ApiError(ErrorCode.ENOENT, ex.message, walked, 'getHandle');
+				}
+
+				convertException(ex, walked, 'getHandle');
+			}
+		}
+
+		return this._handles.get(path);
+	}
+}
+
+export const WebAccess = {
+	name: 'WebAccess',
+
+	options: {
+		handle: {
+			type: 'object',
+			required: true,
+			description: 'The directory handle to use for the root',
+		},
+	},
+
+	isAvailable(): boolean {
+		return typeof FileSystemHandle == 'function';
+	},
+
+	create(options: WebAccessOptions) {
+		return new WebAccessFS(options);
+	},
+} as const satisfies Backend;

package/src/index.ts

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

package/src/utils.ts

@@ -0,0 +1,70 @@
+import { ApiError, ErrorCode } from '@zenfs/core';
+
+/**
+ * Converts a DOMException into an ErrorCode
+ * @see https://developer.mozilla.org/Web/API/DOMException
+ */
+function errnoForDOMException(ex: DOMException): keyof typeof ErrorCode {
+	switch (ex.name) {
+		case 'IndexSizeError':
+		case 'HierarchyRequestError':
+		case 'InvalidCharacterError':
+		case 'InvalidStateError':
+		case 'SyntaxError':
+		case 'NamespaceError':
+		case 'TypeMismatchError':
+		case 'ConstraintError':
+		case 'VersionError':
+		case 'URLMismatchError':
+		case 'InvalidNodeTypeError':
+			return 'EINVAL';
+		case 'WrongDocumentError':
+			return 'EXDEV';
+		case 'NoModificationAllowedError':
+		case 'InvalidModificationError':
+		case 'InvalidAccessError':
+		case 'SecurityError':
+		case 'NotAllowedError':
+			return 'EACCES';
+		case 'NotFoundError':
+			return 'ENOENT';
+		case 'NotSupportedError':
+			return 'ENOTSUP';
+		case 'InUseAttributeError':
+			return 'EBUSY';
+		case 'NetworkError':
+			return 'ENETDOWN';
+		case 'AbortError':
+			return 'EINTR';
+		case 'QuotaExceededError':
+			return 'ENOSPC';
+		case 'TimeoutError':
+			return 'ETIMEDOUT';
+		case 'ReadOnlyError':
+			return 'EROFS';
+		case 'DataCloneError':
+		case 'EncodingError':
+		case 'NotReadableError':
+		case 'DataError':
+		case 'TransactionInactiveError':
+		case 'OperationError':
+		case 'UnknownError':
+		default:
+			return 'EIO';
+	}
+}
+
+/**
+ * Handles converting errors, then rethrowing them
+ */
+export function convertException(ex: Error | ApiError | DOMException, path?: string, syscall?: string): ApiError {
+	if (ex instanceof ApiError) {
+		return ex;
+	}
+
+	const code = ex instanceof DOMException ? ErrorCode[errnoForDOMException(ex)] : ErrorCode.EIO;
+	const error = new ApiError(code, ex.message, path, syscall);
+	error.stack = ex.stack;
+	error.cause = ex.cause;
+	return error;
+}