visaljs 0.0.6 → 0.0.8

package/node/prelude/internal/fs_dir.js

@@ -0,0 +1,166 @@
+// fs.Dir, opendir and opendirSync: a directory's entries as Dirents, one read at a time (and, with
+// recursive, its subdirectories' after them, as Node's). Linked into programs that name them
+// (internal/features.js).
+import { fsReaddir } from "visaljs:host";
+import { Dir as DirWrapper, Dirent } from "../fs.js";
+import { codeError, systemError, validateFunction } from "./errors.js";
+import { features, provideClass } from "./features.js";
+import { getOptions, getValidatedPath } from "./fs_utils.js";
+import { codes } from "./streams/errors.js";
+import { validateUint32 } from "./streams/validators.js";
+
+const closed = () => codeError(Error, "ERR_DIR_CLOSED", "Directory handle was closed");
+
+/* a directory's entries now: [name, type, …] as Dirents of that directory */
+function entriesOf(path) {
+  const r = fsReaddir(path);
+  if (typeof r === "number") {
+    const e = systemError(r, "opendir");  /* Node's message names the call, not the path */
+    e.path = path;
+    throw e;
+  }
+  const entries = [];
+  for (let i = 0; i < r.length; i += 2) entries.push(new Dirent(r[i], r[i + 1], path));
+  return entries;
+}
+
+class Dir {
+  #path;
+  #entries;
+  #queue = [];      /* subdirectories to read next (recursive) */
+  #recursive;
+  #closed = false;
+  #busy = false;
+
+  constructor(path, entries, options) {
+    /* Node's takes the directory's handle first: a program can't make one */
+    if (path == null) throw codeError(TypeError, "ERR_MISSING_ARGS", 'The "handle" argument must be specified');
+    this.#path = path;
+    this.#entries = entries;
+    this.#recursive = Boolean(options?.recursive);
+    validateUint32({ bufferSize: 32, ...options }.bufferSize, "options.bufferSize", true);  /* as Node's: a given null too */
+  }
+
+  get path() {
+    if (!(#path in this)) throw new codes.ERR_INVALID_THIS("Dir");
+    return this.#path;
+  }
+
+  /** The next entry, or null at the end. */
+  readSync() {
+    if (this.#closed) throw closed();
+    if (this.#busy) throw codeError(Error, "ERR_DIR_CONCURRENT_OPERATION", "Cannot do synchronous work on directory handle with concurrent asynchronous operations");
+    return this.#next();
+  }
+
+  #next() {
+    for (;;) {
+      const dirent = this.#entries.shift();
+      if (dirent !== undefined) {
+        /* links aren't followed, as Node's */
+        if (this.#recursive && dirent.isDirectory()) this.#queue.push(`${dirent.parentPath}/${dirent.name}`);
+        return dirent;
+      }
+      if (this.#queue.length === 0) return null;
+      this.#entries = entriesOf(this.#queue.shift());
+    }
+  }
+
+  /** read([callback]): the next entry, or null, as a promise or to the callback. */
+  read(callback) {
+    if (callback !== undefined) {
+      validateFunction(callback, "callback");
+      return this.#later(() => this.#next(), callback);
+    }
+    return this.#promise(() => this.#next());
+  }
+
+  closeSync() {
+    if (this.#closed) throw closed();
+    if (this.#busy) throw codeError(Error, "ERR_DIR_CONCURRENT_OPERATION", "Cannot do synchronous work on directory handle with concurrent asynchronous operations");
+    this.#closed = true;
+    this.#entries = [];
+    this.#queue = [];
+  }
+
+  close(callback) {
+    if (callback !== undefined) {
+      validateFunction(callback, "callback");
+      return this.#later(() => this.closeSync(), callback);
+    }
+    return this.#promise(() => this.closeSync());
+  }
+
+  /* an operation on a later tick, as Node's on the thread pool: the handle is busy until then */
+  #later(fn, callback) {
+    if (this.#closed) {
+      process.nextTick(callback, closed());
+      return;
+    }
+    this.#busy = true;
+    process.nextTick(() => {
+      this.#busy = false;
+      let result, error = null;
+      try {
+        result = fn();
+      } catch (e) {
+        error = e;
+      }
+      if (error) callback(error);
+      else callback(null, result);
+    });
+  }
+
+  #promise(fn) {
+    return new Promise((resolve, reject) => this.#later(fn, (err, result) => (err ? reject(err) : resolve(result))));
+  }
+
+  /** The entries, then the directory closed. */
+  async *entries() {
+    try {
+      for (;;) {
+        const dirent = await this.read();
+        if (dirent === null) break;
+        yield dirent;
+      }
+    } finally {
+      if (!this.#closed) this.closeSync();
+    }
+  }
+
+  [Symbol.asyncIterator]() {
+    return this.entries();
+  }
+
+  [Symbol.dispose ?? Symbol.for("nodejs.dispose")]() {
+    if (!this.#closed) this.closeSync();
+  }
+
+  async [Symbol.asyncDispose ?? Symbol.for("nodejs.asyncDispose")]() {
+    if (!this.#closed) this.closeSync();
+  }
+}
+
+function opendirSync(path, options) {
+  path = getValidatedPath(path);
+  options = getOptions(options, { encoding: "utf8" });
+  return new Dir(path, entriesOf(path), options);
+}
+
+/* the arguments checked now, as Node's; the directory opened, then the Dir made, on a later tick */
+function opendir(path, options, callback) {
+  callback = typeof options === "function" ? options : callback;
+  validateFunction(callback, "callback");
+  path = getValidatedPath(path);
+  options = getOptions(options, { encoding: "utf8" });
+  let entries, error = null;
+  try {
+    entries = entriesOf(path);
+  } catch (e) {
+    error = e;
+  }
+  process.nextTick(() => (error ? callback(error) : callback(null, new Dir(path, entries, options))));
+}
+
+Object.assign(features, { opendirSync, opendir, opendirPromise: async (path, options) => opendirSync(path, options) });
+provideClass(DirWrapper, Dir);

package/node/prelude/internal/fs_filehandle.js

@@ -0,0 +1,287 @@
+// fs/promises' open and FileHandle, as Node's: an fd's calls as promises (read, write, readv,
+// writev, readFile, writeFile, appendFile, stat, truncate, sync, datasync, utimes, chmod, chown),
+// read streams, write streams and readLines on it, close and Symbol.asyncDispose, and its 'close'
+// event. The I/O happens when the method is called, as node:fs/promises' other calls. Linked into
+// programs that name them (internal/features.js).
+import { EventEmitter } from "../events.js";
+import {
+  closeSync, createReadStream, createWriteStream, fchmodSync, fchownSync, fdatasyncSync, fstatSync, fsyncSync, ftruncateSync, futimesSync,
+  openSync, readSync, readvSync, writeSync, writevSync,
+} from "../fs.js";
+import { createInterface } from "../readline.js";
+import { notSupported } from "./errors.js";
+import { features } from "./features.js";
+import {
+  getOptions, kIoMaxLength, validateBufferArray, validateOffsetLengthRead, validateOffsetLengthWrite, validatePosition,
+  validateStringAfterArrayBufferView,
+} from "./fs_utils.js";
+import "./fs_streams.js";  /* its streams */
+import { AbortError, codes } from "./streams/errors.js";
+import { kEmptyObject, validateAbortSignal, validateBuffer, validateInteger, validateObject } from "./streams/validators.js";
+
+const { ERR_FS_FILE_TOO_LARGE, ERR_INVALID_ARG_VALUE } = codes;
+const kReadChunk = 512 * 1024;
+const kWriteFileMaxChunkSize = 512 * 1024;
+
+function checkAborted(signal) {
+  if (signal?.aborted) throw new AbortError(undefined, { cause: signal.reason });
+}
+
+/* an iterable, or async iterable, of chunks: not a string or bytes */
+const isCustomIterable = (obj) =>
+  obj != null && typeof obj !== "string" && !ArrayBuffer.isView(obj) &&
+  (typeof obj[Symbol.asyncIterator] === "function" || typeof obj[Symbol.iterator] === "function");
+
+/* Node's validateEncoding: hex takes whole bytes */
+function validateEncoding(data, encoding) {
+  if (typeof encoding === "string" && encoding.toLowerCase() === "hex" && data.length % 2 !== 0) {
+    throw new ERR_INVALID_ARG_VALUE("encoding", encoding, `is invalid for data of length ${data.length}`);
+  }
+}
+
+/* EBADF for a handle that's closed, as Node's */
+function closedError(syscall) {
+  const e = new Error("file closed");
+  e.errno = -9;
+  e.code = "EBADF";
+  e.syscall = syscall;
+  return e;
+}
+
+export class FileHandle extends EventEmitter {
+  #fd;
+  #closing = null;
+
+  constructor(fd) {
+    super();
+    this.#fd = fd;
+  }
+
+  get fd() {
+    return this.#fd;
+  }
+
+  /* the call on the fd as a promise; EBADF once the handle is closed */
+  #call(syscall, fn) {
+    return new Promise((resolve, reject) => {
+      if (this.#fd < 0) return reject(closedError(syscall));
+      try {
+        resolve(fn(this.#fd));
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+
+  /** read(buffer, offset, length, position), read(buffer, options) or read(options): { bytesRead,
+   *  buffer }. Node's argument handling (lib/internal/fs/promises.js). */
+  read(bufferOrParams, offset, length, position) {
+    return this.#call("read", (fd) => {
+      let buffer = bufferOrParams;
+      if (!ArrayBuffer.isView(buffer)) {
+        if (bufferOrParams !== undefined && bufferOrParams !== null) validateObject(bufferOrParams, "options");
+        ({ buffer = Buffer.alloc(16384), offset = 0, length = buffer.byteLength - offset, position = null } = bufferOrParams ?? kEmptyObject);
+        validateBuffer(buffer);
+      }
+      if (offset !== null && typeof offset === "object") {
+        ({ offset = 0, length = buffer.byteLength - offset, position = null } = offset);
+      }
+      if (offset == null) offset = 0;
+      else validateInteger(offset, "offset", 0);
+      length ??= buffer.byteLength - offset;
+      if (position == null) position = -1;
+      else validatePosition(position, "position", length);
+      if (length === 0) return { __proto__: null, bytesRead: length, buffer };
+      if (buffer.byteLength === 0) throw new ERR_INVALID_ARG_VALUE("buffer", buffer, "is empty and cannot be written");
+      validateOffsetLengthRead(offset, length, buffer.byteLength);
+      return { __proto__: null, bytesRead: readSync(fd, buffer, offset, length, position) || 0, buffer };
+    });
+  }
+
+  /** write(buffer[, offset[, length[, position]]]), write(buffer, options) or write(string[, position[,
+   *  encoding]]): { bytesWritten, buffer }. */
+  write(buffer, offsetOrOptions, length, position) {
+    return this.#call("write", (fd) => {
+      if (buffer?.byteLength === 0) return { __proto__: null, bytesWritten: 0, buffer };
+      let offset = offsetOrOptions;
+      if (ArrayBuffer.isView(buffer)) {
+        if (typeof offset === "object") {
+          ({ offset = 0, length = buffer.byteLength - offset, position = null } = offsetOrOptions ?? kEmptyObject);
+        }
+        if (offset == null) offset = 0;
+        else validateInteger(offset, "offset", 0);
+        if (typeof length !== "number") length = buffer.byteLength - offset;
+        if (typeof position !== "number") position = null;
+        validateOffsetLengthWrite(offset, length, buffer.byteLength);
+        return { __proto__: null, bytesWritten: writeSync(fd, buffer, offset, length, position) || 0, buffer };
+      }
+      validateStringAfterArrayBufferView(buffer, "buffer");
+      validateEncoding(buffer, length);
+      return { __proto__: null, bytesWritten: writeSync(fd, buffer, offset, length) || 0, buffer };
+    });
+  }
+
+  readv(buffers, position) {
+    return this.#call("read", (fd) => {
+      validateBufferArray(buffers);
+      return { __proto__: null, bytesRead: readvSync(fd, buffers, typeof position === "number" ? position : null), buffers };
+    });
+  }
+
+  writev(buffers, position) {
+    return this.#call("write", (fd) => {
+      validateBufferArray(buffers);
+      if (buffers.length === 0) return { __proto__: null, bytesWritten: 0, buffers };
+      return { __proto__: null, bytesWritten: writevSync(fd, buffers, typeof position === "number" ? position : null), buffers };
+    });
+  }
+
+  /** The rest of the file from its current position: a Buffer, or a string with an encoding. An
+   *  abort signal is checked before and between reads, as Node's. */
+  readFile(options) {
+    return this.#call("read", async (fd) => {
+      options = getOptions(options, { flag: "r" });
+      const { signal, encoding } = options;
+      validateAbortSignal(signal, "options.signal");
+      checkAborted(signal);
+      const st = fstatSync(fd);
+      if (st.isFile() && st.size > kIoMaxLength) throw new ERR_FS_FILE_TOO_LARGE(st.size);
+      const chunks = [];
+      let total = 0;
+      for (;;) {
+        await undefined;  /* a turn for an abort, as Node's reads on its thread pool */
+        checkAborted(signal);
+        const chunk = Buffer.allocUnsafe(kReadChunk);
+        const n = readSync(fd, chunk, 0, kReadChunk, null);
+        if (n === 0) break;
+        chunks.push(n === kReadChunk ? chunk : chunk.subarray(0, n));
+        total += n;
+      }
+      const all = Buffer.concat(chunks, total);
+      return encoding && encoding !== "buffer" ? all.toString(encoding) : all;
+    });
+  }
+
+  /** The data written from the current position: a string, bytes, or an iterable or stream of them,
+   *  in chunks, an abort signal checked between them (Node's writeFileHandle). */
+  writeFile(data, options) {
+    return this.#call("write", async () => {
+      options = getOptions(options, { encoding: "utf8", mode: 0o666, flag: "w", flush: false });
+      if (!ArrayBuffer.isView(data) && !isCustomIterable(data)) {
+        validateStringAfterArrayBufferView(data, "data");
+        data = Buffer.from(data, options.encoding || "utf8");
+      }
+      const { signal, encoding } = options;
+      validateAbortSignal(signal, "options.signal");
+      checkAborted(signal);
+      if (isCustomIterable(data)) {
+        for await (const buf of data) {
+          checkAborted(signal);
+          const toWrite = ArrayBuffer.isView(buf) ? buf : Buffer.from(buf, encoding || "utf8");
+          let remaining = toWrite.byteLength;
+          while (remaining > 0) {
+            const writeSize = Math.min(kWriteFileMaxChunkSize, remaining);
+            const { bytesWritten } = await this.write(toWrite, toWrite.byteLength - remaining, writeSize);
+            remaining -= bytesWritten;
+            checkAborted(signal);
+          }
+        }
+        return;
+      }
+      data = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      let remaining = data.byteLength;
+      if (remaining === 0) return;
+      do {
+        checkAborted(signal);
+        const { bytesWritten } = await this.write(data, 0, Math.min(kWriteFileMaxChunkSize, data.byteLength));
+        remaining -= bytesWritten;
+        data = new Uint8Array(data.buffer, data.byteOffset + bytesWritten, data.byteLength - bytesWritten);
+      } while (remaining > 0);
+    });
+  }
+
+  appendFile(data, options) {
+    return this.writeFile(data, options);
+  }
+
+  stat(options) {
+    return this.#call("fstat", (fd) => fstatSync(fd, options ?? { bigint: false }));
+  }
+
+  truncate(len = 0) {
+    return this.#call("ftruncate", (fd) => void ftruncateSync(fd, len));
+  }
+
+  sync() {
+    return this.#call("fsync", (fd) => void fsyncSync(fd));
+  }
+
+  datasync() {
+    return this.#call("fdatasync", (fd) => void fdatasyncSync(fd));
+  }
+
+  utimes(atime, mtime) {
+    return this.#call("futime", (fd) => void futimesSync(fd, atime, mtime));
+  }
+
+  chmod(mode) {
+    return this.#call("fchmod", (fd) => void fchmodSync(fd, mode));
+  }
+
+  chown(uid, gid) {
+    return this.#call("fchown", (fd) => void fchownSync(fd, uid, gid));
+  }
+
+  /* streams on the handle, as Node's: they read and write through it, and close it */
+  createReadStream(options = undefined) {
+    return createReadStream(undefined, { ...options, fd: this });
+  }
+
+  createWriteStream(options = undefined) {
+    return createWriteStream(undefined, { ...options, fd: this });
+  }
+
+  /** The lines: node:readline's interface on a read stream. */
+  readLines(options) {
+    return createInterface({ input: this.createReadStream(options), crlfDelay: Infinity });
+  }
+
+  readableWebStream() {
+    throw notSupported("FileHandle.readableWebStream");
+  }
+
+  /** Closes the fd, once: 'close' follows. */
+  close() {
+    if (this.#closing) return this.#closing;
+    if (this.#fd < 0) return Promise.resolve();
+    const fd = this.#fd;
+    this.#closing = new Promise((resolve, reject) => {
+      try {
+        closeSync(fd);
+        this.#fd = -1;
+        this.emit("close");
+        resolve();
+      } catch (e) {
+        reject(e);
+      }
+    });
+    return this.#closing;
+  }
+
+  [Symbol.asyncDispose ?? Symbol.for("nodejs.asyncDispose")]() {
+    return this.close();
+  }
+}
+
+/** fs/promises' open(path[, flags[, mode]]): a FileHandle. */
+function promisesOpen(path, flags = "r", mode = 0o666) {
+  return new Promise((resolve, reject) => {
+    try {
+      resolve(new FileHandle(openSync(path, flags, mode)));
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+
+Object.assign(features, { promisesOpen, FileHandle });