@zenfs/core 1.0.11 → 1.1.1

package/dist/utils.d.ts

@@ -17,20 +17,30 @@ export declare function mkdirpSync(path: string, mode: number, fs: FileSystem):
  * @hidden
  */
 export declare function levenshtein(a: string, b: string): number;
+/** @hidden */
+export declare const setImmediate: (callback: () => unknown) => void;
 /**
- * @hidden
+ * Encodes a string into a buffer
+ * @internal
  */
-export declare const setImmediate: (callback: () => unknown) => void;
+export declare function encodeRaw(input: string): Uint8Array;
+/**
+ * Decodes a string from a buffer
+ * @internal
+ */
+export declare function decodeRaw(input?: Uint8Array): string;
 /**
  * Encodes a string into a buffer
  * @internal
  */
-export declare function encode(input: string): Uint8Array;
+export declare function encodeUTF8(input: string): Uint8Array;
+export { /** @deprecated @hidden */ encodeUTF8 as encode };
 /**
  * Decodes a string from a buffer
  * @internal
  */
-export declare function decode(input?: Uint8Array): string;
+export declare function decodeUTF8(input?: Uint8Array): string;
+export { /** @deprecated @hidden */ decodeUTF8 as decode };
 /**
  * Decodes a directory listing
  * @hidden

package/dist/utils.js

@@ -83,45 +83,67 @@ export function levenshtein(a, b) {
     }
     return dd;
 }
+/** @hidden */
+export const setImmediate = typeof globalThis.setImmediate == 'function' ? globalThis.setImmediate : (cb) => setTimeout(cb, 0);
 /**
- * @hidden
+ * Encodes a string into a buffer
+ * @internal
  */
-export const setImmediate = typeof globalThis.setImmediate == 'function' ? globalThis.setImmediate : (cb) => setTimeout(cb, 0);
+export function encodeRaw(input) {
+    if (typeof input != 'string') {
+        throw new ErrnoError(Errno.EINVAL, 'Can not encode a non-string');
+    }
+    return new Uint8Array(Array.from(input).map(char => char.charCodeAt(0)));
+}
+/**
+ * Decodes a string from a buffer
+ * @internal
+ */
+export function decodeRaw(input) {
+    if (!(input instanceof Uint8Array)) {
+        throw new ErrnoError(Errno.EINVAL, 'Can not decode a non-Uint8Array');
+    }
+    return Array.from(input)
+        .map(char => String.fromCharCode(char))
+        .join('');
+}
 const encoder = new TextEncoder();
 /**
  * Encodes a string into a buffer
  * @internal
  */
-export function encode(input) {
+export function encodeUTF8(input) {
     if (typeof input != 'string') {
         throw new ErrnoError(Errno.EINVAL, 'Can not encode a non-string');
     }
     return encoder.encode(input);
 }
+export { /** @deprecated @hidden */ encodeUTF8 as encode };
 const decoder = new TextDecoder();
 /**
  * Decodes a string from a buffer
  * @internal
  */
-export function decode(input) {
+export function decodeUTF8(input) {
     if (!(input instanceof Uint8Array)) {
         throw new ErrnoError(Errno.EINVAL, 'Can not decode a non-Uint8Array');
     }
     return decoder.decode(input);
 }
+export { /** @deprecated @hidden */ decodeUTF8 as decode };
 /**
  * Decodes a directory listing
  * @hidden
  */
 export function decodeDirListing(data) {
-    return JSON.parse(decode(data), (k, v) => (k == '' ? v : BigInt(v)));
+    return JSON.parse(decodeUTF8(data), (k, v) => (k == '' ? v : BigInt(v)));
 }
 /**
  * Encodes a directory listing
  * @hidden
  */
 export function encodeDirListing(data) {
-    return encode(JSON.stringify(data, (k, v) => (k == '' ? v : v.toString())));
+    return encodeUTF8(JSON.stringify(data, (k, v) => (k == '' ? v : v.toString())));
 }
 /**
  * converts Date or number to a integer UNIX timestamp

package/package.json

@@ -1,7 +1,11 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.0.11",
+	"version": "1.1.1",
 	"description": "A filesystem, anywhere",
+	"funding": {
+		"type": "individual",
+		"url": "https://github.com/sponsors/james-pre"
+	},
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"keywords": [

package/readme.md

@@ -15,9 +15,11 @@ ZenFS is modular and extensible. The core includes some built-in backends:
 
 ZenFS supports a number of other backends. Many are provided as separate packages under `@zenfs`. More backends can be defined by separate libraries by extending the `FileSystem` class and providing a `Backend` object.
 
+You can find all of the packages available over at [zenfs.dev](https://zenfs.dev).
+
 As an added bonus, all ZenFS backends support synchronous operations. All of the backends included with the core are cross-platform.
 
-For more information, see the [docs](https://zen-fs.github.io/core).
+For more information, see the [docs](https://zenfs.dev/core).
 
 ## Installing
 
@@ -143,8 +145,62 @@ fs.mount('/mnt/zip', zipfs);
 fs.umount('/mnt/zip'); // finished using the zip
 ```
 
+> [!CAUTION]
+> Instances of backends follow the _internal_ API. You should never use a backend's methods unless you are extending a backend.
+
+#### Devices and device files
+
 > [!WARNING]
-> Instances of backends follow the **internal** ZenFS API. You should never use a backend's methods unless you are extending a backend.
+> This is an **experimental** feature. Breaking changes may occur during non-major releases. Using this feature is the fastest way to make it stable.
+
+ZenFS includes experimental support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. You can automatically add some normal devices with the `addDevices` configuration option:
+
+```ts
+await configure({
+	mounts: {
+		/* ... */
+	},
+	addDevices: true,
+});
+
+fs.writeFileSync('/dev/null', 'Some data to be discarded');
+
+const randomData = new Unit8Array(100);
+
+const random = fs.openSync('/dev/random', 'r');
+fs.readSync(random, randomData);
+fs.closeSync(random);
+```
+
+You can create your own devices by implementing a `DeviceDriver`. For example, the null device looks similar to this:
+
+```ts
+const customNullDevice = {
+	name: 'custom_null',
+	isBuffered: false,
+	read() {
+		return 0;
+	},
+	write() {},
+};
+```
+
+Note the actual implementation's write is slightly more complicated since it adds to the file position. You can find more information on the docs.
+
+Finally, if you'd like to use your custom device with the file system, you can use so through the aptly named `DeviceFS`.
+
+```ts
+const devfs = fs.mounts.get('/dev') as DeviceFS;
+devfs.createDevice('/custom', customNullDevice);
+
+fs.writeFileSync('/dev/custom', 'This gets discarded.');
+```
+
+In the above example, `createDevice` works relative to the `DeviceFS` mount point.
+
+Additionally, a type assertion (` as ...`) is used since `fs.mounts` does not keep track of which file system type is mapped to which mount point. Doing so would create significant maintenance costs due to the complexity of implementing it.
+
+If you would like to see a more intuitive way adding custom devices (e.g. `fs.mknod`), please feel free to open an issue for a feature request.
 
 ## Using with bundlers
 

package/src/backends/file_index.ts

@@ -8,7 +8,7 @@ import { FileSystem } from '../filesystem.js';
 import { Readonly } from '../mixins/readonly.js';
 import type { StatsLike } from '../stats.js';
 import { Stats } from '../stats.js';
-import { decode, encode } from '../utils.js';
+import { decodeUTF8, encodeUTF8 } from '../utils.js';
 
 /**
  * An Index in JSON form
@@ -83,7 +83,7 @@ export class Index extends Map<string, Stats> {
 		for (const [path, data] of Object.entries(json.entries)) {
 			const stats = new Stats(data);
 			if (stats.isDirectory()) {
-				stats.fileData = encode(JSON.stringify(this.dirEntries(path)));
+				stats.fileData = encodeUTF8(JSON.stringify(this.dirEntries(path)));
 			}
 			this.set(path, stats);
 		}
@@ -195,7 +195,7 @@ export abstract class IndexFS extends Readonly(FileSystem) {
 			throw ErrnoError.With('ENOTDIR', path, 'readdir');
 		}
 
-		const content: unknown = JSON.parse(decode(stats.fileData));
+		const content: unknown = JSON.parse(decodeUTF8(stats.fileData));
 		if (!Array.isArray(content)) {
 			throw ErrnoError.With('ENODATA', path, 'readdir');
 		}

package/src/backends/overlay.ts

@@ -6,7 +6,7 @@ import type { FileSystemMetadata } from '../filesystem.js';
 import { FileSystem } from '../filesystem.js';
 import { Mutexed } from '../mixins/mutexed.js';
 import { Stats } from '../stats.js';
-import { decode, encode } from '../utils.js';
+import { decodeUTF8, encodeUTF8 } from '../utils.js';
 import type { Backend } from './backend.js';
 /** @internal */
 const deletionLogPath = '/.deleted';
@@ -99,7 +99,7 @@ export class UnmutexedOverlayFS extends FileSystem {
 			const file = await this.writable.openFile(deletionLogPath, parseFlag('r'));
 			const { size } = await file.stat();
 			const { buffer } = await file.read(new Uint8Array(size));
-			this._deleteLog = decode(buffer);
+			this._deleteLog = decodeUTF8(buffer);
 		} catch (err) {
 			if ((err as ErrnoError).errno !== Errno.ENOENT) {
 				throw err;
@@ -386,7 +386,7 @@ export class UnmutexedOverlayFS extends FileSystem {
 		this._deleteLogUpdatePending = true;
 		const log = await this.writable.openFile(deletionLogPath, parseFlag('w'));
 		try {
-			await log.write(encode(this._deleteLog));
+			await log.write(encodeUTF8(this._deleteLog));
 			if (this._deleteLogUpdateNeeded) {
 				this._deleteLogUpdateNeeded = false;
 				await this.updateLog('');

package/src/backends/store/fs.ts

@@ -6,8 +6,9 @@ import { PreloadFile } from '../../file.js';
 import { FileSystem, type FileSystemMetadata } from '../../filesystem.js';
 import { type Ino, Inode, randomIno, rootIno } from '../../inode.js';
 import type { FileType, Stats } from '../../stats.js';
-import { decodeDirListing, encode, encodeDirListing } from '../../utils.js';
+import { decodeDirListing, encodeUTF8, encodeDirListing } from '../../utils.js';
 import type { Store, Transaction } from './store.js';
+import type { File } from '../../file.js';
 
 const maxInodeAllocTries = 5;
 
@@ -172,17 +173,17 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 		return this.findINodeSync(tx, path).toStats();
 	}
 
-	public async createFile(path: string, flag: string, mode: number): Promise<PreloadFile<this>> {
+	public async createFile(path: string, flag: string, mode: number): Promise<File> {
 		const node = await this.commitNew(path, S_IFREG, mode, new Uint8Array(0));
 		return new PreloadFile(this, path, flag, node.toStats(), new Uint8Array(0));
 	}
 
-	public createFileSync(path: string, flag: string, mode: number): PreloadFile<this> {
+	public createFileSync(path: string, flag: string, mode: number): File {
 		this.commitNewSync(path, S_IFREG, mode);
 		return this.openFileSync(path, flag);
 	}
 
-	public async openFile(path: string, flag: string): Promise<PreloadFile<this>> {
+	public async openFile(path: string, flag: string): Promise<File> {
 		await using tx = this.store.transaction();
 		const node = await this.findINode(tx, path),
 			data = await tx.get(node.ino);
@@ -192,7 +193,7 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 		return new PreloadFile(this, path, flag, node.toStats(), data);
 	}
 
-	public openFileSync(path: string, flag: string): PreloadFile<this> {
+	public openFileSync(path: string, flag: string): File {
 		using tx = this.store.transaction();
 		const node = this.findINodeSync(tx, path),
 			data = tx.getSync(node.ino);
@@ -225,11 +226,11 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 	}
 
 	public async mkdir(path: string, mode: number): Promise<void> {
-		await this.commitNew(path, S_IFDIR, mode, encode('{}'));
+		await this.commitNew(path, S_IFDIR, mode, encodeUTF8('{}'));
 	}
 
 	public mkdirSync(path: string, mode: number): void {
-		this.commitNewSync(path, S_IFDIR, mode, encode('{}'));
+		this.commitNewSync(path, S_IFDIR, mode, encodeUTF8('{}'));
 	}
 
 	public async readdir(path: string): Promise<string[]> {
@@ -334,7 +335,7 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 		const inode = new Inode();
 		inode.mode = 0o777 | S_IFDIR;
 		// If the root doesn't exist, the first random ID shouldn't exist either.
-		await tx.set(inode.ino, encode('{}'));
+		await tx.set(inode.ino, encodeUTF8('{}'));
 		await tx.set(rootIno, inode.data);
 		await tx.commit();
 	}
@@ -351,7 +352,7 @@ export class StoreFS<T extends Store = Store> extends FileSystem {
 		const inode = new Inode();
 		inode.mode = 0o777 | S_IFDIR;
 		// If the root doesn't exist, the first random ID shouldn't exist either.
-		tx.setSync(inode.ino, encode('{}'));
+		tx.setSync(inode.ino, encodeUTF8('{}'));
 		tx.setSync(rootIno, inode.data);
 		tx.commitSync();
 	}

package/src/config.ts

@@ -1,6 +1,7 @@
 import type { Backend, BackendConfiguration, FilesystemOf, SharedConfig } from './backends/backend.js';
 import { checkOptions, isBackend, isBackendConfig } from './backends/backend.js';
 import { credentials } from './credentials.js';
+import { DeviceFS, fullDevice, nullDevice, randomDevice, zeroDevice } from './devices.js';
 import * as fs from './emulation/index.js';
 import type { AbsolutePath } from './emulation/path.js';
 import type { MountObject } from './emulation/shared.js';
@@ -77,14 +78,25 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
 	 * An object mapping mount points to mount configuration
 	 */
 	mounts: { [K in keyof T & AbsolutePath]: MountConfiguration<T[K]> };
+
 	/**
 	 * The uid to use
+	 * @default 0
 	 */
 	uid: number;
+
 	/**
 	 * The gid to use
+	 * @default 0
 	 */
 	gid: number;
+
+	/**
+	 * Whether to automatically add normal Linux devices
+	 * @default false
+	 * @experimental
+	 */
+	addDevices: boolean;
 }
 
 /**
@@ -110,6 +122,16 @@ export async function configure<T extends ConfigMounts>(configuration: Partial<C
 
 	Object.assign(credentials, { uid, gid, suid: uid, sgid: gid, euid: uid, egid: gid });
 
+	if (configuration.addDevices) {
+		const devfs = new DeviceFS();
+		devfs.createDevice('/null', nullDevice);
+		devfs.createDevice('/zero', zeroDevice);
+		devfs.createDevice('/full', fullDevice);
+		devfs.createDevice('/random', randomDevice);
+		await devfs.ready();
+		fs.mount('/dev', devfs);
+	}
+
 	if (!configuration.mounts) {
 		return;
 	}