@zenfs/core 1.1.6 → 1.2.1

package/src/backends/fetch.ts

@@ -0,0 +1,180 @@
+import { Errno, ErrnoError } from '../error.js';
+import type { FileSystemMetadata } from '../filesystem.js';
+import type { Stats } from '../stats.js';
+import type { Backend } from './backend.js';
+import { IndexFS } from './file_index.js';
+import type { IndexData } from './file_index.js';
+
+/**
+ * Asynchronously download a file as a buffer or a JSON object.
+ * Note that the third function signature with a non-specialized type is
+ * invalid, but TypeScript requires it when you specialize string arguments to
+ * constants.
+ * @hidden
+ */
+async function fetchFile(path: string, type: 'buffer'): Promise<Uint8Array>;
+async function fetchFile<T extends object>(path: string, type: 'json'): Promise<T>;
+async function fetchFile<T extends object>(path: string, type: 'buffer' | 'json'): Promise<T | Uint8Array>;
+async function fetchFile<T extends object>(path: string, type: string): Promise<T | Uint8Array> {
+	const response = await fetch(path).catch((e: Error) => {
+		throw new ErrnoError(Errno.EIO, e.message, path);
+	});
+	if (!response.ok) {
+		throw new ErrnoError(Errno.EIO, 'fetch failed: response returned code ' + response.status, path);
+	}
+	switch (type) {
+		case 'buffer': {
+			const arrayBuffer = await response.arrayBuffer().catch((e: Error) => {
+				throw new ErrnoError(Errno.EIO, e.message, path);
+			});
+			return new Uint8Array(arrayBuffer);
+		}
+		case 'json':
+			return response.json().catch((e: Error) => {
+				throw new ErrnoError(Errno.EIO, e.message, path);
+			}) as Promise<T>;
+		default:
+			throw new ErrnoError(Errno.EINVAL, 'Invalid download type: ' + type);
+	}
+}
+
+/**
+ * Configuration options for FetchFS.
+ */
+export interface FetchOptions {
+	/**
+	 * URL to a file index as a JSON file or the file index object itself.
+	 * Defaults to `index.json`.
+	 */
+	index?: string | IndexData;
+
+	/** Used as the URL prefix for fetched files.
+	 * Default: Fetch files relative to the index.
+	 */
+	baseUrl?: string;
+}
+
+/**
+ * A simple filesystem backed by HTTP using the `fetch` API.
+ *
+ *
+ * Index objects look like the following:
+ *
+ * ```json
+ * {
+ * 	"version": 1,
+ * 	"entries": {
+ * 		"/home": { ... },
+ * 		"/home/jvilk": { ... },
+ * 		"/home/james": { ... }
+ * 	}
+ * }
+ * ```
+ *
+ * Each entry contains the stats associated with the file.
+ */
+export class FetchFS extends IndexFS {
+	public readonly baseUrl: string;
+
+	public async ready(): Promise<void> {
+		if (this._isInitialized) {
+			return;
+		}
+		await super.ready();
+
+		if (this._disableSync) {
+			return;
+		}
+
+		/**
+		 * Iterate over all of the files and cache their contents
+		 */
+		for (const [path, stats] of this.index.files()) {
+			await this.getData(path, stats);
+		}
+	}
+
+	public constructor({ index = 'index.json', baseUrl = '' }: FetchOptions) {
+		// prefix url must end in a directory separator.
+		if (baseUrl.at(-1) != '/') {
+			baseUrl += '/';
+		}
+
+		super(typeof index != 'string' ? index : fetchFile<IndexData>(baseUrl + index, 'json'));
+
+		this.baseUrl = baseUrl;
+	}
+
+	public metadata(): FileSystemMetadata {
+		return {
+			...super.metadata(),
+			name: FetchFS.name,
+			readonly: true,
+		};
+	}
+
+	/**
+	 * Preload the `path` into the index.
+	 */
+	public preload(path: string, buffer: Uint8Array): void {
+		const stats = this.index.get(path);
+		if (!stats) {
+			throw ErrnoError.With('ENOENT', path, 'preload');
+		}
+		if (!stats.isFile()) {
+			throw ErrnoError.With('EISDIR', path, 'preload');
+		}
+		stats.size = buffer.length;
+		stats.fileData = buffer;
+	}
+
+	/**
+	 * @todo Be lazier about actually requesting the data?
+	 */
+	protected async getData(path: string, stats: Stats): Promise<Uint8Array> {
+		if (stats.fileData) {
+			return stats.fileData;
+		}
+
+		const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer');
+		stats.fileData = data;
+		return data;
+	}
+
+	protected getDataSync(path: string, stats: Stats): Uint8Array {
+		if (stats.fileData) {
+			return stats.fileData;
+		}
+
+		throw new ErrnoError(Errno.ENODATA, '', path, 'getData');
+	}
+}
+
+const _Fetch = {
+	name: 'Fetch',
+
+	options: {
+		index: {
+			type: ['string', 'object'],
+			required: false,
+			description: 'URL to a file index as a JSON file or the file index object itself, generated with the make-index script. Defaults to `index.json`.',
+		},
+		baseUrl: {
+			type: 'string',
+			required: false,
+			description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
+		},
+	},
+
+	isAvailable(): boolean {
+		return typeof globalThis.fetch == 'function';
+	},
+
+	create(options: FetchOptions) {
+		return new FetchFS(options);
+	},
+} as const satisfies Backend<FetchFS, FetchOptions>;
+type _Fetch = typeof _Fetch;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Fetch extends _Fetch {}
+export const Fetch: Fetch = _Fetch;

package/src/backends/file_index.ts

@@ -0,0 +1,206 @@
+/* Note: this file is named file_index.ts because Typescript has special behavior regarding index.ts which can't be disabled. */
+
+import { isJSON } from 'utilium';
+import { basename, dirname } from '../emulation/path.js';
+import { Errno, ErrnoError } from '../error.js';
+import { NoSyncFile, isWriteable } from '../file.js';
+import { FileSystem } from '../filesystem.js';
+import { Readonly } from '../mixins/readonly.js';
+import type { StatsLike } from '../stats.js';
+import { Stats } from '../stats.js';
+import { decodeUTF8, encodeUTF8 } from '../utils.js';
+
+/**
+ * An Index in JSON form
+ * @internal
+ */
+export interface IndexData {
+	version: 1;
+	entries: Record<string, StatsLike<number>>;
+}
+
+export const version = 1;
+
+/**
+ * An index of files
+ * @internal
+ */
+export class Index extends Map<string, Stats> {
+	/**
+	 * Convenience method
+	 */
+	public files(): Map<string, Stats> {
+		const files = new Map<string, Stats>();
+		for (const [path, stats] of this) {
+			if (stats.isFile()) {
+				files.set(path, stats);
+			}
+		}
+		return files;
+	}
+
+	/**
+	 * Converts the index to JSON
+	 */
+	public toJSON(): IndexData {
+		return {
+			version,
+			entries: Object.fromEntries(this),
+		};
+	}
+
+	/**
+	 * Converts the index to a string
+	 */
+	public toString(): string {
+		return JSON.stringify(this.toJSON());
+	}
+
+	/**
+	 * Returns the files in the directory `dir`.
+	 * This is expensive so it is only called once per directory.
+	 */
+	protected dirEntries(dir: string): string[] {
+		const entries = [];
+		for (const entry of this.keys()) {
+			if (dirname(entry) == dir) {
+				entries.push(basename(entry));
+			}
+		}
+		return entries;
+	}
+
+	/**
+	 * Loads the index from JSON data
+	 */
+	public fromJSON(json: IndexData): void {
+		if (json.version != version) {
+			throw new ErrnoError(Errno.EINVAL, 'Index version mismatch');
+		}
+
+		this.clear();
+
+		for (const [path, data] of Object.entries(json.entries)) {
+			const stats = new Stats(data);
+			if (stats.isDirectory()) {
+				stats.fileData = encodeUTF8(JSON.stringify(this.dirEntries(path)));
+			}
+			this.set(path, stats);
+		}
+	}
+
+	/**
+	 * Parses an index from a string
+	 */
+	public static parse(data: string): Index {
+		if (!isJSON(data)) {
+			throw new ErrnoError(Errno.EINVAL, 'Invalid JSON');
+		}
+
+		const json = JSON.parse(data) as IndexData;
+		const index = new Index();
+		index.fromJSON(json);
+		return index;
+	}
+}
+
+export abstract class IndexFS extends Readonly(FileSystem) {
+	protected index: Index = new Index();
+
+	protected _isInitialized: boolean = false;
+
+	public async ready(): Promise<void> {
+		await super.ready();
+		if (this._isInitialized) {
+			return;
+		}
+		this.index.fromJSON(await this.indexData);
+		this._isInitialized = true;
+	}
+
+	public constructor(private indexData: IndexData | Promise<IndexData>) {
+		super();
+	}
+
+	public async reloadFiles(): Promise<void> {
+		for (const [path, stats] of this.index.files()) {
+			delete stats.fileData;
+			stats.fileData = await this.getData(path, stats);
+		}
+	}
+
+	public reloadFilesSync(): void {
+		for (const [path, stats] of this.index.files()) {
+			delete stats.fileData;
+			stats.fileData = this.getDataSync(path, stats);
+		}
+	}
+
+	public stat(path: string): Promise<Stats> {
+		return Promise.resolve(this.statSync(path));
+	}
+
+	public statSync(path: string): Stats {
+		if (!this.index.has(path)) {
+			throw ErrnoError.With('ENOENT', path, 'stat');
+		}
+
+		return this.index.get(path)!;
+	}
+
+	public async openFile(path: string, flag: string): Promise<NoSyncFile<this>> {
+		if (isWriteable(flag)) {
+			// You can't write to files on this file system.
+			throw new ErrnoError(Errno.EPERM, path);
+		}
+
+		// Check if the path exists, and is a file.
+		const stats = this.index.get(path);
+
+		if (!stats) {
+			throw ErrnoError.With('ENOENT', path, 'openFile');
+		}
+
+		return new NoSyncFile(this, path, flag, stats, stats.isDirectory() ? stats.fileData : await this.getData(path, stats));
+	}
+
+	public openFileSync(path: string, flag: string): NoSyncFile<this> {
+		if (isWriteable(flag)) {
+			// You can't write to files on this file system.
+			throw new ErrnoError(Errno.EPERM, path);
+		}
+
+		// Check if the path exists, and is a file.
+		const stats = this.index.get(path);
+
+		if (!stats) {
+			throw ErrnoError.With('ENOENT', path, 'openFile');
+		}
+
+		return new NoSyncFile(this, path, flag, stats, stats.isDirectory() ? stats.fileData : this.getDataSync(path, stats));
+	}
+
+	public readdir(path: string): Promise<string[]> {
+		return Promise.resolve(this.readdirSync(path));
+	}
+
+	public readdirSync(path: string): string[] {
+		// Check if it exists.
+		const stats = this.index.get(path);
+		if (!stats) {
+			throw ErrnoError.With('ENOENT', path, 'readdir');
+		}
+
+		const content: unknown = JSON.parse(decodeUTF8(stats.fileData));
+		if (!Array.isArray(content)) {
+			throw ErrnoError.With('ENODATA', path, 'readdir');
+		}
+		if (!content.every(item => typeof item == 'string')) {
+			throw ErrnoError.With('ENODATA', path, 'readdir');
+		}
+		return content;
+	}
+
+	protected abstract getData(path: string, stats: Stats): Promise<Uint8Array>;
+	protected abstract getDataSync(path: string, stats: Stats): Uint8Array;
+}

package/src/backends/memory.ts

@@ -0,0 +1,50 @@
+import type { Ino } from '../inode.js';
+import type { Backend } from './backend.js';
+import { StoreFS } from './store/fs.js';
+import { SimpleTransaction, type SimpleSyncStore } from './store/simple.js';
+
+/**
+ * A simple in-memory store
+ */
+export class InMemoryStore extends Map<Ino, Uint8Array> implements SimpleSyncStore {
+	public constructor(public name: string = 'tmp') {
+		super();
+	}
+
+	public async sync(): Promise<void> {}
+
+	public clearSync(): void {
+		this.clear();
+	}
+
+	public transaction(): SimpleTransaction {
+		return new SimpleTransaction(this);
+	}
+}
+
+/**
+ * A simple in-memory file system backed by an InMemoryStore.
+ * Files are not persisted across page loads.
+ */
+const _InMemory = {
+	name: 'InMemory',
+	isAvailable(): boolean {
+		return true;
+	},
+	options: {
+		name: {
+			type: 'string',
+			required: false,
+			description: 'The name of the store',
+		},
+	},
+	create({ name }: { name?: string }) {
+		const fs = new StoreFS(new InMemoryStore(name));
+		fs.checkRootSync();
+		return fs;
+	},
+} as const satisfies Backend<StoreFS<InMemoryStore>, { name?: string }>;
+type _InMemory = typeof _InMemory;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface InMemory extends _InMemory {}
+export const InMemory: InMemory = _InMemory;