@zenfs/core 0.0.1

package/dist/emulation/shared.js

@@ -0,0 +1,192 @@
+// Utilities and shared data
+import { posix as path } from 'path';
+import { ApiError, ErrorCode } from '../ApiError';
+//import { BackendConstructor } from '../backends';
+import { InMemoryFileSystem } from '../backends/InMemory';
+/**
+ * converts Date or number to a fractional UNIX timestamp
+ * Grabbed from NodeJS sources (lib/fs.js)
+ */
+export function _toUnixTimestamp(time) {
+    if (typeof time === 'number') {
+        return time;
+    }
+    else if (time instanceof Date) {
+        return time.getTime() / 1000;
+    }
+    throw new Error('Cannot parse time: ' + time);
+}
+export function normalizeMode(mode, def) {
+    switch (typeof mode) {
+        case 'number':
+            // (path, flag, mode, cb?)
+            return mode;
+        case 'string':
+            // (path, flag, modeString, cb?)
+            const trueMode = parseInt(mode, 8);
+            if (!isNaN(trueMode)) {
+                return trueMode;
+            }
+            // Invalid string.
+            return def;
+        default:
+            return def;
+    }
+}
+export function normalizeTime(time) {
+    if (time instanceof Date) {
+        return time;
+    }
+    if (typeof time === 'number') {
+        return new Date(time * 1000);
+    }
+    throw new ApiError(ErrorCode.EINVAL, `Invalid time.`);
+}
+export function normalizePath(p) {
+    // Node doesn't allow null characters in paths.
+    if (p.indexOf('\u0000') >= 0) {
+        throw new ApiError(ErrorCode.EINVAL, 'Path must be a string without null bytes.');
+    }
+    if (p === '') {
+        throw new ApiError(ErrorCode.EINVAL, 'Path must not be empty.');
+    }
+    p = p.replaceAll(/\/+/g, '/');
+    return path.resolve(p);
+}
+export function normalizeOptions(options, defEnc, defFlag, defMode) {
+    // typeof null === 'object' so special-case handing is needed.
+    switch (options === null ? 'null' : typeof options) {
+        case 'object':
+            return {
+                encoding: typeof options['encoding'] !== 'undefined' ? options['encoding'] : defEnc,
+                flag: typeof options['flag'] !== 'undefined' ? options['flag'] : defFlag,
+                mode: normalizeMode(options['mode'], defMode),
+            };
+        case 'string':
+            return {
+                encoding: options,
+                flag: defFlag,
+                mode: defMode,
+            };
+        case 'null':
+        case 'undefined':
+        case 'function':
+            return {
+                encoding: defEnc,
+                flag: defFlag,
+                mode: defMode,
+            };
+        default:
+            throw new TypeError(`"options" must be a string or an object, got ${typeof options} instead.`);
+    }
+}
+export function nop() {
+    // do nothing
+}
+// credentials
+export let cred;
+export function setCred(val) {
+    cred = val;
+}
+// descriptors
+export const fdMap = new Map();
+let nextFd = 100;
+export function getFdForFile(file) {
+    const fd = nextFd++;
+    fdMap.set(fd, file);
+    return fd;
+}
+export function fd2file(fd) {
+    if (!fdMap.has(fd)) {
+        throw new ApiError(ErrorCode.EBADF, 'Invalid file descriptor.');
+    }
+    return fdMap.get(fd);
+}
+export const mounts = new Map();
+/*
+Set a default root.
+There is a very small but not 0 change that initialize() will try to unmount the default before it is mounted.
+This can be fixed by using a top-level await, which is not done to maintain ES6 compatibility.
+*/
+InMemoryFileSystem.Create().then(fs => mount('/', fs));
+/**
+ * Gets the file system mounted at `mountPoint`
+ */
+export function getMount(mountPoint) {
+    return mounts.get(mountPoint);
+}
+/**
+ * Gets an object of mount points (keys) and filesystems (values)
+ */
+export function getMounts() {
+    return Object.fromEntries(mounts.entries());
+}
+/**
+ * Mounts the file system at the given mount point.
+ */
+export function mount(mountPoint, fs) {
+    if (mountPoint[0] !== '/') {
+        mountPoint = '/' + mountPoint;
+    }
+    mountPoint = path.resolve(mountPoint);
+    if (mounts.has(mountPoint)) {
+        throw new ApiError(ErrorCode.EINVAL, 'Mount point ' + mountPoint + ' is already in use.');
+    }
+    mounts.set(mountPoint, fs);
+}
+/**
+ * Unmounts the file system at the given mount point.
+ */
+export function umount(mountPoint) {
+    if (mountPoint[0] !== '/') {
+        mountPoint = `/${mountPoint}`;
+    }
+    mountPoint = path.resolve(mountPoint);
+    if (!mounts.has(mountPoint)) {
+        throw new ApiError(ErrorCode.EINVAL, 'Mount point ' + mountPoint + ' is already unmounted.');
+    }
+    mounts.delete(mountPoint);
+}
+/**
+ * Gets the internal FileSystem for the path, then returns it along with the path relative to the FS' root
+ */
+export function resolveFS(path) {
+    const sortedMounts = [...mounts].sort((a, b) => (a[0].length > b[0].length ? -1 : 1)); // decending order of the string length
+    for (const [mountPoint, fs] of sortedMounts) {
+        // We know path is normalized, so it would be a substring of the mount point.
+        if (mountPoint.length <= path.length && path.startsWith(mountPoint)) {
+            path = path.slice(mountPoint.length > 1 ? mountPoint.length : 0); // Resolve the path relative to the mount point
+            if (path === '') {
+                path = '/';
+            }
+            return { fs, path, mountPoint };
+        }
+    }
+    throw new ApiError(ErrorCode.EIO, 'ZenFS not initialized with a file system');
+}
+/**
+ * Reverse maps the paths in text from the mounted FileSystem to the global path
+ */
+export function fixPaths(text, paths) {
+    for (const [from, to] of Object.entries(paths)) {
+        text = text.replaceAll(from, to);
+    }
+    return text;
+}
+export function fixError(e, paths) {
+    e.stack = fixPaths(e.stack, paths);
+    e.message = fixPaths(e.message, paths);
+    return e;
+}
+export function initialize(mountMapping) {
+    if (mountMapping['/']) {
+        umount('/');
+    }
+    for (const [point, fs] of Object.entries(mountMapping)) {
+        const FS = fs.constructor;
+        if (!FS.isAvailable()) {
+            throw new ApiError(ErrorCode.EINVAL, `Can not mount "${point}" since the filesystem is unavailable.`);
+        }
+        mount(point, fs);
+    }
+}

package/dist/emulation/sync.d.ts

@@ -0,0 +1,278 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { FileContents } from '../filesystem';
+import { Stats } from '../stats';
+import type { symlink, ReadSyncOptions } from 'fs';
+/**
+ * Synchronous rename.
+ * @param oldPath
+ * @param newPath
+ */
+export declare function renameSync(oldPath: string, newPath: string): void;
+/**
+ * Test whether or not the given path exists by checking with the file system.
+ * @param path
+ */
+export declare function existsSync(path: string): boolean;
+/**
+ * Synchronous `stat`.
+ * @param path
+ * @returns Stats
+ */
+export declare function statSync(path: string): Stats;
+/**
+ * Synchronous `lstat`.
+ * `lstat()` is identical to `stat()`, except that if path is a symbolic link,
+ * then the link itself is stat-ed, not the file that it refers to.
+ * @param path
+ * @return [ZenFS.node.fs.Stats]
+ */
+export declare function lstatSync(path: string): Stats;
+/**
+ * Synchronous `truncate`.
+ * @param path
+ * @param len
+ */
+export declare function truncateSync(path: string, len?: number): void;
+/**
+ * Synchronous `unlink`.
+ * @param path
+ */
+export declare function unlinkSync(path: string): void;
+/**
+ * Synchronous file open.
+ * @see http://www.manpagez.com/man/2/open/
+ * @param path
+ * @param flags
+ * @param mode defaults to `0644`
+ * @return [ZenFS.File]
+ */
+export declare function openSync(path: string, flag: string, mode?: number | string): number;
+/**
+ * Synchronously reads the entire contents of a file.
+ * @param filename
+ * @param options
+ * @option options [String] encoding The string encoding for the file contents. Defaults to `null`.
+ * @option options [String] flag Defaults to `'r'`.
+ * @return [String | ZenFS.node.Buffer]
+ */
+export declare function readFileSync(filename: string, options?: {
+    flag?: string;
+}): Buffer;
+export declare function readFileSync(filename: string, options: {
+    encoding: string;
+    flag?: string;
+}): string;
+export declare function readFileSync(filename: string, encoding: string): string;
+/**
+ * Synchronously writes data to a file, replacing the file if it already
+ * exists.
+ *
+ * The encoding option is ignored if data is a buffer.
+ * @param filename
+ * @param data
+ * @param options
+ * @option options [String] encoding Defaults to `'utf8'`.
+ * @option options [Number] mode Defaults to `0644`.
+ * @option options [String] flag Defaults to `'w'`.
+ */
+export declare function writeFileSync(filename: string, data: FileContents, options?: {
+    encoding?: string;
+    mode?: number | string;
+    flag?: string;
+}): void;
+export declare function writeFileSync(filename: string, data: FileContents, encoding?: string): void;
+/**
+ * Asynchronously append data to a file, creating the file if it not yet
+ * exists.
+ *
+ * @example Usage example
+ *   fs.appendFile('message.txt', 'data to append', function (err) {
+ *     if (err) throw err;
+ *     console.log('The "data to append" was appended to file!');
+ *   });
+ * @param filename
+ * @param data
+ * @param options
+ * @option options [String] encoding Defaults to `'utf8'`.
+ * @option options [Number] mode Defaults to `0644`.
+ * @option options [String] flag Defaults to `'a'`.
+ */
+export declare function appendFileSync(filename: string, data: FileContents, options?: {
+    encoding?: string;
+    mode?: number | string;
+    flag?: string;
+}): void;
+export declare function appendFileSync(filename: string, data: FileContents, encoding?: string): void;
+/**
+ * Synchronous `fstat`.
+ * `fstat()` is identical to `stat()`, except that the file to be stat-ed is
+ * specified by the file descriptor `fd`.
+ * @param fd
+ * @return [ZenFS.node.fs.Stats]
+ */
+export declare function fstatSync(fd: number): Stats;
+/**
+ * Synchronous close.
+ * @param fd
+ */
+export declare function closeSync(fd: number): void;
+/**
+ * Synchronous ftruncate.
+ * @param fd
+ * @param len
+ */
+export declare function ftruncateSync(fd: number, len?: number): void;
+/**
+ * Synchronous fsync.
+ * @param fd
+ */
+export declare function fsyncSync(fd: number): void;
+/**
+ * Synchronous fdatasync.
+ * @param fd
+ */
+export declare function fdatasyncSync(fd: number): void;
+/**
+ * Write buffer to the file specified by `fd`.
+ * Note that it is unsafe to use fs.write multiple times on the same file
+ * without waiting for it to return.
+ * @param fd
+ * @param buffer Buffer containing the data to write to
+ *   the file.
+ * @param offset Offset in the buffer to start reading data from.
+ * @param length The amount of bytes to write to the file.
+ * @param position Offset from the beginning of the file where this
+ *   data should be written. If position is null, the data will be written at
+ *   the current position.
+ */
+export declare function writeSync(fd: number, buffer: Buffer, offset: number, length: number, position?: number | null): number;
+export declare function writeSync(fd: number, data: string, position?: number | null, encoding?: BufferEncoding): number;
+/**
+ * Read data from the file specified by `fd`.
+ * @param fd
+ * @param buffer The buffer that the data will be
+ *   written to.
+ * @param offset The offset within the buffer where writing will
+ *   start.
+ * @param length An integer specifying the number of bytes to read.
+ * @param position An integer specifying where to begin reading from
+ *   in the file. If position is null, data will be read from the current file
+ *   position.
+ */
+export declare function readSync(fd: number, buffer: Buffer, opts?: ReadSyncOptions): number;
+export declare function readSync(fd: number, buffer: Buffer, offset: number, length: number, position?: number): number;
+/**
+ * Synchronous `fchown`.
+ * @param fd
+ * @param uid
+ * @param gid
+ */
+export declare function fchownSync(fd: number, uid: number, gid: number): void;
+/**
+ * Synchronous `fchmod`.
+ * @param fd
+ * @param mode
+ */
+export declare function fchmodSync(fd: number, mode: number | string): void;
+/**
+ * Change the file timestamps of a file referenced by the supplied file
+ * descriptor.
+ * @param fd
+ * @param atime
+ * @param mtime
+ */
+export declare function futimesSync(fd: number, atime: number | Date, mtime: number | Date): void;
+/**
+ * Synchronous `rmdir`.
+ * @param path
+ */
+export declare function rmdirSync(path: string): void;
+/**
+ * Synchronous `mkdir`.
+ * @param path
+ * @param mode defaults to `0777`
+ */
+export declare function mkdirSync(path: string, mode?: number | string): void;
+/**
+ * Synchronous `readdir`. Reads the contents of a directory.
+ * @param path
+ * @return [String[]]
+ */
+export declare function readdirSync(path: string): string[];
+/**
+ * Synchronous `link`.
+ * @param srcpath
+ * @param dstpath
+ */
+export declare function linkSync(srcpath: string, dstpath: string): void;
+/**
+ * Synchronous `symlink`.
+ * @param srcpath
+ * @param dstpath
+ * @param type can be either `'dir'` or `'file'` (default is `'file'`)
+ */
+export declare function symlinkSync(srcpath: string, dstpath: string, type?: symlink.Type): void;
+/**
+ * Synchronous readlink.
+ * @param path
+ * @return [String]
+ */
+export declare function readlinkSync(path: string): string;
+/**
+ * Synchronous `chown`.
+ * @param path
+ * @param uid
+ * @param gid
+ */
+export declare function chownSync(path: string, uid: number, gid: number): void;
+/**
+ * Synchronous `lchown`.
+ * @param path
+ * @param uid
+ * @param gid
+ */
+export declare function lchownSync(path: string, uid: number, gid: number): void;
+/**
+ * Synchronous `chmod`.
+ * @param path
+ * @param mode
+ */
+export declare function chmodSync(path: string, mode: string | number): void;
+/**
+ * Synchronous `lchmod`.
+ * @param path
+ * @param mode
+ */
+export declare function lchmodSync(path: string, mode: number | string): void;
+/**
+ * Change file timestamps of the file referenced by the supplied path.
+ * @param path
+ * @param atime
+ * @param mtime
+ */
+export declare function utimesSync(path: string, atime: number | Date, mtime: number | Date): void;
+/**
+ * Change file timestamps of the file referenced by the supplied path.
+ * @param path
+ * @param atime
+ * @param mtime
+ */
+export declare function lutimesSync(path: string, atime: number | Date, mtime: number | Date): void;
+/**
+ * Synchronous `realpath`.
+ * @param path
+ * @param cache An object literal of mapped paths that can be used to
+ *   force a specific path resolution or avoid additional `fs.stat` calls for
+ *   known real paths.
+ * @return [String]
+ */
+export declare function realpathSync(path: string, cache?: {
+    [path: string]: string;
+}): string;
+/**
+ * Synchronous `access`.
+ * @param path
+ * @param mode
+ */
+export declare function accessSync(path: string, mode?: number): void;