@zenfs/core
Version:
A filesystem, anywhere
270 lines (269 loc) • 10.8 kB
TypeScript
import type { FileReadResult } from 'node:fs/promises';
import type { FileSystem } from './filesystem.js';
import './polyfills.js';
import { Stats, type FileType } from './stats.js';
/**
Typescript does not include a type declaration for resizable array buffers.
It has been standardized into ECMAScript though
@todo Remove this if TS adds them to lib declarations
*/
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 function parseFlag(flag: string | number): string;
export declare function flagToString(flag: number): string;
export declare function flagToNumber(flag: string): number;
/**
* Parses a flag as a mode (W_OK, R_OK, and/or X_OK)
* @param flag the flag to parse
*/
export declare function flagToMode(flag: string): number;
export declare function isReadable(flag: string): boolean;
export declare function isWriteable(flag: string): boolean;
export declare function isTruncating(flag: string): boolean;
export declare function isAppendable(flag: string): boolean;
export declare function isSynchronous(flag: string): boolean;
export declare function isExclusive(flag: string): boolean;
export declare abstract class File {
/**
* @internal
* The file system that created the file
*/
fs: FileSystem;
readonly path: string;
constructor(
/**
* @internal
* The file system that created the file
*/
fs: FileSystem, path: string);
/**
* Get the current file position.
*/
abstract position: number;
abstract stat(): Promise<Stats>;
abstract statSync(): Stats;
abstract close(): Promise<void>;
abstract closeSync(): void;
[Symbol.asyncDispose](): Promise<void>;
[Symbol.dispose](): void;
abstract truncate(len: number): Promise<void>;
abstract truncateSync(len: number): void;
abstract sync(): Promise<void>;
abstract syncSync(): void;
/**
* Write buffer to the file.
* @param buffer Uint8Array 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.
* @returns Promise resolving to the new length of the buffer
*/
abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
/**
* Write buffer to the file.
* @param buffer Uint8Array 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.
*/
abstract writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
/**
* 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.
* @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.
* @returns Promise resolving to the new length of the buffer
*/
abstract read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>>;
/**
* 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.
* @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.
*/
abstract readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
/**
* Default implementation maps to `sync`.
*/
datasync(): Promise<void>;
/**
* Default implementation maps to `syncSync`.
*/
datasyncSync(): void;
abstract chown(uid: number, gid: number): Promise<void>;
abstract chownSync(uid: number, gid: number): void;
abstract chmod(mode: number): Promise<void>;
abstract chmodSync(mode: number): void;
/**
* Change the file timestamps of the file.
*/
abstract utimes(atime: Date, mtime: Date): Promise<void>;
/**
* Change the file timestamps of the file.
*/
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 `File` that operates completely in-memory.
* `PreloadFile`s are backed by a `Uint8Array`.
*/
export declare class PreloadFile<FS extends FileSystem> extends File {
/**
* The file system that created the file.
* @internal
*/
fs: FS;
readonly flag: string;
readonly stats: Stats;
/**
* A buffer containing the entire contents of the file.
*/
protected _buffer: Uint8Array;
/**
* Current position
*/
protected _position: number;
/**
* Whether the file has changes which have not been written to the FS
*/
protected dirty: boolean;
/**
* Whether the file is open or closed
*/
protected closed: boolean;
/**
* Creates a file with `path` and, optionally, the given contents.
* Note that, if contents is specified, it will be mutated by the file.
*/
constructor(
/**
* The file system that created the file.
* @internal
*/
fs: FS, path: string, flag: string, stats: Stats,
/**
* A buffer containing the entire contents of the file.
*/
_buffer?: Uint8Array);
/**
* Get the underlying buffer for this file. Mutating not recommended and will mess up dirty tracking.
*/
get buffer(): Uint8Array;
/**
* Get the current file position.
*
* We emulate the following bug mentioned in the Node documentation:
*
* 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.
* @returns The current file position.
*/
get position(): number;
set position(value: number);
sync(): Promise<void>;
syncSync(): void;
close(): Promise<void>;
closeSync(): void;
/**
* Cleans up. This will *not* sync the file data to the FS
*/
protected dispose(force?: boolean): void;
stat(): Promise<Stats>;
statSync(): Stats;
protected _truncate(length: number): void;
truncate(length: number): Promise<void>;
truncateSync(length: number): void;
protected _write(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
/**
* Write buffer to the file.
* @param buffer Uint8Array 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.
*/
write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
/**
* Write buffer to the file.
* @param buffer Uint8Array 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.
* @returns bytes written
*/
writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
protected _read(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
/**
* 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.
* @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.
*/
read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
bytesRead: number;
buffer: TBuffer;
}>;
/**
* 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.
* @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.
* @returns number of bytes written
*/
readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
chmod(mode: number): Promise<void>;
chmodSync(mode: number): void;
chown(uid: number, gid: number): Promise<void>;
chownSync(uid: number, gid: number): void;
utimes(atime: Date, mtime: Date): Promise<void>;
utimesSync(atime: Date, mtime: Date): void;
_setType(type: FileType): Promise<void>;
_setTypeSync(type: FileType): void;
[Symbol.asyncDispose](): Promise<void>;
[Symbol.dispose](): void;
}
/**
* For the file systems which do not sync to anything.
*/
export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
sync(): Promise<void>;
syncSync(): void;
close(): Promise<void>;
closeSync(): void;
}