@gjsify/fs 0.0.3 → 0.1.0

package/lib/types/callback.d.ts

@@ -0,0 +1,233 @@
+import { PathLike, OpenMode, Mode, ReadPosition, ReadAsyncOptions, NoParamCallback, RmOptions, RmDirOptions, MakeDirectoryOptions } from 'node:fs';
+import { Buffer } from 'node:buffer';
+import { Stats, BigIntStats } from './stats.js';
+export declare function stat(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void): void;
+export declare function stat(path: PathLike, options: {
+    bigint?: boolean;
+}, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void;
+export declare function lstat(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void): void;
+export declare function lstat(path: PathLike, options: {
+    bigint?: boolean;
+}, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void;
+export declare function readdir(path: PathLike, callback: (err: NodeJS.ErrnoException | null, files: string[]) => void): void;
+export declare function readdir(path: PathLike, options: {
+    withFileTypes?: boolean;
+    encoding?: string;
+    recursive?: boolean;
+}, callback: (err: NodeJS.ErrnoException | null, files: string[] | unknown[]) => void): void;
+export declare function realpath(path: PathLike, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void;
+export declare function realpath(path: PathLike, options: {
+    encoding?: BufferEncoding;
+}, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void;
+export declare function symlink(target: PathLike, path: PathLike, callback: NoParamCallback): void;
+export declare function symlink(target: PathLike, path: PathLike, type: string | null, callback: NoParamCallback): void;
+type OpenCallback = (err: NodeJS.ErrnoException | null, fd: number) => void;
+type WriteStrCallback = (err: NodeJS.ErrnoException | null, written: number, str: string) => void;
+type WriteBufCallback = <TBuffer extends NodeJS.ArrayBufferView>(err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void;
+type ReadCallback = (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void;
+/**
+ * Asynchronous file open. See the POSIX [`open(2)`](http://man7.org/linux/man-pages/man2/open.2.html) documentation for more details.
+ *
+ * `mode` sets the file mode (permission and sticky bits), but only if the file was
+ * created. On Windows, only the write permission can be manipulated; see {@link chmod}.
+ *
+ * The callback gets two arguments `(err, fd)`.
+ *
+ * Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
+ * by [Naming Files, Paths, and Namespaces](https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file). Under NTFS, if the filename contains
+ * a colon, Node.js will open a file system stream, as described by [this MSDN page](https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams).
+ *
+ * Functions based on `fs.open()` exhibit this behavior as well:`fs.writeFile()`, `fs.readFile()`, etc.
+ * @since v0.0.2
+ * @param [flags='r'] See `support of file system `flags``.
+ * @param [mode=0o666]
+ */
+export declare function open(path: PathLike, flags: OpenMode | undefined, mode: Mode | undefined | null, callback: OpenCallback): void;
+/**
+ * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`.
+ * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+ * @param [flags='r'] See `support of file system `flags``.
+ */
+export declare function open(path: PathLike, flags: OpenMode | undefined, callback: OpenCallback): void;
+/**
+ * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`.
+ * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+ */
+export declare function open(path: PathLike, callback: OpenCallback): void;
+/**
+ * Write `buffer` to the file specified by `fd`.
+ *
+ * `offset` determines the part of the buffer to be written, and `length` is
+ * an integer specifying the number of bytes to write.
+ *
+ * `position` refers to the offset from the beginning of the file where this data
+ * should be written. If `typeof position !== 'number'`, the data will be written
+ * at the current position. See [`pwrite(2)`](http://man7.org/linux/man-pages/man2/pwrite.2.html).
+ *
+ * The callback will be given three arguments `(err, bytesWritten, buffer)` where`bytesWritten` specifies how many _bytes_ were written from `buffer`.
+ *
+ * If this method is invoked as its `util.promisify()` ed version, it returns
+ * a promise for an `Object` with `bytesWritten` and `buffer` properties.
+ *
+ * It is unsafe to use `fs.write()` multiple times on the same file without waiting
+ * for the callback. For this scenario, {@link createWriteStream} is
+ * recommended.
+ *
+ * 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.
+ * @since v0.0.2
+ */
+export declare function write<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, offset: number | undefined | null, length: number | undefined | null, position: number | undefined | null, callback: WriteBufCallback): void;
+/**
+ * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ * @param offset The part of the buffer to be written. If not supplied, defaults to `0`.
+ * @param length The number of bytes to write. If not supplied, defaults to `buffer.length - offset`.
+ */
+export declare function write<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, offset: number | undefined | null, length: number | undefined | null, callback: WriteBufCallback): void;
+/**
+ * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ * @param offset The part of the buffer to be written. If not supplied, defaults to `0`.
+ */
+export declare function write<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, offset: number | undefined | null, callback: WriteBufCallback): void;
+/**
+ * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ */
+export declare function write<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, callback: WriteBufCallback): void;
+/**
+ * Asynchronously writes `string` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ * @param string A string to write.
+ * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
+ * @param encoding The expected string encoding.
+ */
+export declare function write(fd: number, string: string, position: number | undefined | null, encoding: BufferEncoding | undefined | null, callback: WriteStrCallback): void;
+/**
+ * Asynchronously writes `string` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ * @param string A string to write.
+ * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
+ */
+export declare function write(fd: number, string: string, position: number | undefined | null, callback: WriteStrCallback): void;
+/**
+ * Asynchronously writes `string` to the file referenced by the supplied file descriptor.
+ * @param fd A file descriptor.
+ * @param string A string to write.
+ */
+export declare function write(fd: number, string: string, callback: WriteStrCallback): void;
+/**
+ * Read data from the file specified by `fd`.
+ *
+ * The callback is given the three arguments, `(err, bytesRead, buffer)`.
+ *
+ * If the file is not modified concurrently, the end-of-file is reached when the
+ * number of bytes read is zero.
+ *
+ * If this method is invoked as its `util.promisify()` ed version, it returns
+ * a promise for an `Object` with `bytesRead` and `buffer` properties.
+ * @since v0.0.2
+ * @param buffer The buffer that the data will be written to.
+ * @param offset The position in `buffer` to write the data to.
+ * @param length The number of bytes to read.
+ * @param position Specifies where to begin reading from in the file. If `position` is `null` or `-1 `, data will be read from the current file position, and the file position will be updated. If
+ * `position` is an integer, the file position will be unchanged.
+ */
+export declare function read<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, offset: number, length: number, position: ReadPosition | null, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void): void;
+/**
+ * Similar to the above `fs.read` function, this version takes an optional `options` object.
+ * If not otherwise specified in an `options` object,
+ * `buffer` defaults to `Buffer.alloc(16384)`,
+ * `offset` defaults to `0`,
+ * `length` defaults to `buffer.byteLength`, `- offset` as of Node 17.6.0
+ * `position` defaults to `null`
+ * @since v12.17.0, 13.11.0
+ */
+export declare function read<TBuffer extends NodeJS.ArrayBufferView>(fd: number, options: ReadAsyncOptions<TBuffer>, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void): void;
+export declare function read(fd: number, callback: ReadCallback): void;
+/**
+ * Read data from the file specified by `fd`.
+ *
+ * The callback is given the three arguments, `(err, bytesRead, buffer)`.
+ *
+ * If the file is not modified concurrently, the end-of-file is reached when the
+ * number of bytes read is zero.
+ *
+ * If this method is invoked as its `util.promisify()` ed version, it returns
+ * a promise for an `Object` with `bytesRead` and `buffer` properties.
+ * @since v0.0.2
+ * @param buffer The buffer that the data will be written to.
+ * @param offset The position in `buffer` to write the data to.
+ * @param length The number of bytes to read.
+ * @param position Specifies where to begin reading from in the file. If `position` is `null` or `-1 `, data will be read from the current file position, and the file position will be updated. If
+ * `position` is an integer, the file position will be unchanged.
+ */
+export declare function read<TBuffer extends NodeJS.ArrayBufferView>(fd: number, buffer: TBuffer, offset: number, length: number, position: ReadPosition | null, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void): void;
+/**
+ * Similar to the above `fs.read` function, this version takes an optional `options` object.
+ * If not otherwise specified in an `options` object,
+ * `buffer` defaults to `Buffer.alloc(16384)`,
+ * `offset` defaults to `0`,
+ * `length` defaults to `buffer.byteLength`, `- offset` as of Node 17.6.0
+ * `position` defaults to `null`
+ * @since v12.17.0, 13.11.0
+ */
+export declare function read<TBuffer extends NodeJS.ArrayBufferView>(fd: number, options: ReadAsyncOptions<TBuffer>, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void): void;
+export declare function read(fd: number, callback: ReadCallback): void;
+/**
+ * Closes the file descriptor. No arguments other than a possible exception are
+ * given to the completion callback.
+ *
+ * Calling `fs.close()` on any file descriptor (`fd`) that is currently in use
+ * through any other `fs` operation may lead to undefined behavior.
+ *
+ * See the POSIX [`close(2)`](http://man7.org/linux/man-pages/man2/close.2.html) documentation for more detail.
+ * @since v0.0.2
+ */
+export declare function close(fd: number, callback?: NoParamCallback): void;
+/**
+ * Asynchronously removes files and directories (modeled on the standard POSIX `rm`utility). No arguments other than a possible exception are given to the
+ * completion callback.
+ * @since v14.14.0
+ */
+export declare function rm(path: PathLike, callback: NoParamCallback): void;
+export declare function rm(path: PathLike, options: RmOptions, callback: NoParamCallback): void;
+export declare function rename(oldPath: PathLike, newPath: PathLike, callback: NoParamCallback): void;
+export declare function copyFile(src: PathLike, dest: PathLike, callback: NoParamCallback): void;
+export declare function copyFile(src: PathLike, dest: PathLike, mode: number, callback: NoParamCallback): void;
+export declare function access(path: PathLike, callback: NoParamCallback): void;
+export declare function access(path: PathLike, mode: number, callback: NoParamCallback): void;
+export declare function appendFile(path: PathLike, data: string | Uint8Array, callback: NoParamCallback): void;
+export declare function appendFile(path: PathLike, data: string | Uint8Array, options: {
+    encoding?: string;
+    mode?: number;
+    flag?: string;
+} | string, callback: NoParamCallback): void;
+export declare function readlink(path: PathLike, callback: (err: NodeJS.ErrnoException | null, linkString: string) => void): void;
+export declare function readlink(path: PathLike, options: {
+    encoding?: string;
+} | string, callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void): void;
+export declare function truncate(path: PathLike, callback: NoParamCallback): void;
+export declare function truncate(path: PathLike, len: number, callback: NoParamCallback): void;
+export declare function chmod(path: PathLike, mode: Mode, callback: NoParamCallback): void;
+export declare function chown(path: PathLike, uid: number, gid: number, callback: NoParamCallback): void;
+export declare function mkdir(path: PathLike, callback: NoParamCallback): void;
+export declare function mkdir(path: PathLike, options: MakeDirectoryOptions | Mode, callback: NoParamCallback): void;
+export declare function rmdir(path: PathLike, callback: NoParamCallback): void;
+export declare function rmdir(path: PathLike, options: RmDirOptions, callback: NoParamCallback): void;
+export declare function readFile(path: PathLike, callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void): void;
+export declare function readFile(path: PathLike, options: {
+    encoding?: string;
+    flag?: string;
+} | string, callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void): void;
+export declare function writeFile(path: PathLike, data: string | Uint8Array, callback: NoParamCallback): void;
+export declare function writeFile(path: PathLike, data: string | Uint8Array, options: {
+    encoding?: string;
+    mode?: number;
+    flag?: string;
+} | string, callback: NoParamCallback): void;
+export declare function link(existingPath: PathLike, newPath: PathLike, callback: NoParamCallback): void;
+export declare function unlink(path: PathLike, callback: NoParamCallback): void;
+export {};

package/lib/types/dirent.d.ts

@@ -0,0 +1,77 @@
+import Gio from '@girs/gio-2.0';
+import type { Dirent as OriginalDirent } from 'node:fs';
+/**
+ * A representation of a directory entry, which can be a file or a subdirectory
+ * within the directory, as returned by reading from an `fs.Dir`. The
+ * directory entry is a combination of the file name and file type pairs.
+ *
+ * Additionally, when {@link readdir} or {@link readdirSync} is called with
+ * the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings or `Buffer` s.
+ * @since v10.10.0
+ */
+export declare class Dirent implements OriginalDirent {
+    /**
+     * The file name that this `fs.Dirent` object refers to. The type of this
+     * value is determined by the `options.encoding` passed to {@link readdir} or {@link readdirSync}.
+     * @since v10.10.0
+     */
+    name: string;
+    /**
+     * The path to the parent directory of the file this `fs.Dirent` object refers to.
+     * @since v20.12.0, v18.20.0
+     */
+    parentPath: string;
+    private _isFile;
+    private _isDirectory;
+    private _isBlockDevice;
+    private _isCharacterDevice;
+    private _isSymbolicLink;
+    private _isFIFO;
+    private _isSocket;
+    /** This is not part of node.fs and is used internal by gjsify */
+    protected _file: Gio.File;
+    /** This is not part of node.fs and is used internal by gjsify */
+    constructor(path: string, filename?: string, fileType?: Gio.FileType);
+    /**
+     * Classify a SPECIAL file type using the unix::mode attribute from Gio.FileInfo.
+     * Falls back to marking nothing if the mode attribute is unavailable.
+     */
+    private _classifySpecialFile;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a regular file.
+     * @since v10.10.0
+     */
+    isFile(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a file system
+     * directory.
+     * @since v10.10.0
+     */
+    isDirectory(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a block device.
+     * @since v10.10.0
+     */
+    isBlockDevice(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a character device.
+     * @since v10.10.0
+     */
+    isCharacterDevice(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a symbolic link.
+     * @since v10.10.0
+     */
+    isSymbolicLink(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a first-in-first-out
+     * (FIFO) pipe.
+     * @since v10.10.0
+     */
+    isFIFO(): boolean;
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a socket.
+     * @since v10.10.0
+     */
+    isSocket(): boolean;
+}

package/lib/types/encoding.d.ts

@@ -0,0 +1,6 @@
+import { Buffer } from 'node:buffer';
+import type { ReadOptions } from './types/index.js';
+import type { ObjectEncodingOptions, BufferEncodingOption } from 'node:fs';
+export declare function getEncodingFromOptions(options?: ReadOptions | ObjectEncodingOptions | BufferEncodingOption, defaultEncoding?: null | BufferEncoding | "buffer"): BufferEncoding | 'buffer';
+export declare function encodeUint8Array(encoding: BufferEncoding | 'buffer', data: Uint8Array): string | Buffer<ArrayBuffer>;
+export declare function decode(str: string, encoding?: string): string;

package/lib/types/errors.d.ts

@@ -0,0 +1,7 @@
+import type { PathLike } from 'node:fs';
+import { isNotFoundError } from '@gjsify/utils';
+export { isNotFoundError };
+/**
+ * Create a Node.js-style ErrnoException from a Gio error, with fs-specific path/dest fields.
+ */
+export declare function createNodeError(err: any, syscall: string, path: PathLike, dest?: PathLike): NodeJS.ErrnoException;