@zenfs/core 0.1.0 → 0.2.0

package/dist/file.d.ts

@@ -1,26 +1,43 @@
-import { Stats } from './stats.js';
-import { FileSystem } from './filesystem.js';
+import { Stats, type FileType } from './stats.js';
+import { FileSystem, type SyncFileSystem } from './filesystem.js';
+declare global {
+    interface ArrayBuffer {
+        readonly resizable: boolean;
+        readonly maxByteLength?: number;
+        resize(newLength: number): void;
+    }
+    interface SharedArrayBuffer {
+        readonly resizable: boolean;
+        readonly maxByteLength?: number;
+        resize(newLength: number): void;
+    }
+    interface ArrayBufferConstructor {
+        new (byteLength: number, options: {
+            maxByteLength?: number;
+        }): ArrayBuffer;
+    }
+}
 export declare enum ActionType {
     NOP = 0,
-    THROW_EXCEPTION = 1,
-    TRUNCATE_FILE = 2,
-    CREATE_FILE = 3
+    THROW = 1,
+    TRUNCATE = 2,
+    CREATE = 3
 }
 /**
  * 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.
  */
@@ -33,7 +50,7 @@ export declare class FileFlag {
      * @return The FileFlag object representing the flag
      * @throw when the flag string is invalid
      */
-    static getFileFlag(flag: string | number): FileFlag;
+    static FromString(flag: string | number): FileFlag;
     private flagStr;
     /**
      * This should never be called directly.
@@ -46,16 +63,16 @@ export declare class FileFlag {
      * @return The string representing the flag
      * @throw when the flag number is invalid
      */
-    static StringFromNumber(flag: number): string;
+    static NumberToString(flag: number): string;
     /**
      * Get the underlying flag string for this flag.
      */
-    getFlagString(): string;
+    toString(): string;
     /**
      * Get the equivalent mode (0b0xxx: read, write, execute)
      * Note: Execute will always be 0
      */
-    getMode(): number;
+    get mode(): number;
     /**
      * Returns true if the file is readable.
      */
@@ -91,45 +108,49 @@ export declare class FileFlag {
      */
     pathNotExistsAction(): ActionType;
 }
-export interface File {
+export declare abstract class File {
     /**
-     * **Core**: Get the current file position.
+     * Get the current file position.
      */
-    getPos(): number | undefined;
+    abstract position?: number;
     /**
-     * **Core**: Asynchronous `stat`.
+     * The path to the file
      */
-    stat(): Promise<Stats>;
+    abstract readonly path?: string;
     /**
-     * **Core**: Synchronous `stat`.
+     * Asynchronous `stat`.
      */
-    statSync(): Stats;
+    abstract stat(): Promise<Stats>;
     /**
-     * **Core**: Asynchronous close.
+     * Synchronous `stat`.
      */
-    close(): Promise<void>;
+    abstract statSync(): Stats;
     /**
-     * **Core**: Synchronous close.
+     * Asynchronous close.
      */
-    closeSync(): void;
+    abstract close(): Promise<void>;
     /**
-     * **Core**: Asynchronous truncate.
+     * Synchronous close.
      */
-    truncate(len: number): Promise<void>;
+    abstract closeSync(): void;
     /**
-     * **Core**: Synchronous truncate.
+     * Asynchronous truncate.
      */
-    truncateSync(len: number): void;
+    abstract truncate(len: number): Promise<void>;
     /**
-     * **Core**: Asynchronous sync.
+     * Synchronous truncate.
      */
-    sync(): Promise<void>;
+    abstract truncateSync(len: number): void;
     /**
-     * **Core**: Synchronous sync.
+     * Asynchronous sync.
      */
-    syncSync(): void;
+    abstract sync(): Promise<void>;
+    /**
+     * Synchronous sync.
+     */
+    abstract syncSync(): void;
     /**
-     * **Core**: Write buffer to the file.
+     * 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 buffer Uint8Array containing the data to write to
@@ -141,9 +162,9 @@ export interface File {
      *   the current position.
      * @returns Promise resolving to the new length of the buffer
      */
-    write(buffer: Uint8Array, offset: number, length: number, position: number | null): Promise<number>;
+    abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     /**
-     * **Core**: Write buffer to the file.
+     * Write buffer to the file.
      * Note that it is unsafe to use fs.writeSync multiple times on the same file
      * without waiting for it to return.
      * @param buffer Uint8Array containing the data to write to
@@ -154,9 +175,9 @@ export interface File {
      *   data should be written. If position is null, the data will be written at
      *   the current position.
      */
-    writeSync(buffer: Uint8Array, offset: number, length: number, position: number | null): number;
+    abstract writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
-     * **Core**: Read data from the file.
+     * Read data from the file.
      * @param buffer The buffer that the data will be
      *   written to.
      * @param offset The offset within the buffer where writing will
@@ -167,12 +188,12 @@ export interface File {
      *   position.
      * @returns Promise resolving to the new length of the buffer
      */
-    read(buffer: Uint8Array, offset: number, length: number, position: number | null): Promise<{
+    abstract read<TBuffer extends Uint8Array>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
         bytesRead: number;
-        buffer: Uint8Array;
+        buffer: TBuffer;
     }>;
     /**
-     * **Core**: Read data from the file.
+     * Read data from the file.
      * @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.
@@ -180,59 +201,53 @@ export interface File {
      *   in the file. If position is null, data will be read from the current file
      *   position.
      */
-    readSync(buffer: Uint8Array, offset: number, length: number, position: number): number;
+    abstract readSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
-     * **Supplementary**: Asynchronous `datasync`.
+     * Asynchronous `datasync`.
      *
      * Default implementation maps to `sync`.
      */
     datasync(): Promise<void>;
     /**
-     * **Supplementary**: Synchronous `datasync`.
+     * Synchronous `datasync`.
      *
      * Default implementation maps to `syncSync`.
      */
     datasyncSync(): void;
     /**
-     * **Optional**: Asynchronous `chown`.
+     * Asynchronous `chown`.
      */
-    chown(uid: number, gid: number): Promise<void>;
+    abstract chown(uid: number, gid: number): Promise<void>;
     /**
-     * **Optional**: Synchronous `chown`.
+     * Synchronous `chown`.
      */
-    chownSync(uid: number, gid: number): void;
+    abstract chownSync(uid: number, gid: number): void;
     /**
-     * **Optional**: Asynchronous `fchmod`.
+     * Asynchronous `fchmod`.
      */
-    chmod(mode: number): Promise<void>;
+    abstract chmod(mode: number): Promise<void>;
     /**
-     * **Optional**: Synchronous `fchmod`.
+     * Synchronous `fchmod`.
      */
-    chmodSync(mode: number): void;
+    abstract chmodSync(mode: number): void;
     /**
-     * **Optional**: Change the file timestamps of the file.
+     * Change the file timestamps of the file.
      */
-    utimes(atime: Date, mtime: Date): Promise<void>;
+    abstract utimes(atime: Date, mtime: Date): Promise<void>;
     /**
-     * **Optional**: Change the file timestamps of the file.
+     * Change the file timestamps of the file.
      */
-    utimesSync(atime: Date, mtime: Date): void;
-}
-/**
- * Base class that contains shared implementations of functions for the file
- * object.
- */
-export declare class BaseFile {
-    sync(): Promise<void>;
-    syncSync(): void;
-    datasync(): Promise<void>;
-    datasyncSync(): void;
-    chown(uid: number, gid: number): Promise<void>;
-    chownSync(uid: number, gid: number): void;
-    chmod(mode: number): Promise<void>;
-    chmodSync(mode: number): void;
-    utimes(atime: Date, mtime: Date): Promise<void>;
-    utimesSync(atime: Date, mtime: Date): void;
+    abstract utimesSync(atime: Date, mtime: Date): void;
+    /**
+     * Set the file type
+     * @internal
+     */
+    abstract _setType(type: FileType): Promise<void>;
+    /**
+     * Set the file type
+     * @internal
+     */
+    abstract _setTypeSync(type: FileType): void;
 }
 /**
  * An implementation of the File interface that operates on a file that is
@@ -243,43 +258,45 @@ export declare class BaseFile {
  * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
-export declare class PreloadFile<T extends FileSystem> extends BaseFile {
-    protected _fs: T;
-    protected _pos: number;
-    protected _path: string;
-    protected _stat: Stats;
-    protected _flag: FileFlag;
+export declare abstract class PreloadFile<T extends FileSystem> extends File {
+    /**
+     * The file system that created the file.
+     */
+    protected fs: T;
+    /**
+     * Path to the file
+     */
+    readonly path: string;
+    readonly flag: FileFlag;
+    readonly stats: Stats;
     protected _buffer: Uint8Array;
+    protected _position: number;
     protected _dirty: boolean;
     /**
      * 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: T, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
+    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(): Uint8Array;
+    fs: T, 
     /**
-     * NONSTANDARD: Get underlying stats for this file. !!DO NOT MUTATE!!
+     * Path to the file
      */
-    getStats(): Stats;
-    getFlag(): FileFlag;
+    path: string, flag: FileFlag, stats: Stats, _buffer?: Uint8Array);
     /**
-     * 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(): string;
+    get buffer(): Uint8Array;
     /**
      * Get the current file position.
      *
@@ -287,42 +304,16 @@ export declare class PreloadFile<T extends FileSystem> 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.
-     */
-    getPos(): number;
-    /**
-     * Advance the current file position by the indicated number of positions.
-     * @param [Number] delta
+     * @return The current file position.
      */
-    advancePos(delta: number): number;
+    get position(): number;
     /**
      * Set the file position.
-     * @param [Number] newPos
-     */
-    setPos(newPos: number): number;
-    /**
-     * **Core**: Asynchronous sync. Must be implemented by subclasses of this
-     * class.
-     * @param [Function(ZenFS.ApiError)] cb
+     * @param newPos new position
      */
-    sync(): Promise<void>;
-    /**
-     * **Core**: Synchronous sync.
-     */
-    syncSync(): void;
-    /**
-     * **Core**: Asynchronous close. Must be implemented by subclasses of this
-     * class.
-     * @param [Function(ZenFS.ApiError)] cb
-     */
-    close(): Promise<void>;
-    /**
-     * **Core**: Synchronous close.
-     */
-    closeSync(): void;
+    set position(newPos: number);
     /**
      * Asynchronous `stat`.
-     * @param [Function(ZenFS.ApiError, ZenFS.node.fs.Stats)] cb
      */
     stat(): Promise<Stats>;
     /**
@@ -331,111 +322,117 @@ export declare class PreloadFile<T extends FileSystem> extends BaseFile {
     statSync(): Stats;
     /**
      * Asynchronous truncate.
-     * @param [Number] len
-     * @param [Function(ZenFS.ApiError)] cb
+     * @param len
      */
     truncate(len: number): Promise<void>;
     /**
      * Synchronous truncate.
-     * @param [Number] len
+     * @param len
      */
     truncateSync(len: number): void;
     /**
      * 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.
      */
-    write(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
+    write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     /**
      * 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: Uint8Array, offset: number, length: number, position: number): number;
+    writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
      * 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
      */
-    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+    read<TBuffer extends Uint8Array>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
         bytesRead: number;
-        buffer: Uint8Array;
+        buffer: TBuffer;
     }>;
     /**
      * 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: Uint8Array, offset: number, length: number, position: number): number;
+    readSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
      * Asynchronous `fchmod`.
-     * @param [Number|String] mode
+     * @param mode the mode
      */
     chmod(mode: number): Promise<void>;
     /**
      * Synchronous `fchmod`.
-     * @param [Number] mode
+     * @param mode
      */
     chmodSync(mode: number): void;
     /**
      * Asynchronous `fchown`.
-     * @param [Number] uid
-     * @param [Number] gid
+     * @param uid
+     * @param gid
      */
     chown(uid: number, gid: number): Promise<void>;
     /**
      * Synchronous `fchown`.
-     * @param [Number] uid
-     * @param [Number] gid
+     * @param uid
+     * @param gid
      */
     chownSync(uid: number, gid: number): void;
+    utimes(atime: Date, mtime: Date): Promise<void>;
+    utimesSync(atime: Date, mtime: Date): void;
     protected isDirty(): boolean;
     /**
      * Resets the dirty bit. Should only be called after a sync has completed successfully.
      */
     protected resetDirty(): void;
+    _setType(type: FileType): Promise<void>;
+    _setTypeSync(type: FileType): void;
+}
+/**
+ * For synchronous file systems
+ */
+export declare class SyncFile<FS extends SyncFileSystem> extends PreloadFile<FS> {
+    constructor(_fs: FS, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
+    sync(): Promise<void>;
+    syncSync(): void;
+    close(): Promise<void>;
+    closeSync(): void;
 }
 /**
- * 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 declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> implements File {
+export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
     constructor(_fs: T, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
     /**
      * Asynchronous sync. Doesn't do anything, simply calls the cb.
-     * @param [Function(ZenFS.ApiError)] cb
      */
     sync(): Promise<void>;
     /**
@@ -444,7 +441,6 @@ export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> imp
     syncSync(): void;
     /**
      * Asynchronous close. Doesn't do anything, simply calls the cb.
-     * @param [Function(ZenFS.ApiError)] cb
      */
     close(): Promise<void>;
     /**