visaljs 0.0.10 → 0.0.11

package/node/prelude/internal/events_on.js

@@ -1,9 +1,17 @@
-// events.on: an emitter's or EventTarget's events as an async iterator. Linked into programs that
-// name it (internal/features.js).
-import { invalidArgType } from "./errors.js";
+// events.on (Node's lib/events.js): an emitter's or EventTarget's events as an async iterator,
+// buffered until read, the emitter paused above highWaterMark and resumed below lowWaterMark.
+// Linked into programs that name it (internal/features.js), and with node:readline's iterator.
+// Ported from Node.js (Copyright Node.js contributors, MIT): node/third_party/nodejs/LICENSE.
+import { invalidArgType, outOfRange } from "./errors.js";
 import { features } from "./features.js";
 
-const isEventTarget = (target) => typeof target?.addEventListener === "function" && typeof target?.on !== "function";
+/* the iterator's watermarks and state (events.on's [kWatermarkData]) */
+const kWatermarkData = Symbol.for("nodejs.watermarkData");
+/** Node's internal option: each event's first argument, not an array of them (readline's lines).
+ *  In the registry: readline's iterator names it without linking this module. */
+export const kFirstEventParam = Symbol.for("visaljs.events.kFirstEventParam");
+
+const AsyncIteratorPrototype = Object.getPrototypeOf(Object.getPrototypeOf(async function* () {}).prototype);
 
 function validateSignal(signal, name) {
   if (signal !== undefined && (signal === null || typeof signal !== "object" || !("aborted" in signal))) {
@@ -11,6 +19,12 @@ function validateSignal(signal, name) {
   }
 }
 
+function validateWatermark(value, name) {
+  if (typeof value !== "number") throw invalidArgType(name, "of type number", value);
+  if (!Number.isInteger(value)) throw outOfRange(name, "an integer", value);
+  if (value < 1 || value > Number.MAX_SAFE_INTEGER) throw outOfRange(name, `>= 1 && <= ${Number.MAX_SAFE_INTEGER}`, value);
+}
+
 /* Node's AbortError: name and code, the signal's reason as its cause */
 function abortError(signal) {
   const error = new Error("The operation was aborted", { cause: signal?.reason });
@@ -19,29 +33,48 @@ function abortError(signal) {
   return error;
 }
 
-/** events.on(emitter, name[, { signal, close }]): the events as an async iterator of their
- *  arguments, buffered until read; an 'error' ends it by throwing, a `close` event by finishing. */
-function on(emitter, event, options = {}) {
-  const signal = options?.signal;
+function addListener(emitter, name, listener) {
+  if (typeof emitter.on === "function") emitter.on(name, listener);
+  else if (typeof emitter.addEventListener === "function") emitter.addEventListener(name, listener);
+  else throw invalidArgType("emitter", "an instance of EventEmitter", emitter);
+}
+
+function removeListener(emitter, name, listener) {
+  if (typeof emitter.removeListener === "function") emitter.removeListener(name, listener);
+  else if (typeof emitter.removeEventListener === "function") emitter.removeEventListener(name, listener);
+  else throw invalidArgType("emitter", "an instance of EventEmitter", emitter);
+}
+
+const iterResult = (value, done) => ({ value, done });
+
+/** events.on(emitter, name[, { signal, close, highWaterMark, lowWaterMark }]) */
+export function on(emitter, event, options = {}) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) throw invalidArgType("options", "of type object", options);
+  const signal = options.signal;
   validateSignal(signal, "options.signal");
   if (signal?.aborted) throw abortError(signal);
-  const close = options?.close ?? [];
+  const highWatermark = options.highWaterMark ?? options.highWatermark ?? Number.MAX_SAFE_INTEGER;
+  validateWatermark(highWatermark, "options.highWaterMark");
+  const lowWatermark = options.lowWaterMark ?? options.lowWatermark ?? 1;
+  validateWatermark(lowWatermark, "options.lowWaterMark");
+
   const unconsumedEvents = [];
   const unconsumedPromises = [];
+  let paused = false;
   let error = null;
   let finished = false;
   const listening = [];
-  const listen = (name, handler) => {
-    if (isEventTarget(emitter)) emitter.addEventListener(name, handler);
-    else emitter.on(name, handler);
-    listening.push([name, handler]);
-  };
-  const result = (value, done) => ({ value, done });
 
-  const iterator = {
+  const iterator = Object.setPrototypeOf({
     next() {
-      const value = unconsumedEvents.shift();
-      if (value) return Promise.resolve(result(value, false));
+      if (unconsumedEvents.length) {
+        const value = unconsumedEvents.shift();
+        if (paused && unconsumedEvents.length < lowWatermark) {
+          emitter.resume();
+          paused = false;
+        }
+        return Promise.resolve(iterResult(value, false));
+      }
       if (error) {
         const p = Promise.reject(error);
         error = null;
@@ -54,45 +87,57 @@ function on(emitter, event, options = {}) {
       return closeHandler();
     },
     throw(err) {
-      if (!(err instanceof Error)) throw invalidArgType("EventEmitter.AsyncIterator", "an instance of Error", err);
+      if (!err || !(err instanceof Error)) throw invalidArgType("EventEmitter.AsyncIterator", "an instance of Error", err);
       errorHandler(err);
     },
     [Symbol.asyncIterator]() {
       return this;
     },
+    [kWatermarkData]: {
+      get size() { return unconsumedEvents.length; },
+      get low() { return lowWatermark; },
+      get high() { return highWatermark; },
+      get isPaused() { return paused; },
+    },
+  }, AsyncIteratorPrototype);
+
+  const listen = (name, handler) => {
+    addListener(emitter, name, handler);
+    listening.push([name, handler]);
   };
 
-  function eventHandler(...args) {
-    const pending = unconsumedPromises.shift();
-    if (pending) pending.resolve(result(args, false));
-    else unconsumedEvents.push(args);
+  function eventHandler(value) {
+    if (unconsumedPromises.length === 0) {
+      if (!paused && unconsumedEvents.length + 1 > highWatermark) {
+        paused = true;
+        emitter.pause();
+      }
+      unconsumedEvents.push(value);
+    } else {
+      unconsumedPromises.shift().resolve(iterResult(value, false));
+    }
   }
   function errorHandler(err) {
-    finished = true;
-    const pending = unconsumedPromises.shift();
-    if (pending) pending.reject(err);
-    else error = err;
-    iterator.return();
+    if (unconsumedPromises.length === 0) error = err;
+    else unconsumedPromises.shift().reject(err);
+    closeHandler();
   }
   function abortListener() {
     errorHandler(abortError(signal));
   }
   function closeHandler() {
-    for (const [name, handler] of listening) {
-      if (isEventTarget(emitter)) emitter.removeEventListener(name, handler);
-      else emitter.removeListener(name, handler);
-    }
-    listening.length = 0;
     signal?.removeEventListener("abort", abortListener);
+    while (listening.length) removeListener(emitter, ...listening.pop());
     finished = true;
-    const done = result(undefined, true);
+    paused = false;
+    const done = iterResult(undefined, true);
     while (unconsumedPromises.length) unconsumedPromises.shift().resolve(done);
     return Promise.resolve(done);
   }
 
-  listen(event, eventHandler);
-  if (event !== "error" && !isEventTarget(emitter)) listen("error", errorHandler);
-  for (const name of close) listen(name, closeHandler);
+  listen(event, options[kFirstEventParam] ? eventHandler : (...args) => eventHandler(args));
+  if (event !== "error" && typeof emitter.on === "function") listen("error", errorHandler);
+  for (const name of options?.close ?? []) listen(name, closeHandler);
   signal?.addEventListener("abort", abortListener, { once: true });
   return iterator;
 }

package/node/prelude/internal/features.js

@@ -23,14 +23,18 @@ export function lazyFunction(name, length = 0) {
   return f;
 }
 
+const kFeatureKey = Symbol("kFeatureKey");
+
 /** A class the program may construct, as a function the feature's module gives its prototype:
- *  `new Wrapper(…)` builds the feature's class, and instanceof holds. */
-export function lazyClass(name) {
+ *  `new Wrapper(…)` builds the feature's class, and instanceof holds. `key`, when two modules'
+ *  classes share a name (dns's and dns/promises' Resolver). */
+export function lazyClass(name, key = name) {
   const Wrapper = function (...args) {
     if (!new.target) throw new TypeError(`Class constructor ${name} cannot be invoked without 'new'`);
-    return Reflect.construct(feature(name), args, new.target);
+    return Reflect.construct(feature(key), args, new.target);
   };
   Object.defineProperty(Wrapper, "name", { value: name });
+  Object.defineProperty(Wrapper, kFeatureKey, { value: key });
   return Wrapper;
 }
 
@@ -48,7 +52,7 @@ export function lazyConstructor(name, length = 1) {
 
 /** Called by a feature's module for a lazyClass: the wrapper takes the class's prototype. */
 export function provideClass(Wrapper, Class) {
-  features[Wrapper.name] = Class;
+  features[Wrapper[kFeatureKey] ?? Wrapper.name] = Class;
   Wrapper.prototype = Class.prototype;
   Object.defineProperty(Class.prototype, "constructor", { value: Wrapper, writable: true, configurable: true });
   Object.setPrototypeOf(Wrapper, Object.getPrototypeOf(Class));

package/node/prelude/internal/fs_filehandle.js

@@ -62,13 +62,18 @@ export class FileHandle extends EventEmitter {
   }
 
   /* the call on the fd as a promise; EBADF once the handle is closed */
+  /* done at once, settled on a later turn of the loop: Node's run on the thread pool, so what
+   * the caller's ticks and promise jobs do (an abort) comes first. An async operation's promise
+   * is followed at once (its steps are these calls), so its rejection has a handler. */
   #call(syscall, fn) {
     return new Promise((resolve, reject) => {
       if (this.#fd < 0) return reject(closedError(syscall));
       try {
-        resolve(fn(this.#fd));
+        const result = fn(this.#fd);
+        if (typeof result?.then === "function") resolve(result);
+        else setImmediate(resolve, result);
       } catch (e) {
-        reject(e);
+        setImmediate(reject, e);
       }
     });
   }
@@ -274,12 +279,13 @@ export class FileHandle extends EventEmitter {
 }
 
 /** fs/promises' open(path[, flags[, mode]]): a FileHandle. */
+/* settled on a later turn of the loop, as Node's open on its thread pool (FileHandle's #call) */
 function promisesOpen(path, flags = "r", mode = 0o666) {
   return new Promise((resolve, reject) => {
     try {
-      resolve(new FileHandle(openSync(path, flags, mode)));
+      setImmediate(resolve, new FileHandle(openSync(path, flags, mode)));
     } catch (e) {
-      reject(e);
+      setImmediate(reject, e);
     }
   });
 }

package/node/prelude/internal/perf_histogram.js

@@ -432,4 +432,4 @@ function monitorEventLoopDelay(options = {}) {
   return new ELDHistogram(new Hdr(1, MAX_SAFE, 3), resolution);
 }
 
-Object.assign(features, { createHistogram, monitorEventLoopDelay });
+Object.assign(features, { createHistogram, monitorEventLoopDelay, isHistogram: (value) => value instanceof Histogram });

package/node/prelude/internal/process_more.js

@@ -10,7 +10,7 @@ import {
 } from "visaljs:host";
 import { isBuiltin, REQUIRE_TABLE } from "../module.js";
 import { parseDotenv } from "./dotenv.js";
-import { codeError, invalidArgType, notSupported, systemError } from "./errors.js";
+import { codeError, invalidArgType, invalidArgValue, notSupported, outOfRange, systemError } from "./errors.js";
 import "./process_events.js";
 
 const p = globalThis.process;
@@ -66,13 +66,13 @@ define("uptime", function uptime() {
 function cpuUsageOf(thread, prevValue) {
   const usage = procCpuUsage(thread);
   const [user, system] = typeof usage === "number" ? [0, 0] : usage;
-  if (prevValue === undefined) return { user, system };
+  if (!prevValue) return { user, system };  /* as Node's: any falsy prevValue */
   for (const key of ["user", "system"]) {
-    const value = prevValue?.[key];
+    const value = prevValue[key];
+    if (typeof value === "number" && value >= 0 && Number.isFinite(value)) continue;
+    if (key === "user" && (typeof prevValue !== "object" || Array.isArray(prevValue))) throw invalidArgType("prevValue", "of type object", prevValue);
     if (typeof value !== "number") throw invalidArgType(`prevValue.${key}`, "of type number", value);
-    if (!(value >= 0) || !Number.isFinite(value)) {
-      throw codeError(RangeError, "ERR_INVALID_ARG_VALUE", `The property 'prevValue.${key}' is invalid. Received ${value}`);
-    }
+    throw codeError(RangeError, "ERR_INVALID_ARG_VALUE", `The property 'prevValue.${key}' is invalid. Received ${value}`);
   }
   return { user: user - prevValue.user, system: system - prevValue.system };
 }
@@ -140,28 +140,36 @@ if (posix) {
     return groups;
   });
 
+  /* Node's validateId: a uint32 or a name; all checked before any is looked up */
+  const validateId = (id, name) => {
+    if (typeof id === "number") {
+      if (!Number.isInteger(id)) throw outOfRange(name, "an integer", id);
+      if (id < 0 || id > 4294967295) throw outOfRange(name, ">= 0 && <= 4294967295", id);
+    } else if (typeof id !== "string") {
+      throw invalidArgType(name, "one of type number or string", id);
+    }
+  };
+
   define("setgroups", function setgroups(groups) {
     if (!Array.isArray(groups)) throw invalidArgType("groups", "an instance of Array", groups);
-    const ids = groups.map((group, i) => {
-      if (typeof group !== "number" && typeof group !== "string") throw invalidArgType(`groups[${i}]`, "one of type number or string", group);
-      return idOf(group, "Group");
-    });
+    groups.forEach((group, i) => validateId(group, `groups[${i}]`));
+    const ids = groups.map((group) => idOf(group, "Group"));
     const err = procSetGroups(ids);
     if (err < 0) throw errnoException(err, "setgroups");
   });
 
   define("initgroups", function initgroups(user, extraGroup) {
+    validateId(user, "user");
+    validateId(extraGroup, "extraGroup");
+    const group = idOf(extraGroup, "Group");  /* as Node's: an unknown group is reported before an unknown user */
     let name = user;
     if (typeof user === "number") {
       name = procUserName(user);
       if (name === null) throw codeError(Error, "ERR_UNKNOWN_CREDENTIAL", `User identifier does not exist: ${user}`);
-    } else if (typeof user !== "string") {
-      throw invalidArgType("user", "one of type number or string", user);
     } else if (procUserId(user) === -1) {
       throw codeError(Error, "ERR_UNKNOWN_CREDENTIAL", `User identifier does not exist: ${user}`);
     }
-    if (typeof extraGroup !== "number" && typeof extraGroup !== "string") throw invalidArgType("extraGroup", "one of type number or string", extraGroup);
-    const err = procInitGroups(name, idOf(extraGroup, "Group"));
+    const err = procInitGroups(name, group);
     if (err < 0) throw errnoException(err, "initgroups");
   });
 }
@@ -183,9 +191,16 @@ define("execve", function execve(execPath, args = [], env = p.env) {
   if (!posix) throw codeError(Error, "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", `process.execve is not available on ${p.platform}`);
   validateString(execPath, "execPath");
   if (!Array.isArray(args)) throw invalidArgType("args", "an instance of Array", args);
-  args.forEach((arg, i) => validateString(arg, `args[${i}]`));
-  if (env === null || typeof env !== "object") throw invalidArgType("env", "of type object", env);
-  const pairs = Object.entries(env).map(([key, value]) => `${key}=${value}`);
+  args.forEach((arg, i) => {
+    if (typeof arg !== "string" || arg.includes("\u0000")) throw invalidArgValue(`args[${i}]`, "must be a string without null bytes", arg);
+  });
+  if (env === null || typeof env !== "object" || Array.isArray(env)) throw invalidArgType("env", "of type object", env);
+  const pairs = Object.entries(env).map(([key, value]) => {
+    if (typeof value !== "string" || key.includes("\u0000") || value.includes("\u0000")) {
+      throw invalidArgValue("env", "must be an object with string keys and values without null bytes", env);
+    }
+    return `${key}=${value}`;
+  });
   const err = procExecve(execPath, args, pairs);
   p.stderr.write(`process.execve failed with error code ${errnoName(err)}\n`);
   procAbort();

package/node/prelude/internal/process_signals.js

@@ -28,6 +28,12 @@ p.on("removeListener", (type) => {
   watched[type] = false;
 });
 
+/* the system call, as Node's binding: 0 or -errno */
+p._kill = function _kill(pid, signum) {
+  return processKill(pid, signum);
+};
+
+/* through process._kill, as Node's: a program (or a test) that replaces it sends no signal */
 p.kill = function kill(pid, sig) {
   if (pid != (pid | 0)) throw invalidArgType("pid", "of type number", pid);
   let signum;
@@ -37,7 +43,7 @@ p.kill = function kill(pid, sig) {
     signum = signals[sig];
     if (signum === undefined) throw codeError(TypeError, "ERR_UNKNOWN_SIGNAL", "Unknown signal: " + sig);
   }
-  const err = processKill(pid, signum);
-  if (err < 0) throw errnoException(err, "kill");
+  const err = p._kill(pid, signum);
+  if (err) throw errnoException(err, "kill");
   return true;
 };

package/node/prelude/internal/punycode.ts

@@ -0,0 +1,163 @@
+"use static";
+// Punycode (RFC 3492), node:punycode's decode and encode, typed: code points in an i32[], the
+// arithmetic in ints (its divisions are of non-negative values: Math.floor's).
+// Ported from punycode.js 2.1.0 (Copyright Mathias Bynens, MIT): node/third_party/punycode/LICENSE.
+import type { i32, int } from "visaljs";
+
+const maxInt: int = 2147483647;
+const base: int = 36;
+const tMin: int = 1;
+const tMax: int = 26;
+const skew: int = 38;
+const damp: int = 700;
+const initialBias: int = 72;
+const initialN: int = 128;
+
+const overflow = "Overflow: input needs wider integers to process";
+const notBasic = "Illegal input >= 0x80 (not a basic code point)";
+const invalidInput = "Invalid input";
+
+/** A string's code points: surrogate pairs joined, lone surrogates kept. */
+function ucs2decode(s: string): i32[] {
+  const output: i32[] = [];
+  const length: int = s.length;
+  let counter: int = 0;
+  while (counter < length) {
+    const value: int = s.charCodeAt(counter++);
+    if (value >= 0xd800 && value <= 0xdbff && counter < length) {
+      const extra: int = s.charCodeAt(counter++);
+      if ((extra & 0xfc00) === 0xdc00) output.push(((value & 0x3ff) << 10) + (extra & 0x3ff) + 0x10000);
+      else {
+        output.push(value);
+        counter--;
+      }
+    } else output.push(value);
+  }
+  return output;
+}
+
+/* a basic code point's digit value, or base for anything else */
+function basicToDigit(codePoint: int): int {
+  if (codePoint >= 0x30 && codePoint < 0x3a) return 26 + (codePoint - 0x30);
+  if (codePoint >= 0x41 && codePoint < 0x5b) return codePoint - 0x41;
+  if (codePoint >= 0x61 && codePoint < 0x7b) return codePoint - 0x61;
+  return base;
+}
+
+/* a digit's code point, lowercase (0..25 a..z, 26..35 0..9) */
+function digitToBasic(digit: int): int {
+  return digit < 26 ? digit + 97 : digit + 22;
+}
+
+/* RFC 3492 3.4 */
+function adapt(delta: int, numPoints: int, firstTime: boolean): int {
+  let k: int = 0;
+  delta = firstTime ? delta / damp : delta >> 1;
+  delta += delta / numPoints;
+  for (; delta > ((base - tMin) * tMax) >> 1; k += base) delta = delta / (base - tMin);
+  return k + ((base - tMin + 1) * delta) / (delta + skew);
+}
+
+/** Punycode (ASCII only) to the Unicode string it encodes. */
+export function decode(input: string): string {
+  const output: i32[] = [];
+  const inputLength: int = input.length;
+  let i: int = 0;
+  let n: int = initialN;
+  let bias: int = initialBias;
+
+  /* the basic code points: everything before the last delimiter */
+  let basic: int = input.lastIndexOf("-");
+  if (basic < 0) basic = 0;
+  for (let j: int = 0; j < basic; ++j) {
+    const c: int = input.charCodeAt(j);
+    if (c >= 0x80) throw new RangeError(notBasic);
+    output.push(c);
+  }
+
+  /* the deltas, each inserting a code point */
+  for (let index: int = basic > 0 ? basic + 1 : 0; index < inputLength;) {
+    const oldi: int = i;
+    for (let w: int = 1, k: int = base; ; k += base) {
+      if (index >= inputLength) throw new RangeError(invalidInput);
+      const digit: int = basicToDigit(input.charCodeAt(index++));
+      if (digit >= base) throw new RangeError(invalidInput);
+      if (digit > (maxInt - i) / w) throw new RangeError(overflow);
+      i += digit * w;
+      const t: int = k <= bias ? tMin : k >= bias + tMax ? tMax : k - bias;
+      if (digit < t) break;
+      const baseMinusT: int = base - t;
+      if (w > maxInt / baseMinusT) throw new RangeError(overflow);
+      w *= baseMinusT;
+    }
+    const out: int = output.length + 1;
+    bias = adapt(i - oldi, out, oldi === 0);
+    if (i / out > maxInt - n) throw new RangeError(overflow);
+    n += i / out;
+    i %= out;
+    output.push(0);
+    for (let m: int = output.length - 1; m > i; m--) output[m] = output[m - 1];
+    output[i++] = n;
+  }
+
+  let s = "";
+  for (let k: int = 0; k < output.length; k++) {
+    const c: int = output[k];
+    /* past U+10FFFF: String.fromCodePoint's RangeError */
+    s += c < 0x10000 ? String.fromCharCode(c) : String.fromCodePoint(c);
+  }
+  return s;
+}
+
+/** A Unicode string as Punycode (ASCII only). */
+export function encode(str: string): string {
+  const input = ucs2decode(str);
+  const inputLength: int = input.length;
+  let n: int = initialN;
+  let delta: int = 0;
+  let bias: int = initialBias;
+
+  let output = "";
+  for (let j: int = 0; j < inputLength; j++) {
+    const c: int = input[j];
+    if (c < 0x80) output += String.fromCharCode(c);
+  }
+  const basicLength: int = output.length;
+  let handledCPCount: int = basicLength;
+  if (basicLength > 0) output += "-";
+
+  while (handledCPCount < inputLength) {
+    /* the next code point to insert: the smallest not yet handled */
+    let m: int = maxInt;
+    for (let j: int = 0; j < inputLength; j++) {
+      const c: int = input[j];
+      if (c >= n && c < m) m = c;
+    }
+    const handledCPCountPlusOne: int = handledCPCount + 1;
+    if (m - n > (maxInt - delta) / handledCPCountPlusOne) throw new RangeError(overflow);
+    delta += (m - n) * handledCPCountPlusOne;
+    n = m;
+    for (let j: int = 0; j < inputLength; j++) {
+      const c: int = input[j];
+      if (c < n && ++delta > maxInt) throw new RangeError(overflow);
+      if (c === n) {
+        let q: int = delta;
+        for (let k: int = base; ; k += base) {
+          const t: int = k <= bias ? tMin : k >= bias + tMax ? tMax : k - bias;
+          if (q < t) break;
+          const qMinusT: int = q - t;
+          const baseMinusT: int = base - t;
+          output += String.fromCharCode(digitToBasic(t + (qMinusT % baseMinusT)));
+          q = qMinusT / baseMinusT;
+        }
+        output += String.fromCharCode(digitToBasic(q));
+        bias = adapt(delta, handledCPCountPlusOne, handledCPCount === basicLength);
+        delta = 0;
+        ++handledCPCount;
+      }
+    }
+    ++delta;
+    ++n;
+  }
+  return output;
+}