@zenfs/core 0.1.0 → 0.2.0

package/dist/file.js

@@ -1,33 +1,33 @@
 import { ApiError, ErrorCode } from './ApiError.js';
 import { Stats } from './stats.js';
-import { getMount } from './emulation/shared.js';
-import { O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_SYNC } from './emulation/constants.js';
+import { O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_SYNC, S_IFMT } from './emulation/constants.js';
+import { size_max } from './inode.js';
 export var ActionType;
 (function (ActionType) {
     // Indicates that the code should not do anything.
     ActionType[ActionType["NOP"] = 0] = "NOP";
     // Indicates that the code should throw an exception.
-    ActionType[ActionType["THROW_EXCEPTION"] = 1] = "THROW_EXCEPTION";
+    ActionType[ActionType["THROW"] = 1] = "THROW";
     // Indicates that the code should truncate the file, but only if it is a file.
-    ActionType[ActionType["TRUNCATE_FILE"] = 2] = "TRUNCATE_FILE";
+    ActionType[ActionType["TRUNCATE"] = 2] = "TRUNCATE";
     // Indicates that the code should create the file.
-    ActionType[ActionType["CREATE_FILE"] = 3] = "CREATE_FILE";
+    ActionType[ActionType["CREATE"] = 3] = "CREATE";
 })(ActionType = ActionType || (ActionType = {}));
 /**
  * Represents one of the following file flags. A convenience object.
  *
- * * `'r'` - Open file for reading. An exception occurs if the file does not exist.
- * * `'r+'` - Open file for reading and writing. An exception occurs if the file does not exist.
- * * `'rs'` - Open file for reading in synchronous mode. Instructs the filesystem to not cache writes.
- * * `'rs+'` - Open file for reading and writing, and opens the file in synchronous mode.
- * * `'w'` - Open file for writing. The file is created (if it does not exist) or truncated (if it exists).
- * * `'wx'` - Like 'w' but opens the file in exclusive mode.
- * * `'w+'` - Open file for reading and writing. The file is created (if it does not exist) or truncated (if it exists).
- * * `'wx+'` - Like 'w+' but opens the file in exclusive mode.
- * * `'a'` - Open file for appending. The file is created if it does not exist.
- * * `'ax'` - Like 'a' but opens the file in exclusive mode.
- * * `'a+'` - Open file for reading and appending. The file is created if it does not exist.
- * * `'ax+'` - Like 'a+' but opens the file in exclusive mode.
+ * - r: 	Open file for reading. An exception occurs if the file does not exist.
+ * - r+: 	Open file for reading and writing. An exception occurs if the file does not exist.
+ * - rs: 	Open file for reading in synchronous mode. Instructs the filesystem to not cache writes.
+ * - rs+: 	Open file for reading and writing, and opens the file in synchronous mode.
+ * - w: 	Open file for writing. The file is created (if it does not exist) or truncated (if it exists).
+ * - wx: 	Like 'w' but opens the file in exclusive mode.
+ * - w+: 	Open file for reading and writing. The file is created (if it does not exist) or truncated (if it exists).
+ * - wx+: 	Like 'w+' but opens the file in exclusive mode.
+ * - a: 	Open file for appending. The file is created if it does not exist.
+ * - ax: 	Like 'a' but opens the file in exclusive mode.
+ * - a+: 	Open file for reading and appending. The file is created if it does not exist.
+ * - ax+: 	Like 'a+' but opens the file in exclusive mode.
  *
  * Exclusive mode ensures that the file path is newly created.
  */
@@ -38,7 +38,7 @@ export class FileFlag {
      * @return The FileFlag object representing the flag
      * @throw when the flag string is invalid
      */
-    static getFileFlag(flag) {
+    static FromString(flag) {
         // Check cache first.
         if (!FileFlag.flagCache.has(flag)) {
             FileFlag.flagCache.set(flag, new FileFlag(flag));
@@ -52,7 +52,7 @@ export class FileFlag {
      */
     constructor(flag) {
         if (typeof flag === 'number') {
-            flag = FileFlag.StringFromNumber(flag);
+            flag = FileFlag.NumberToString(flag);
         }
         if (FileFlag.validFlagStrs.indexOf(flag) < 0) {
             throw new ApiError(ErrorCode.EINVAL, 'Invalid flag string: ' + flag);
@@ -64,7 +64,7 @@ export class FileFlag {
      * @return The string representing the flag
      * @throw when the flag number is invalid
      */
-    static StringFromNumber(flag) {
+    static NumberToString(flag) {
         // based on https://github.com/nodejs/node/blob/abbdc3efaa455e6c907ebef5409ac8b0f222f969/lib/internal/fs/utils.js#L619
         switch (flag) {
             case O_RDONLY:
@@ -98,14 +98,14 @@ export class FileFlag {
     /**
      * Get the underlying flag string for this flag.
      */
-    getFlagString() {
+    toString() {
         return this.flagStr;
     }
     /**
      * Get the equivalent mode (0b0xxx: read, write, execute)
      * Note: Execute will always be 0
      */
-    getMode() {
+    get mode() {
         let mode = 0;
         mode <<= 1;
         mode += +this.isReadable();
@@ -156,14 +156,12 @@ export class FileFlag {
      */
     pathExistsAction() {
         if (this.isExclusive()) {
-            return ActionType.THROW_EXCEPTION;
+            return ActionType.THROW;
         }
-        else if (this.isTruncating()) {
-            return ActionType.TRUNCATE_FILE;
-        }
-        else {
-            return ActionType.NOP;
+        if (this.isTruncating()) {
+            return ActionType.TRUNCATE;
         }
+        return ActionType.NOP;
     }
     /**
      * Returns one of the static fields on this object that indicates the
@@ -171,10 +169,10 @@ export class FileFlag {
      */
     pathNotExistsAction() {
         if ((this.isWriteable() || this.isAppendable()) && this.flagStr !== 'r+') {
-            return ActionType.CREATE_FILE;
+            return ActionType.CREATE;
         }
         else {
-            return ActionType.THROW_EXCEPTION;
+            return ActionType.THROW;
         }
     }
 }
@@ -182,41 +180,23 @@ export class FileFlag {
 FileFlag.flagCache = new Map();
 // Array of valid mode strings.
 FileFlag.validFlagStrs = ['r', 'r+', 'rs', 'rs+', 'w', 'wx', 'w+', 'wx+', 'a', 'ax', 'a+', 'ax+'];
-/**
- * Base class that contains shared implementations of functions for the file
- * object.
- */
-export class BaseFile {
-    async sync() {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    syncSync() {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    async datasync() {
+export class File {
+    /**
+     * Asynchronous `datasync`.
+     *
+     * Default implementation maps to `sync`.
+     */
+    datasync() {
         return this.sync();
     }
+    /**
+     * Synchronous `datasync`.
+     *
+     * Default implementation maps to `syncSync`.
+     */
     datasyncSync() {
         return this.syncSync();
     }
-    async chown(uid, gid) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    chownSync(uid, gid) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    async chmod(mode) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    chmodSync(mode) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    async utimes(atime, mtime) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    utimesSync(atime, mtime) {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
 }
 /**
  * An implementation of the File interface that operates on a file that is
@@ -227,59 +207,54 @@ export class BaseFile {
  * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
-export class PreloadFile extends BaseFile {
+export class PreloadFile extends File {
     /**
      * Creates a file with the given path and, optionally, the given contents. Note
      * that, if contents is specified, it will be mutated by the file!
-     * @param _fs The file system that created the file.
-     * @param _path
      * @param _mode The mode that the file was opened using.
      *   Dictates permissions and where the file pointer starts.
-     * @param _stat The stats object for the given file.
+     * @param stats The stats object for the given file.
      *   PreloadFile will mutate this object. Note that this object must contain
      *   the appropriate mode that the file was opened as.
-     * @param contents A buffer containing the entire
+     * @param buffer A buffer containing the entire
      *   contents of the file. PreloadFile will mutate this buffer. If not
      *   specified, we assume it is a new file.
      */
-    constructor(_fs, _path, _flag, _stat, contents) {
-        super();
-        this._pos = 0;
-        this._dirty = false;
-        this._fs = _fs;
-        this._path = _path;
-        this._flag = _flag;
-        this._stat = _stat;
-        this._buffer = contents ? contents : new Uint8Array(0);
-        // Note: This invariant is *not* maintained once the file starts getting
-        // modified.
-        // Note: Only actually matters if file is readable, as writeable modes may
-        // truncate/append to file.
-        if (this._stat.size !== this._buffer.length && this._flag.isReadable()) {
-            throw new Error(`Invalid buffer: Uint8Array is ${this._buffer.length} long, yet Stats object specifies that file is ${this._stat.size} long.`);
-        }
-    }
+    constructor(
     /**
-     * NONSTANDARD: Get the underlying buffer for this file. !!DO NOT MUTATE!! Will mess up dirty tracking.
+     * The file system that created the file.
      */
-    getBuffer() {
-        return this._buffer;
-    }
+    fs, 
     /**
-     * NONSTANDARD: Get underlying stats for this file. !!DO NOT MUTATE!!
+     * Path to the file
      */
-    getStats() {
-        return this._stat;
-    }
-    getFlag() {
-        return this._flag;
+    path, flag, stats, _buffer = new Uint8Array(new ArrayBuffer(0, { maxByteLength: size_max }))) {
+        super();
+        this.fs = fs;
+        this.path = path;
+        this.flag = flag;
+        this.stats = stats;
+        this._buffer = _buffer;
+        this._position = 0;
+        this._dirty = false;
+        /*
+            Note:
+            This invariant is *not* maintained once the file starts getting modified.
+            It only actually matters if file is readable, as writeable modes may truncate/append to file.
+        */
+        if (this.stats.size == _buffer.byteLength) {
+            return;
+        }
+        if (this.flag.isReadable()) {
+            throw new Error(`Size mismatch: buffer length ${_buffer.byteLength}, stats size ${this.stats.size}`);
+        }
+        this._dirty = true;
     }
     /**
-     * Get the path to this file.
-     * @return [String] The path to the file.
+     * Get the underlying buffer for this file. Mutating not recommended and will mess up dirty tracking.
      */
-    getPath() {
-        return this._path;
+    get buffer() {
+        return this._buffer;
     }
     /**
      * Get the current file position.
@@ -288,103 +263,66 @@ export class PreloadFile extends BaseFile {
      * > On Linux, positional writes don't work when the file is opened in append
      *   mode. The kernel ignores the position argument and always appends the data
      *   to the end of the file.
-     * @return [Number] The current file position.
+     * @return The current file position.
      */
-    getPos() {
-        if (this._flag.isAppendable()) {
-            return this._stat.size;
+    get position() {
+        if (this.flag.isAppendable()) {
+            return this.stats.size;
         }
-        return this._pos;
-    }
-    /**
-     * Advance the current file position by the indicated number of positions.
-     * @param [Number] delta
-     */
-    advancePos(delta) {
-        return (this._pos += delta);
+        return this._position;
     }
     /**
      * Set the file position.
-     * @param [Number] newPos
-     */
-    setPos(newPos) {
-        return (this._pos = newPos);
-    }
-    /**
-     * **Core**: Asynchronous sync. Must be implemented by subclasses of this
-     * class.
-     * @param [Function(ZenFS.ApiError)] cb
+     * @param newPos new position
      */
-    async sync() {
-        this.syncSync();
-    }
-    /**
-     * **Core**: Synchronous sync.
-     */
-    syncSync() {
-        throw new ApiError(ErrorCode.ENOTSUP);
-    }
-    /**
-     * **Core**: Asynchronous close. Must be implemented by subclasses of this
-     * class.
-     * @param [Function(ZenFS.ApiError)] cb
-     */
-    async close() {
-        this.closeSync();
-    }
-    /**
-     * **Core**: Synchronous close.
-     */
-    closeSync() {
-        throw new ApiError(ErrorCode.ENOTSUP);
+    set position(newPos) {
+        this._position = newPos;
     }
     /**
      * Asynchronous `stat`.
-     * @param [Function(ZenFS.ApiError, ZenFS.node.fs.Stats)] cb
      */
     async stat() {
-        return Stats.clone(this._stat);
+        return Stats.clone(this.stats);
     }
     /**
      * Synchronous `stat`.
      */
     statSync() {
-        return Stats.clone(this._stat);
+        return Stats.clone(this.stats);
     }
     /**
      * Asynchronous truncate.
-     * @param [Number] len
-     * @param [Function(ZenFS.ApiError)] cb
+     * @param len
      */
     truncate(len) {
         this.truncateSync(len);
-        if (this._flag.isSynchronous() && !getMount('/').metadata.synchronous) {
+        if (this.flag.isSynchronous() && !this.fs.metadata.synchronous) {
             return this.sync();
         }
     }
     /**
      * Synchronous truncate.
-     * @param [Number] len
+     * @param len
      */
     truncateSync(len) {
         this._dirty = true;
-        if (!this._flag.isWriteable()) {
+        if (!this.flag.isWriteable()) {
             throw new ApiError(ErrorCode.EPERM, 'File not opened with a writeable mode.');
         }
-        this._stat.mtimeMs = Date.now();
+        this.stats.mtimeMs = Date.now();
         if (len > this._buffer.length) {
             const buf = new Uint8Array(len - this._buffer.length);
-            // Write will set @_stat.size for us.
+            // Write will set stats.size for us.
             this.writeSync(buf, 0, buf.length, this._buffer.length);
-            if (this._flag.isSynchronous() && getMount('/').metadata.synchronous) {
+            if (this.flag.isSynchronous() && this.fs.metadata.synchronous) {
                 this.syncSync();
             }
             return;
         }
-        this._stat.size = len;
+        this.stats.size = len;
         // Truncate buffer to 'len'.
         this._buffer = this._buffer.subarray(0, len);
-        if (this._flag.isSynchronous() && getMount('/').metadata.synchronous) {
+        if (this.flag.isSynchronous() && this.fs.metadata.synchronous) {
             this.syncSync();
         }
     }
@@ -392,142 +330,155 @@ export class PreloadFile extends BaseFile {
      * Write buffer to the file.
      * Note that it is unsafe to use fs.write multiple times on the same file
      * without waiting for the callback.
-     * @param [ZenFS.node.Uint8Array] buffer Uint8Array containing the data to write to
+     * @param buffer Uint8Array containing the data to write to
      *  the file.
-     * @param [Number] offset Offset in the buffer to start reading data from.
-     * @param [Number] length The amount of bytes to write to the file.
-     * @param [Number] position Offset from the beginning of the file where this
+     * @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.
-     * @param [Function(ZenFS.ApiError, Number, ZenFS.node.Uint8Array)]
-     *   cb The number specifies the number of bytes written into the file.
      */
-    async write(buffer, offset, length, position) {
+    async write(buffer, offset = 0, length = this.stats.size, position = 0) {
         return this.writeSync(buffer, offset, length, position);
     }
     /**
      * Write buffer to the file.
      * Note that it is unsafe to use fs.writeSync multiple times on the same file
      * without waiting for the callback.
-     * @param [ZenFS.node.Uint8Array] buffer Uint8Array containing the data to write to
+     * @param buffer Uint8Array containing the data to write to
      *  the file.
-     * @param [Number] offset Offset in the buffer to start reading data from.
-     * @param [Number] length The amount of bytes to write to the file.
-     * @param [Number] position Offset from the beginning of the file where this
+     * @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.
-     * @return [Number]
+     * @returns bytes written
      */
-    writeSync(buffer, offset, length, position) {
+    writeSync(buffer, offset = 0, length = this.stats.size, position = 0) {
         this._dirty = true;
-        if (position === undefined || position === null) {
-            position = this.getPos();
-        }
-        if (!this._flag.isWriteable()) {
+        position ?? (position = this.position);
+        if (!this.flag.isWriteable()) {
             throw new ApiError(ErrorCode.EPERM, 'File not opened with a writeable mode.');
         }
         const endFp = position + length;
-        if (endFp > this._stat.size) {
-            this._stat.size = endFp;
-            if (endFp > this._buffer.length) {
-                // Extend the buffer!
-                const newBuffer = new Uint8Array(endFp);
-                newBuffer.set(this._buffer);
-                this._buffer = newBuffer;
+        if (endFp > this.stats.size) {
+            this.stats.size = endFp;
+            if (endFp > this._buffer.byteLength) {
+                if (this._buffer.buffer.resizable && this._buffer.buffer.maxByteLength <= endFp) {
+                    this._buffer.buffer.resize(endFp);
+                }
+                else {
+                    // Extend the buffer!
+                    const newBuffer = new Uint8Array(new ArrayBuffer(endFp, { maxByteLength: size_max }));
+                    newBuffer.set(this._buffer);
+                    this._buffer = newBuffer;
+                }
             }
         }
         this._buffer.set(buffer.slice(offset, offset + length), position);
-        const len = this._buffer.length;
-        this._stat.mtimeMs = Date.now();
-        if (this._flag.isSynchronous()) {
+        const len = this._buffer.byteOffset;
+        this.stats.mtimeMs = Date.now();
+        if (this.flag.isSynchronous()) {
             this.syncSync();
             return len;
         }
-        this.setPos(position + len);
+        this.position = position + len;
         return len;
     }
     /**
      * Read data from the file.
-     * @param [ZenFS.node.Uint8Array] buffer The buffer that the data will be
+     * @param buffer The buffer that the data will be
      *   written to.
-     * @param [Number] offset The offset within the buffer where writing will
+     * @param offset The offset within the buffer where writing will
      *   start.
-     * @param [Number] length An integer specifying the number of bytes to read.
-     * @param [Number] position An integer specifying where to begin reading from
+     * @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.
-     * @param [Function(ZenFS.ApiError, Number, ZenFS.node.Uint8Array)] cb The
-     *   number is the number of bytes read
      */
-    async read(buffer, offset, length, position) {
+    async read(buffer, offset = 0, length = this.stats.size, position = 0) {
         return { bytesRead: this.readSync(buffer, offset, length, position), buffer };
     }
     /**
      * Read data from the file.
-     * @param [ZenFS.node.Uint8Array] buffer The buffer that the data will be
+     * @param buffer The buffer that the data will be
      *   written to.
-     * @param [Number] offset The offset within the buffer where writing will
-     *   start.
-     * @param [Number] length An integer specifying the number of bytes to read.
-     * @param [Number] position An integer specifying where to begin reading from
+     * @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.
-     * @return [Number]
+     * @returns number of bytes written
      */
-    readSync(buffer, offset, length, position) {
-        if (!this._flag.isReadable()) {
+    readSync(buffer, offset = 0, length = this.stats.size, position = 0) {
+        if (!this.flag.isReadable()) {
             throw new ApiError(ErrorCode.EPERM, 'File not opened with a readable mode.');
         }
-        if (position === undefined || position === null) {
-            position = this.getPos();
+        position ?? (position = this.position);
+        let end = position + length;
+        if (end > this.stats.size) {
+            end = position + Math.max(this.stats.size - position, 0);
         }
-        const endRead = position + length;
-        if (endRead > this._stat.size) {
-            length = this._stat.size - position;
+        this.stats.atimeMs = Date.now();
+        this._position = end;
+        const bytesRead = end - position;
+        if (bytesRead == 0) {
+            // No copy/read. Return immediatly for better performance
+            return bytesRead;
         }
-        this._buffer.set(buffer.slice(offset, offset + length), position);
-        this._stat.atimeMs = Date.now();
-        this._pos = position + length;
-        return this._buffer.length;
+        buffer.set(this._buffer.slice(position, end), offset);
+        return bytesRead;
     }
     /**
      * Asynchronous `fchmod`.
-     * @param [Number|String] mode
+     * @param mode the mode
      */
     async chmod(mode) {
         this.chmodSync(mode);
     }
     /**
      * Synchronous `fchmod`.
-     * @param [Number] mode
+     * @param mode
      */
     chmodSync(mode) {
-        if (!this._fs.metadata.supportsProperties) {
+        if (!this.fs.metadata.supportsProperties) {
             throw new ApiError(ErrorCode.ENOTSUP);
         }
         this._dirty = true;
-        this._stat.chmod(mode);
+        this.stats.chmod(mode);
         this.syncSync();
     }
     /**
      * Asynchronous `fchown`.
-     * @param [Number] uid
-     * @param [Number] gid
+     * @param uid
+     * @param gid
      */
     async chown(uid, gid) {
         this.chownSync(uid, gid);
     }
     /**
      * Synchronous `fchown`.
-     * @param [Number] uid
-     * @param [Number] gid
+     * @param uid
+     * @param gid
      */
     chownSync(uid, gid) {
-        if (!this._fs.metadata.supportsProperties) {
+        if (!this.fs.metadata.supportsProperties) {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        }
+        this._dirty = true;
+        this.stats.chown(uid, gid);
+        this.syncSync();
+    }
+    async utimes(atime, mtime) {
+        this.utimesSync(atime, mtime);
+    }
+    utimesSync(atime, mtime) {
+        if (!this.fs.metadata.supportsProperties) {
             throw new ApiError(ErrorCode.ENOTSUP);
         }
         this._dirty = true;
-        this._stat.chown(uid, gid);
+        this.stats.atime = atime;
+        this.stats.mtime = mtime;
         this.syncSync();
     }
     isDirty() {
@@ -539,10 +490,42 @@ export class PreloadFile extends BaseFile {
     resetDirty() {
         this._dirty = false;
     }
+    _setType(type) {
+        this._dirty = true;
+        this.stats.mode = (this.stats.mode & ~S_IFMT) | type;
+        return this.sync();
+    }
+    _setTypeSync(type) {
+        this._dirty = true;
+        this.stats.mode = (this.stats.mode & ~S_IFMT) | type;
+        this.syncSync();
+    }
+}
+/**
+ * For synchronous file systems
+ */
+export class SyncFile extends PreloadFile {
+    constructor(_fs, _path, _flag, _stat, contents) {
+        super(_fs, _path, _flag, _stat, contents);
+    }
+    async sync() {
+        this.syncSync();
+    }
+    syncSync() {
+        if (this.isDirty()) {
+            this.fs.syncSync(this.path, this._buffer, this.stats);
+            this.resetDirty();
+        }
+    }
+    async close() {
+        this.closeSync();
+    }
+    closeSync() {
+        this.syncSync();
+    }
 }
 /**
- * File class for the InMemory and XHR file systems.
- * Doesn't sync to anything, so it works nicely for memory-only files.
+ * For the filesystems which do not sync to anything..
  */
 export class NoSyncFile extends PreloadFile {
     constructor(_fs, _path, _flag, _stat, contents) {
@@ -550,7 +533,6 @@ export class NoSyncFile extends PreloadFile {
     }
     /**
      * Asynchronous sync. Doesn't do anything, simply calls the cb.
-     * @param [Function(ZenFS.ApiError)] cb
      */
     async sync() {
         return;
@@ -563,7 +545,6 @@ export class NoSyncFile extends PreloadFile {
     }
     /**
      * Asynchronous close. Doesn't do anything, simply calls the cb.
-     * @param [Function(ZenFS.ApiError)] cb
      */
     async close() {
         return;