@gjsify/fs 0.0.1 → 0.0.2

package/src/callback.ts

@@ -0,0 +1,362 @@
+import { open as openP, rm as rmP } from './promises.js'
+import { warnNotImplemented } from '@gjsify/utils';
+import { PathLike, OpenMode, Mode, ReadPosition, ReadAsyncOptions, NoParamCallback, RmOptions } from 'fs';
+import { FileHandle } from './file-handle.js';
+import { Buffer } from 'buffer';
+
+export { realpath } from '@gjsify/deno_std/node/_fs/_fs_realpath';
+export { readdir } from '@gjsify/deno_std/node/_fs/_fs_readdir';
+export { symlink } from '@gjsify/deno_std/node/_fs/_fs_symlink';
+export { lstat } from '@gjsify/deno_std/node/_fs/_fs_lstat';
+export { stat } from '@gjsify/deno_std/node/_fs/_fs_stat';
+
+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 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 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 function open(path: PathLike, callback: OpenCallback): void;
+
+export function open(path: PathLike, ...args: any[]): void {
+    let flags: number | OpenMode | undefined;
+    let mode: Mode | undefined | null;
+    let callback: OpenCallback
+
+    switch (args.length) {
+        case 1:
+            callback = args[0]
+            break;
+        case 2:
+            flags = args[0]
+            callback = args[1]
+            break;
+        case 3:
+            flags = args[0]
+            mode = args[1]
+            callback = args[2]
+            break;
+        default:
+            break;
+    }
+
+    openP(path, flags as any, mode)
+    .then((fileHandle) => {
+        callback(null, fileHandle.fd);
+    })
+    .catch((err) => {
+        callback(err, -1);
+    })
+}
+
+/**
+ * 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 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 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 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 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 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 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 function write(fd: number, string: string, callback: WriteStrCallback): void;
+
+export function write<TBuffer extends NodeJS.ArrayBufferView>(fd: number, data: string | TBuffer, ...args: any[]): void {
+
+    const fileHandle = FileHandle.getInstance(fd);
+    
+    if (typeof data === 'string') {
+        const callback: WriteStrCallback = args[args.length -1];
+
+        fileHandle.write(data, ...args.pop())
+        .then((res) => {
+            callback(null, res.bytesWritten, res.buffer);
+        })
+        .catch((err) => {
+            callback(err, 0, '');
+        });
+
+        return;
+    }
+
+    const callback: WriteBufCallback = args[args.length -1];
+    const offset: number | undefined = args[0];
+    const length: number | undefined = args[1];
+    const position: number | undefined = args[2];
+
+    fileHandle.write(data, offset, length, position)
+    .then((res) => {
+        callback(null, res.bytesWritten, res.buffer);
+    })
+    .catch((err) => {
+        callback(err, 0, Buffer.from([]));
+    });
+}
+
+/**
+ * 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 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 function read<TBuffer extends NodeJS.ArrayBufferView>(
+    fd: number,
+    options: ReadAsyncOptions<TBuffer>,
+    callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void
+): void;
+export 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 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 function read<TBuffer extends NodeJS.ArrayBufferView>(
+    fd: number,
+    options: ReadAsyncOptions<TBuffer>,
+    callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void
+): void;
+export function read(fd: number, callback: ReadCallback): void;
+
+export function read(fd: number, ...args: any[]): void {
+
+    const fileHandle = FileHandle.getInstance(fd);
+
+    const callback: ReadCallback = args[args.length -1];
+    const err = new Error(warnNotImplemented('fs.read'));
+    callback(err, 0, Buffer.from(''));
+
+    let buffer: NodeJS.ArrayBufferView | undefined;
+    let offset: number | null | undefined;
+    let length: number | null | undefined;
+    let position: ReadPosition | null | undefined;
+
+    if (typeof args[0] === 'object') {
+        const options: ReadAsyncOptions<any> = args[0];
+        buffer = options.buffer;
+        offset = options.offset;
+        length = options.length;
+        position = options.position;
+    } else {
+        buffer = args[0];
+        offset = args[1];
+        length = args[2];
+        position = args[3];
+    }
+
+
+    fileHandle.read(buffer, offset, length, position)
+    .then((res) => {
+        callback(null, res.bytesRead, res.buffer);
+    })
+    .catch((err) => {
+        callback(err, 0, Buffer.from([]));
+    });
+}
+
+/**
+ * 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 function close(fd: number, callback?: NoParamCallback): void {
+    FileHandle.getInstance(fd).close()
+    .then(() => {
+        callback(null);
+    })
+    .catch((err) => callback(err))
+}
+
+/**
+ * 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 function rm(path: PathLike, callback: NoParamCallback): void;
+export function rm(path: PathLike, options: RmOptions, callback: NoParamCallback): void;
+
+export function rm(path: PathLike, ...args: any[]): void {
+
+    let options: RmOptions = {};
+    let callback: NoParamCallback = args[args.length -1];
+
+    if (args.length >= 2) {
+        options = args[0];
+    }
+
+    rmP(path, options)
+    .then(() => {
+        callback(null);
+    })
+    .catch((err) => {
+        callback(err);
+    });
+}

package/src/dirent.ts

@@ -0,0 +1,117 @@
+import Gio from '@girs/gio-2.0';
+import { basename } from 'path';
+
+import type { Dirent as OriginalDirent } from 'fs'; // Types from @types/node
+
+/**
+ * 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 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;
+
+    private _isFile = false;
+    private _isDirectory = false;
+    private _isBlockDevice = false;
+    private _isCharacterDevice = false;
+    private _isSymbolicLink = false;
+    private _isFIFO = false;
+    private _isSocket = false;
+
+    /** 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) {
+        if (!filename) filename = basename(path);
+        this.name = filename;
+        this._file = Gio.File.new_for_path(path);
+        const type = this._file.query_file_type(Gio.FileQueryInfoFlags.NONE, null);
+
+        switch (type) {
+            case Gio.FileType.DIRECTORY:
+                this._isDirectory = true;
+                break;
+            case Gio.FileType.MOUNTABLE:
+                break;
+            case Gio.FileType.REGULAR:
+                this._isFile = true;
+                break;
+            case Gio.FileType.SYMBOLIC_LINK:
+            case Gio.FileType.SHORTCUT:
+                this._isSymbolicLink = true; // ?
+                break;
+            case Gio.FileType.SPECIAL:
+                // File is a "special" file, such as a socket, fifo, block device, or character device.
+                this._isBlockDevice = Gio.unix_is_system_device_path(path);
+                // TODO: this._isCharacterDevice = 
+                // TODO: this._isSocket = 
+                // TODO: this._isFifo = 
+                break;
+        }
+
+    }
+
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a regular file.
+     * @since v10.10.0
+     */
+    isFile(): boolean {
+        return this._isFile;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a file system
+     * directory.
+     * @since v10.10.0
+     */
+    isDirectory(): boolean {
+        return this._isDirectory;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a block device.
+     * @since v10.10.0
+     */
+    isBlockDevice(): boolean {
+        return this._isBlockDevice;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a character device.
+     * @since v10.10.0
+     */
+    isCharacterDevice(): boolean {
+        return this._isCharacterDevice;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a symbolic link.
+     * @since v10.10.0
+     */
+    isSymbolicLink(): boolean {
+        return this._isSymbolicLink;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a first-in-first-out
+     * (FIFO) pipe.
+     * @since v10.10.0
+     */
+    isFIFO(): boolean {
+        return this._isFIFO;
+    }
+    /**
+     * Returns `true` if the `fs.Dirent` object describes a socket.
+     * @since v10.10.0
+     */
+    isSocket(): boolean {
+        return this._isSocket;
+    }
+}

package/src/encoding.ts

@@ -0,0 +1,40 @@
+import { Buffer } from 'buffer';
+
+import type { ReadOptions } from './types/index.js';
+import type { ObjectEncodingOptions, BufferEncodingOption } from 'fs'; // Types from @types/node
+
+export function getEncodingFromOptions(options: ReadOptions | ObjectEncodingOptions | BufferEncodingOption= { encoding: null, flag: 'r' }, defaultEncoding: null | BufferEncoding | "buffer" = 'utf8'): BufferEncoding | 'buffer' {
+  if (options === null) {
+    return defaultEncoding;
+  }
+
+  if (typeof options === 'string') {
+    return options as BufferEncoding | 'buffer';
+  }
+
+  if (typeof options === 'object' && typeof options.encoding === 'string') {
+    return options.encoding;
+  }
+
+  return defaultEncoding;
+}
+
+export function encodeUint8Array(encoding: BufferEncoding | 'buffer', data: Uint8Array) {
+  if (encoding === 'buffer') {
+    return Buffer.from(data);
+  }
+
+  const decoder = new TextDecoder(encoding);
+  return decoder.decode(data);
+  // return byteArray.toString(data);
+}
+
+// Credits https://github.com/denoland/deno_std/blob/63be40277264e71af60f9b118a2cb569e02beeab/node/_fs/_fs_mkdtemp.ts#L82
+export function decode(str: string, encoding?: string): string {
+  if (!encoding) return str;
+  else {
+    const decoder = new TextDecoder(encoding);
+    const encoder = new TextEncoder();
+    return decoder.decode(encoder.encode(str));
+  }
+}

package/src/file-handle.spec.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from '@gjsify/unit';
+import { promises } from 'fs';
+import { Buffer } from 'buffer';
+
+export default async () => {
+	await describe('FileHandle', async () => {
+		await it(`should open a file for writing`, async () => {
+			const path = './test/openP.txt';
+			const fileHandle = await promises.open(path, 'w+', 0o666);
+
+			console.log('FileHandle: file open');
+
+			let buffWrite = Buffer.from('Hello World', 'utf8'),
+			buffStart = 0,
+			buffLength = buffWrite.length,
+			filePos = 0;
+			const res = await fileHandle.write(buffWrite, buffStart, buffLength, filePos);
+			console.log('FileHandle: file written');
+
+			// console.log('written', res.bytesWritten);
+
+			expect(res.bytesWritten).toBe(buffWrite.length);
+
+			expect(res.buffer).toBe(buffWrite);
+
+			await fileHandle.close();
+			console.log('FileHandle: file closed');
+
+			await promises.rm(path);
+			console.log('FileHandle: file removed');	
+
+		});
+	});
+}