@zenfs/core 0.10.0 → 0.11.0

package/src/backends/store/readme.md

@@ -0,0 +1,9 @@
+# Store
+
+While `StoreFS`, `Store`, etc. don't provide any backends directly, they are invaluable for creating new backends with a minimal amount of code.
+
+`StoreFS` implements the all of `FileSystem` using a `Store`.
+
+`Store` and `Transaction` are simple interfaces which are used by `StoreFS`.
+
+In [simple.ts](./simple.ts) you can find `SimpleSyncStore`, `SimpleAsyncStore`, and `SimpleTransaction`. These classes provide an even more simple interface. This means backends like `InMemory` can be implemented with a very small amount of code.

package/src/backends/store/simple.ts

@@ -0,0 +1,144 @@
+import type { Ino } from '../../inode.js';
+import { type Store, SyncTransaction } from './store.js';
+
+/**
+ * An interface for simple synchronous stores that don't have special support for transactions and such.
+ */
+export interface SimpleSyncStore extends Store {
+	get(ino: Ino): Uint8Array | undefined;
+	set(ino: Ino, data: Uint8Array): void;
+	delete(ino: Ino): void;
+}
+
+/**
+ * An interface for simple asynchronous stores that don't have special support for transactions and such.
+ * This class adds caching at the store level.
+ */
+export abstract class SimpleAsyncStore implements SimpleSyncStore {
+	public abstract name: string;
+
+	protected cache: Map<Ino, Uint8Array> = new Map();
+
+	protected queue: Set<Promise<unknown>> = new Set();
+
+	protected abstract entries(): Promise<Iterable<[Ino, Uint8Array]>>;
+
+	public get(ino: Ino): Uint8Array | undefined {
+		return this.cache.get(ino);
+	}
+
+	public set(ino: Ino, data: Uint8Array): void {
+		this.cache.set(ino, data);
+		this.queue.add(this._set(ino, data));
+	}
+
+	protected abstract _set(ino: Ino, data: Uint8Array): Promise<void>;
+
+	public delete(ino: Ino): void {
+		this.cache.delete(ino);
+		this.queue.add(this._delete(ino));
+	}
+
+	protected abstract _delete(ino: Ino): Promise<void>;
+
+	public clearSync(): void {
+		this.cache.clear();
+		this.queue.add(this.clear());
+	}
+
+	public abstract clear(): Promise<void>;
+
+	public async sync(): Promise<void> {
+		for (const [ino, data] of await this.entries()) {
+			if (!this.cache.has(ino)) {
+				this.cache.set(ino, data);
+			}
+		}
+		for (const promise of this.queue) {
+			await promise;
+		}
+	}
+
+	public transaction(): SimpleTransaction {
+		return new SimpleTransaction(this);
+	}
+}
+
+/**
+ * Transaction for simple stores.
+ * @see SimpleSyncStore
+ * @see SimpleAsyncStore
+ */
+export class SimpleTransaction extends SyncTransaction {
+	/**
+	 * Stores data in the keys we modify prior to modifying them.
+	 * Allows us to roll back commits.
+	 */
+	protected originalData: Map<Ino, Uint8Array | void> = new Map();
+	/**
+	 * List of keys modified in this transaction, if any.
+	 */
+	protected modifiedKeys: Set<Ino> = new Set();
+
+	constructor(protected store: SimpleSyncStore) {
+		super();
+	}
+
+	public getSync(ino: Ino): Uint8Array {
+		const val = this.store.get(ino);
+		this.stashOldValue(ino, val);
+		return val!;
+	}
+
+	public setSync(ino: Ino, data: Uint8Array): void {
+		this.markModified(ino);
+		return this.store.set(ino, data);
+	}
+
+	public removeSync(ino: Ino): void {
+		this.markModified(ino);
+		this.store.delete(ino);
+	}
+
+	public commitSync(): void {
+		/* NOP */
+	}
+
+	public abortSync(): void {
+		// Rollback old values.
+		for (const key of this.modifiedKeys) {
+			const value = this.originalData.get(key);
+			if (!value) {
+				// Key didn't exist.
+				this.store.delete(key);
+			} else {
+				// Key existed. Store old value.
+				this.store.set(key, value);
+			}
+		}
+	}
+
+	/**
+	 * Stashes given key value pair into `originalData` if it doesn't already
+	 * exist. Allows us to stash values the program is requesting anyway to
+	 * prevent needless `get` requests if the program modifies the data later
+	 * on during the transaction.
+	 */
+	protected stashOldValue(ino: Ino, value?: Uint8Array): void {
+		// Keep only the earliest value in the transaction.
+		if (!this.originalData.has(ino)) {
+			this.originalData.set(ino, value);
+		}
+	}
+
+	/**
+	 * Marks the given key as modified, and stashes its value if it has not been
+	 * stashed already.
+	 */
+	protected markModified(ino: Ino): void {
+		this.modifiedKeys.add(ino);
+		if (!this.originalData.has(ino)) {
+			this.originalData.set(ino, this.store.get(ino));
+		}
+	}
+}

package/src/backends/store/store.ts

@@ -0,0 +1,164 @@
+import { ErrnoError } from '../../error.js';
+import type { Ino } from '../../inode.js';
+
+/**
+ * Represents a key-value store.
+ */
+export interface Store {
+	/**
+	 * The name of the store.
+	 */
+	name: string;
+
+	/**
+	 * Syncs the store
+	 */
+	sync(): Promise<void>;
+
+	/**
+	 * Empties the store completely.
+	 */
+	clear(): Promise<void> | void;
+
+	/**
+	 * Empties the store completely.
+	 */
+	clearSync(): void;
+
+	/**
+	 * Begins a new transaction.
+	 */
+	transaction(): Transaction;
+}
+
+/**
+ * A transaction for a synchronous store.
+ */
+export abstract class Transaction {
+	protected aborted: boolean = false;
+
+	/**
+	 * Retrieves the data at the given key.
+	 * @param ino The key to look under for data.
+	 */
+	public abstract get(ino: Ino): Promise<Uint8Array>;
+
+	/**
+	 * Retrieves the data at the given key. Throws an error if an error occurs
+	 * or if the key does not exist.
+	 * @param ino The key to look under for data.
+	 * @return The data stored under the key, or undefined if not present.
+	 */
+	public abstract getSync(ino: Ino): Uint8Array;
+
+	/**
+	 * Adds the data to the store under the given key. Overwrites any existing
+	 * data.
+	 * @param ino The key to add the data under.
+	 * @param data The data to add to the store.
+	 * @param overwrite If 'true', overwrite any existing data. If 'false',
+	 *   avoids writing the data if the key exists.
+	 */
+	public abstract set(ino: Ino, data: Uint8Array): Promise<void>;
+
+	/**
+	 * Adds the data to the store under the given key.
+	 * @param ino The key to add the data under.
+	 * @param data The data to add to the store.
+	 * @param overwrite If 'true', overwrite any existing data. If 'false',
+	 *   avoids storing the data if the key exists.
+	 * @return True if storage succeeded, false otherwise.
+	 */
+	public abstract setSync(ino: Ino, data: Uint8Array): void;
+
+	/**
+	 * Deletes the data at the given key.
+	 * @param ino The key to delete from the store.
+	 */
+	public abstract remove(ino: Ino): Promise<void>;
+
+	/**
+	 * Deletes the data at the given key.
+	 * @param ino The key to delete from the store.
+	 */
+	public abstract removeSync(ino: Ino): void;
+
+	/**
+	 * Commits the transaction.
+	 */
+	public abstract commit(): Promise<void>;
+
+	public async [Symbol.asyncDispose]() {
+		if (this.aborted) {
+			return;
+		}
+
+		await this.commit();
+	}
+
+	/**
+	 * Commits the transaction.
+	 */
+	public abstract commitSync(): void;
+
+	public [Symbol.dispose]() {
+		if (this.aborted) {
+			return;
+		}
+
+		this.commitSync();
+	}
+
+	/**
+	 * Aborts and rolls back the transaction.
+	 */
+	public abstract abort(): Promise<void>;
+
+	/**
+	 * Aborts and rolls back the transaction.
+	 */
+	public abstract abortSync(): void;
+}
+
+/**
+ * Transaction that implements asynchronous operations with synchronous ones
+ */
+export abstract class SyncTransaction extends Transaction {
+	public async get(ino: Ino): Promise<Uint8Array> {
+		return this.getSync(ino);
+	}
+	public async set(ino: bigint, data: Uint8Array): Promise<void> {
+		return this.setSync(ino, data);
+	}
+	public async remove(ino: Ino): Promise<void> {
+		return this.removeSync(ino);
+	}
+	public async commit(): Promise<void> {
+		return this.commitSync();
+	}
+	public async abort(): Promise<void> {
+		return this.abortSync();
+	}
+}
+
+/**
+ * Transaction that only supports asynchronous operations
+ * @todo Add caching
+ */
+export abstract class AsyncTransaction extends Transaction {
+	public getSync(ino: Ino): Uint8Array {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.getSync');
+	}
+	public setSync(ino: bigint, data: Uint8Array): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.setSync');
+	}
+	public removeSync(ino: bigint): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.removeSync');
+	}
+	public commitSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.commitSync');
+	}
+	public abortSync(): void {
+		throw ErrnoError.With('ENOSYS', undefined, 'AsyncTransaction.abortSync');
+	}
+}

package/src/config.ts

@@ -33,7 +33,7 @@ export async function resolveMountConfig<FS extends FileSystem, TOptions extends
 	}
 
 	if (isBackend(config)) {
-		config = <BackendConfiguration<Backend<FS, TOptions>>>{ backend: config };
+		config = { backend: config } as BackendConfiguration<Backend<FS, TOptions>>;
 	}
 
 	for (const [key, value] of Object.entries(config)) {
@@ -76,7 +76,7 @@ export interface Configuration {
  * Creates filesystems with the given configuration, and initializes ZenFS with it.
  * @see Configuration for more info on the configuration object.
  */
-export async function configure(config: MountConfiguration | Configuration): Promise<void> {
+export async function configure<T extends MountConfiguration | Configuration>(config: T | Configuration): Promise<void> {
 	const uid = 'uid' in config ? config.uid || 0 : 0;
 	const gid = 'gid' in config ? config.gid || 0 : 0;
 

package/src/emulation/shared.ts

@@ -1,7 +1,7 @@
 // Utilities and shared data
 
 import { ErrnoError, Errno } from '../error.js';
-import { InMemory } from '../backends/InMemory.js';
+import { InMemory } from '../backends/memory.js';
 import { Cred, rootCred } from '../cred.js';
 import type { File } from '../file.js';
 import { FileSystem } from '../filesystem.js';

package/src/error.ts

@@ -269,7 +269,6 @@ export class ErrnoError extends Error implements NodeJS.ErrnoException {
 	 *
 	 * Error codes mirror those returned by regular Unix file operations, which is
 	 * what Node returns.
-	 * @constructor ApiError
 	 * @param type The type of the error.
 	 * @param message A descriptive error message.
 	 */

package/src/file.ts

@@ -620,7 +620,7 @@ export class PreloadFile<FS extends FileSystem> extends File {
 			// No copy/read. Return immediatly for better performance
 			return bytesRead;
 		}
-		new Uint8Array(buffer.buffer, 0, length).set(this._buffer.slice(position, end), offset);
+		new Uint8Array(buffer.buffer, offset, length).set(this._buffer.slice(position, end));
 		return bytesRead;
 	}
 

package/src/filesystem.ts

@@ -59,9 +59,7 @@ export abstract class FileSystem {
 		// unused
 	}
 
-	public async ready(): Promise<this> {
-		return this;
-	}
+	public async ready(): Promise<void> {}
 
 	/**
 	 * Asynchronous rename. No arguments other than a possible exception
@@ -201,7 +199,7 @@ export abstract class FileSystem {
  */
 declare abstract class SyncFileSystem extends FileSystem {
 	metadata(): FileSystemMetadata;
-	ready(): Promise<this>;
+	ready(): Promise<void>;
 	exists(path: string, cred: Cred): Promise<boolean>;
 	rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
 	stat(path: string, cred: Cred): Promise<Stats>;
@@ -278,7 +276,7 @@ declare abstract class AsyncFileSystem extends FileSystem {
 	abstract _sync: FileSystem;
 	queueDone(): Promise<void>;
 	metadata(): FileSystemMetadata;
-	ready(): Promise<this>;
+	ready(): Promise<void>;
 	renameSync(oldPath: string, newPath: string, cred: Cred): void;
 	statSync(path: string, cred: Cred): Stats;
 	createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
@@ -335,11 +333,11 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 
 		abstract _sync: FileSystem;
 
-		public async ready(): Promise<this> {
+		public async ready(): Promise<void> {
 			await this._sync.ready();
 			await super.ready();
 			if (this._isInitialized) {
-				return this;
+				return;
 			}
 
 			try {
@@ -349,7 +347,6 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 				this._isInitialized = false;
 				throw e;
 			}
-			return this;
 		}
 
 		public renameSync(oldPath: string, newPath: string, cred: Cred): void {
@@ -357,8 +354,8 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 			this.queue('rename', oldPath, newPath, cred);
 		}
 
-		public statSync(p: string, cred: Cred): Stats {
-			return this._sync.statSync(p, cred);
+		public statSync(path: string, cred: Cred): Stats {
+			return this._sync.statSync(path, cred);
 		}
 
 		public createFileSync(path: string, flag: string, mode: number, cred: Cred): PreloadFile<this> {
@@ -374,23 +371,23 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 			return this._sync.openFileSync(path, flag, cred);
 		}
 
-		public unlinkSync(p: string, cred: Cred): void {
-			this._sync.unlinkSync(p, cred);
-			this.queue('unlink', p, cred);
+		public unlinkSync(path: string, cred: Cred): void {
+			this._sync.unlinkSync(path, cred);
+			this.queue('unlink', path, cred);
 		}
 
-		public rmdirSync(p: string, cred: Cred): void {
-			this._sync.rmdirSync(p, cred);
-			this.queue('rmdir', p, cred);
+		public rmdirSync(path: string, cred: Cred): void {
+			this._sync.rmdirSync(path, cred);
+			this.queue('rmdir', path, cred);
 		}
 
-		public mkdirSync(p: string, mode: number, cred: Cred): void {
-			this._sync.mkdirSync(p, mode, cred);
-			this.queue('mkdir', p, mode, cred);
+		public mkdirSync(path: string, mode: number, cred: Cred): void {
+			this._sync.mkdirSync(path, mode, cred);
+			this.queue('mkdir', path, mode, cred);
 		}
 
-		public readdirSync(p: string, cred: Cred): string[] {
-			return this._sync.readdirSync(p, cred);
+		public readdirSync(path: string, cred: Cred): string[] {
+			return this._sync.readdirSync(path, cred);
 		}
 
 		public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
@@ -403,27 +400,27 @@ export function Async<T extends abstract new (...args: any[]) => FileSystem>(FS:
 			this.queue('sync', path, data, stats);
 		}
 
-		public existsSync(p: string, cred: Cred): boolean {
-			return this._sync.existsSync(p, cred);
+		public existsSync(path: string, cred: Cred): boolean {
+			return this._sync.existsSync(path, cred);
 		}
 
 		/**
 		 * @internal
 		 */
-		protected async crossCopy(p: string): Promise<void> {
-			const stats = await this.stat(p, rootCred);
+		protected async crossCopy(path: string): Promise<void> {
+			const stats = await this.stat(path, rootCred);
 			if (stats.isDirectory()) {
-				if (p !== '/') {
-					const stats = await this.stat(p, rootCred);
-					this._sync.mkdirSync(p, stats.mode, stats.cred());
+				if (path !== '/') {
+					const stats = await this.stat(path, rootCred);
+					this._sync.mkdirSync(path, stats.mode, stats.cred());
 				}
-				const files = await this.readdir(p, rootCred);
+				const files = await this.readdir(path, rootCred);
 				for (const file of files) {
-					await this.crossCopy(join(p, file));
+					await this.crossCopy(join(path, file));
 				}
 			} else {
-				const asyncFile = await this.openFile(p, parseFlag('r'), rootCred);
-				const syncFile = this._sync.createFileSync(p, parseFlag('w'), stats.mode, stats.cred());
+				const asyncFile = await this.openFile(path, parseFlag('r'), rootCred);
+				const syncFile = this._sync.createFileSync(path, parseFlag('w'), stats.mode, stats.cred());
 				try {
 					const buffer = new Uint8Array(stats.size);
 					await asyncFile.read(buffer);

package/src/index.ts

@@ -1,13 +1,11 @@
 export * from './error.js';
 export * from './backends/port/fs.js';
-export * from './backends/port/store.js';
-export * from './backends/AsyncStore.js';
-export * from './backends/Fetch.js';
-export * from './backends/InMemory.js';
+export * from './backends/fetch.js';
+export * from './backends/memory.js';
 export * from './backends/Index.js';
-export * from './backends/Locked.js';
-export * from './backends/Overlay.js';
-export * from './backends/SyncStore.js';
+export * from './backends/locked.js';
+export * from './backends/overlay.js';
+export * from './backends/store/fs.js';
 export * from './backends/backend.js';
 export * from './config.js';
 export * from './cred.js';

package/src/inode.ts

@@ -16,7 +16,7 @@ export const size_max = 2 ** 32 - 1;
  * Room inode
  * @hidden
  */
-export const rootIno: Ino = 0n;
+export const rootIno = 0n as const;
 
 /**
  * Generates a random 32 bit integer, then converts to a hex string