@zenfs/core 1.3.6 → 1.4.0

package/src/backends/backend.ts

@@ -1,161 +0,0 @@
-import type { Entries, RequiredKeys } from 'utilium';
-import { ErrnoError, Errno } from '../error.js';
-import type { FileSystem } from '../filesystem.js';
-import { levenshtein } from '../utils.js';
-
-type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
-
-/**
- * Resolves the type of Backend.options from the options interface
- */
-export type OptionsConfig<T> = {
-	[K in keyof T]: {
-		/**
-		 * The basic JavaScript type(s) for this option.
-		 */
-		type: OptionType | readonly OptionType[];
-
-		/**
-		 * Description of the option. Used in error messages and documentation.
-		 * @deprecated
-		 */
-		description?: string;
-
-		/**
-		 * Whether or not the option is required (optional can be set to null or undefined). Defaults to false.
-		 */
-		required: K extends RequiredKeys<T> ? true : false;
-
-		/**
-		 * A custom validation function to check if the option is valid.
-		 * When async, resolves if valid and rejects if not.
-		 * When sync, it will throw an error if not valid.
-		 */
-		validator?(opt: T[K]): void | Promise<void>;
-	};
-};
-
-/**
- * Configuration options shared by backends and `Configuration`
- */
-export interface SharedConfig {
-	/**
-	 * If set, disables the sync cache and sync operations on async file systems.
-	 */
-	disableAsyncCache?: boolean;
-}
-
-/**
- * A backend
- */
-export interface Backend<FS extends FileSystem = FileSystem, TOptions extends object = object> {
-	/**
-	 * Create a new instance of the backend
-	 */
-	create(options: TOptions & Partial<SharedConfig>): FS | Promise<FS>;
-
-	/**
-	 * A name to identify the backend.
-	 */
-	name: string;
-
-	/**
-	 * Describes all of the options available for this backend.
-	 */
-	options: OptionsConfig<TOptions>;
-
-	/**
-	 * Whether the backend is available in the current environment.
-	 * It supports checking synchronously and asynchronously
-	 *
-	 * Returns 'true' if this backend is available in the current
-	 * environment. For example, a backend using a browser API will return
-	 * 'false' if the API is unavailable
-	 *
-	 */
-	isAvailable(): boolean | Promise<boolean>;
-}
-
-/**
- * Gets the options type of a backend
- * @internal
- */
-export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
-
-/**
- * Gets the FileSystem type for a backend
- * @internal
- */
-export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
-
-/** @internal */
-export function isBackend(arg: unknown): arg is Backend {
-	return arg != null && typeof arg == 'object' && 'isAvailable' in arg && typeof arg.isAvailable == 'function' && 'create' in arg && typeof arg.create == 'function';
-}
-
-/**
- * Checks that `options` object is valid for the file system options.
- * @internal
- */
-export async function checkOptions<T extends Backend>(backend: T, options: Record<string, unknown>): Promise<void> {
-	if (typeof options != 'object' || options === null) {
-		throw new ErrnoError(Errno.EINVAL, 'Invalid options');
-	}
-
-	// Check for required options.
-	for (const [optName, opt] of Object.entries(backend.options) as Entries<OptionsConfig<Record<string, any>>>) {
-		const providedValue = options?.[optName];
-
-		if (providedValue === undefined || providedValue === null) {
-			if (!opt.required) {
-				continue;
-			}
-			/* Required option not provided.
-			if any incorrect options provided, which ones are close to the provided one?
-			(edit distance 5 === close)*/
-			const incorrectOptions = Object.keys(options)
-				.filter(o => !(o in backend.options))
-				.map((a: string) => {
-					return { str: a, distance: levenshtein(optName, a) };
-				})
-				.filter(o => o.distance < 5)
-				.sort((a, b) => a.distance - b.distance);
-
-			throw new ErrnoError(
-				Errno.EINVAL,
-				`${backend.name}: Required option '${optName}' not provided.${
-					incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''
-				}`
-			);
-		}
-		// Option provided, check type.
-		const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
-		if (!typeMatches) {
-			throw new ErrnoError(
-				Errno.EINVAL,
-				`${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${
-					Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : (opt.type as string)
-				}, but received ${typeof providedValue}`
-			);
-		}
-
-		if (opt.validator) {
-			await opt.validator(providedValue);
-		}
-		// Otherwise: All good!
-	}
-}
-
-/**
- * Specifies a file system backend type and its options.
- *
- * Individual options can recursively contain BackendConfiguration objects for values that require file systems.
- *
- * The configuration for each file system corresponds to that file system's option object passed to its `create()` method.
- */
-export type BackendConfiguration<T extends Backend> = OptionsOf<T> & Partial<SharedConfig> & { backend: T };
-
-/** @internal */
-export function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T> {
-	return arg != null && typeof arg == 'object' && 'backend' in arg && isBackend(arg.backend);
-}

package/src/backends/fetch.ts

@@ -1,180 +0,0 @@
-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', init?: RequestInit): Promise<Uint8Array>;
-async function fetchFile<T extends object>(path: string, type: 'json', init?: RequestInit): Promise<T>;
-async function fetchFile<T extends object>(path: string, type: 'buffer' | 'json', init?: RequestInit): Promise<T | Uint8Array>;
-async function fetchFile<T extends object>(path: string, type: string, init?: RequestInit): Promise<T | Uint8Array> {
-	const response = await fetch(path, init).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 {
-	/**
-	 * Options to pass through to fetch calls
-	 */
-	requestInit?: RequestInit;
-
-	/**
-	 * 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 readonly requestInit?: RequestInit;
-
-	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 = '', requestInit }: FetchOptions) {
-		// prefix url must end in a directory separator.
-		if (baseUrl.at(-1) != '/') {
-			baseUrl += '/';
-		}
-
-		super(typeof index != 'string' ? index : fetchFile<IndexData>(index, 'json', requestInit));
-
-		this.baseUrl = baseUrl;
-		this.requestInit = requestInit;
-	}
-
-	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', this.requestInit);
-		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 },
-		baseUrl: { type: 'string', required: false },
-		requestInit: { type: 'object', required: false },
-	},
-
-	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

@@ -1,206 +0,0 @@
-/* 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

@@ -1,45 +0,0 @@
-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<bigint, 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 },
-	},
-	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;