visaljs 0.0.7 → 0.0.8

package/node/prelude/url.js

@@ -1,7 +1,8 @@
-// node:url (ADR 0012, layer 3): the legacy url.parse/format/resolve API (Node's lib/url.js, v22.22.2,
+// node:url: the legacy url.parse/format/resolve API (Node's lib/url.js, v22.22.2,
 // ported: primordials as plain calls, its requires as imports, Node's bindings as JS over the
 // url component), the WHATWG URL and URLSearchParams (the runtime's), and Node's file-URL and
-// domain helpers (from lib/internal/url.js; POSIX paths). Node's notice for lib/url.js:
+// domain helpers (from lib/internal/url.js: Windows paths on Windows, or with { windows: true }).
+// Node's notice for lib/url.js:
 //
 // Copyright Joyent, Inc. and other Node contributors.
 //
@@ -24,7 +25,7 @@
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-import { codeError, invalidArgType } from "./internal/errors.js";
+import { codeError, invalidArgType, invalidArgValue } from "./internal/errors.js";
 import { encodeStr, hexTable } from "./internal/querystring.js";
 import * as path from "./path.js";
 import querystring from "./querystring.js";
@@ -152,35 +153,65 @@ function urlToHttpOptions(url) {
   return options;
 }
 
+const isWindows = process.platform === "win32";
+
 function fileUrlOf(path) {
-  if (typeof path === "string") return new URL(path);
-  if (!(path instanceof URL)) throw invalidArgType("path", "of type string or an instance of URL", path);
-  return path;
+  let url = path;
+  if (typeof path === "string") url = new URL(path);
+  else if (!(path instanceof URL)) throw invalidArgType("path", "of type string or an instance of URL", path);
+  if (url.protocol !== "file:") throw codeError(TypeError, "ERR_INVALID_URL_SCHEME", "The URL must be of scheme file");
+  return url;
 }
 
-function checkFileUrl(url) {
-  if (url.protocol !== "file:") throw codeError(TypeError, "ERR_INVALID_URL_SCHEME", "The URL must be of scheme file");
-  if (url.hostname !== "") throw codeError(TypeError, "ERR_INVALID_FILE_URL_HOST", `File URL host must be "localhost" or empty on ${process.platform}`);
-  const pathname = url.pathname;
+/* an encoded / (and on Windows, \): the path would name another file */
+function checkEncodedSlashes(pathname, windows) {
   for (let n = 0; n < pathname.length; n++) {
-    if (pathname[n] === "%" && pathname[n + 1] === "2" && (pathname.codePointAt(n + 2) | 0x20) === 102) {
-      throw codeError(TypeError, "ERR_INVALID_FILE_URL_PATH", "File URL path must not include encoded / characters");
+    if (pathname[n] !== "%") continue;
+    const third = pathname.codePointAt(n + 2) | 0x20;
+    if (pathname[n + 1] === "2" && third === 102) {
+      throw codeError(TypeError, "ERR_INVALID_FILE_URL_PATH", `File URL path must not include encoded ${windows ? "\\ or / characters" : "/ characters"}`);
+    }
+    if (windows && pathname[n + 1] === "5" && third === 99) {
+      throw codeError(TypeError, "ERR_INVALID_FILE_URL_PATH", "File URL path must not include encoded \\ or / characters");
     }
   }
-  return pathname;
 }
 
-function fileURLToPath(path) {
-  const pathname = checkFileUrl(fileUrlOf(path));
-  return pathname.includes("%") ? decodeURIComponent(pathname) : pathname;
+function checkHost(url) {
+  if (url.hostname !== "") throw codeError(TypeError, "ERR_INVALID_FILE_URL_HOST", `File URL host must be "localhost" or empty on ${process.platform}`);
+}
+
+/* a local Windows path needs a drive letter: /C:/… */
+function checkDrive(letter, sep) {
+  if ((letter | 0x20) < 97 || (letter | 0x20) > 122 || sep !== CHAR_COLON) {
+    throw codeError(TypeError, "ERR_INVALID_FILE_URL_PATH", "File URL path must be absolute");
+  }
 }
 
-function fileURLToPathBuffer(path) {
-  const pathname = checkFileUrl(fileUrlOf(path));
+function fileURLToPath(path, options) {
+  const url = fileUrlOf(path);
+  const windows = options?.windows ?? isWindows;
+  let pathname = url.pathname;
+  if (!windows) {
+    checkHost(url);
+    checkEncodedSlashes(pathname, false);
+    return pathname.includes("%") ? decodeURIComponent(pathname) : pathname;
+  }
+  checkEncodedSlashes(pathname, true);
+  pathname = pathname.replace(/\//g, "\\");
+  if (pathname.includes("%")) pathname = decodeURIComponent(pathname);
+  /* a host is a UNC path's server: \\server\share\… */
+  if (url.hostname !== "") return `\\\\${domainToUnicode(url.hostname)}${pathname}`;
+  checkDrive(pathname.charCodeAt(1), pathname.charCodeAt(2));
+  return pathname.slice(1);
+}
+
+/* the bytes of a pathname with its %XX decoded; an invalid one is kept as it is */
+function percentDecode(pathname) {
   const bytes = Buffer.from(pathname, "utf8");
   const out = [];
+  const hex = (c) => (c >= 48 && c <= 57 ? c - 48 : (c | 0x20) >= 97 && (c | 0x20) <= 102 ? (c | 0x20) - 87 : -1);
   for (let i = 0; i < bytes.length; i++) {
-    const hex = (c) => (c >= 48 && c <= 57 ? c - 48 : (c | 0x20) >= 97 && (c | 0x20) <= 102 ? (c | 0x20) - 87 : -1);
     if (bytes[i] === 37 && i + 2 < bytes.length && hex(bytes[i + 1]) >= 0 && hex(bytes[i + 2]) >= 0) {
       out.push(hex(bytes[i + 1]) * 16 + hex(bytes[i + 2]));
       i += 2;
@@ -191,19 +222,49 @@ function fileURLToPathBuffer(path) {
   return Buffer.from(out);
 }
 
-function pathToFileURL(filepath) {
-  validateString(filepath, "path");
-  let resolved = path.resolve(filepath);
-  /* path.resolve strips trailing slashes, so they're added back */
-  if (filepath.charCodeAt(filepath.length - 1) === CHAR_FORWARD_SLASH && resolved[resolved.length - 1] !== path.sep) resolved += "/";
-  /* the characters a URL's pathname setter would take differently */
-  resolved = resolved.replace(/%/g, "%25").replace(/\\/g, "%5C").replace(/\n/g, "%0A").replace(/\r/g, "%0D").replace(/\t/g, "%09")
-    .replace(/#/g, "%23").replace(/\?/g, "%3F");
+/* as fileURLToPath, without decoding the bytes as UTF-8, nor looking for encoded slashes */
+function fileURLToPathBuffer(path, options) {
+  const url = fileUrlOf(path);
+  if (!(options?.windows ?? isWindows)) {
+    checkHost(url);
+    return percentDecode(url.pathname);
+  }
+  const decoded = percentDecode(url.pathname.replace(/\//g, "\\"));
+  if (url.hostname !== "") return Buffer.concat([Buffer.from("\\\\", "ascii"), Buffer.from(domainToUnicode(url.hostname), "utf8"), decoded]);
+  checkDrive(decoded[1], decoded[2]);
+  return decoded.subarray(1);
+}
+
+/* a resolved path as a file URL (Node's binding): the characters a pathname's setter would take
+ * differently are encoded; on Windows, \ is the separator */
+function fileUrlFromPath(resolved, windows, hostname) {
+  resolved = resolved.replace(/%/g, "%25").replace(/\\/g, windows ? "/" : "%5C").replace(/\n/g, "%0A").replace(/\r/g, "%0D")
+    .replace(/\t/g, "%09").replace(/#/g, "%23").replace(/\?/g, "%3F");
   const url = new URL("file://");
+  if (hostname !== undefined) url.hostname = hostname;
   url.pathname = resolved;
   return url;
 }
 
+function pathToFileURL(filepath, options) {
+  validateString(filepath, "path");
+  const windows = options?.windows ?? isWindows;
+  const isUNC = windows && filepath.startsWith("\\\\");
+  let resolved = isUNC ? filepath : windows ? path.win32.resolve(filepath) : path.posix.resolve(filepath);
+  if (isUNC || (windows && resolved.startsWith("\\\\"))) {
+    /* \\server\share\resource; an extended one's "\\?\UNC\" prefix is skipped */
+    const prefixLength = resolved.startsWith("\\\\?\\UNC\\") ? 8 : 2;
+    const hostnameEndIndex = resolved.indexOf("\\", prefixLength);
+    if (hostnameEndIndex === -1) throw invalidArgValue("path", "Missing UNC resource path", resolved);
+    if (hostnameEndIndex === 2) throw invalidArgValue("path", "Empty UNC servername", resolved);
+    return fileUrlFromPath(resolved.slice(hostnameEndIndex), true, resolved.slice(prefixLength, hostnameEndIndex));
+  }
+  /* path.resolve strips trailing slashes, so they're added back */
+  const last = filepath.charCodeAt(filepath.length - 1);
+  if ((last === CHAR_FORWARD_SLASH || (windows && last === CHAR_BACKWARD_SLASH)) && resolved[resolved.length - 1] !== path.sep) resolved += "/";
+  return fileUrlFromPath(resolved, windows);
+}
+
 /* ---- Node's lib/url.js -------------------------------------------------------------------------- */
 
 // Original url.parse() API

package/node/prelude/util.js

@@ -1,7 +1,14 @@
-// node:util (ADR 0012, layer 3): inspect and format are the runtime's (console prints
-// with them), Node's algorithms in C; deprecate, inherits and types (node:util/types).
+// node:util: inspect and format are the runtime's (console prints
+// with them), Node's algorithms in C; deprecate, inherits, types (node:util/types),
+// isDeepStrictEqual (node:assert's deepStrictEqual, internal/comparisons.js), promisify,
+// callbackify, stripVTControlCharacters and styleText, debuglog, parseArgs, parseEnv, MIMEType,
+// diff, the system error names, and the deprecated is* functions and log; TextEncoder and
+// TextDecoder, the globals (the runtime's encoding component).
 import { utilFormat, utilFormatWithOptions, utilInspect } from "visaljs:host";
-import types from "./util_types.js";
+import { isDeepStrictEqual } from "./internal/comparisons.js";
+import { validateFunction, validateString } from "./internal/errors.js";
+import { lazyClass, lazyFunction } from "./internal/features.js";
+import types, { isPromise } from "./util_types.js";
 
 export { types };
 
@@ -23,6 +30,75 @@ inspect.defaultOptions = {
 };
 export const format = utilFormat;
 export const formatWithOptions = utilFormatWithOptions;
+export const TextEncoder = globalThis.TextEncoder;
+export const TextDecoder = globalThis.TextDecoder;
+
+/* ANSI escape codes, as Node's internal/util/inspect.js matches them: an OSC sequence (a terminal
+   hyperlink: ESC ] … BEL) whole, or a CSI sequence */
+const ansi = new RegExp(
+  "(?:\\u001B\\][\\s\\S]*?(?:\\u0007|\\u001B\\u005C|\\u009C))" +
+  "|[\\u001B\\u009B][[\\]()#;?]*" +
+  "(?:\\d{1,4}(?:[;:]\\d{0,4})*)?" +
+  "[\\dA-PR-TZcf-nq-uy=><~]", "g",
+);
+
+const kCustomPromisifiedSymbol = Symbol.for("nodejs.util.promisify.custom");
+/* names to make an object of when the callback gets several values, e.g. ['bytesRead', 'buffer'] */
+/* (registered: node:fs names its functions' values without importing node:util) */
+const kCustomPromisifyArgsSymbol = Symbol.for("visaljs.util.customPromisifyArgs");
+
+/** A function taking a callback (err, value) as one returning a promise: Node's
+ *  internal/util.js promisify, with its util.promisify.custom. */
+export function promisify(original) {
+  validateFunction(original, "original");
+
+  if (original[kCustomPromisifiedSymbol]) {
+    const fn = original[kCustomPromisifiedSymbol];
+
+    validateFunction(fn, "util.promisify.custom");
+
+    return Object.defineProperty(fn, kCustomPromisifiedSymbol, { value: fn, enumerable: false, writable: false, configurable: true });
+  }
+
+  const argumentNames = original[kCustomPromisifyArgsSymbol];
+
+  function fn(...args) {
+    return new Promise((resolve, reject) => {
+      args.push((err, ...values) => {
+        if (err) {
+          return reject(err);
+        }
+        if (argumentNames !== undefined && values.length > 1) {
+          const obj = {};
+          for (let i = 0; i < argumentNames.length; i++) obj[argumentNames[i]] = values[i];
+          resolve(obj);
+        } else {
+          resolve(values[0]);
+        }
+      });
+      if (isPromise(Reflect.apply(original, this, args))) {
+        process.emitWarning("Calling promisify on a function that returns a Promise is likely a mistake.", "DeprecationWarning", "DEP0174");
+      }
+    });
+  }
+
+  Object.setPrototypeOf(fn, Object.getPrototypeOf(original));
+
+  Object.defineProperty(fn, kCustomPromisifiedSymbol, { value: fn, enumerable: false, writable: false, configurable: true });
+
+  const descriptors = Object.getOwnPropertyDescriptors(original);
+  for (const descriptor of Object.values(descriptors)) Object.setPrototypeOf(descriptor, null);
+  return Object.defineProperties(fn, descriptors);
+}
+
+promisify.custom = kCustomPromisifiedSymbol;
+
+/** The string without its ANSI escape codes (colors, cursor movements, …). */
+export function stripVTControlCharacters(str) {
+  validateString(str, "str");
+  if (!str.includes("\u001B") && !str.includes("\u009B")) return str;  /* no escape introducer */
+  return str.replace(ansi, "");
+}
 
 const codesWarned = new Set();
 
@@ -36,7 +112,7 @@ export function deprecate(fn, msg, code) {
   if (process.noDeprecation === true) return fn;
   let warned = false;
   function deprecated(...args) {
-    if (!warned) {
+    if (!warned && process.noDeprecation !== true) {
       warned = true;
       if (code !== undefined) {
         if (!codesWarned.has(code)) {
@@ -64,4 +140,44 @@ export function inherits(ctor, superCtor) {
   Object.setPrototypeOf(ctor.prototype, superCtor.prototype);
 }
 
-export default { format, formatWithOptions, inspect, deprecate, inherits, types };
+export { isDeepStrictEqual };
+
+/* features in modules of their own, linked when the program names them (internal/features.js) */
+export const MIMEType = lazyClass("MIMEType");
+export const MIMEParams = lazyClass("MIMEParams");
+
+export const parseArgs = lazyFunction("parseArgs");  /* internal/parse_args.js */
+
+/* internal/system_errors.js */
+export const getSystemErrorName = lazyFunction("getSystemErrorName", 1);
+export const getSystemErrorMessage = lazyFunction("getSystemErrorMessage", 1);
+export const getSystemErrorMap = lazyFunction("getSystemErrorMap");
+
+export const parseEnv = lazyFunction("parseEnv", 1);  /* internal/dotenv.js */
+
+/* internal/util_styles.js (with inspect.colors and inspect.styles), internal/util_diff.js */
+export const styleText = lazyFunction("styleText", 2);
+export const diff = lazyFunction("diff", 2);
+
+/* the rarely used ones: internal/util_more.js */
+export const callbackify = lazyFunction("callbackify", 1);
+export const debuglog = lazyFunction("debuglog", 2);
+export const debug = debuglog;
+export const toUSVString = lazyFunction("toUSVString", 1);
+export const aborted = lazyFunction("aborted", 2);
+export const transferableAbortSignal = lazyFunction("transferableAbortSignal", 1);
+export const transferableAbortController = lazyFunction("transferableAbortController");
+export const getCallSites = lazyFunction("getCallSites");
+export const setTraceSigInt = lazyFunction("setTraceSigInt", 1);
+export const convertProcessSignalToExitCode = lazyFunction("convertProcessSignalToExitCode", 1);
+export const _extend = lazyFunction("_extend", 2);
+export const isArray = lazyFunction("isArray", 1);
+
+/* in Node 24's order, which Object.keys(util) shows (less the internal _errnoException and
+   _exceptionWithHostPort) */
+export default {
+  _extend, callbackify, convertProcessSignalToExitCode, debug, debuglog, deprecate, format, styleText, formatWithOptions, getCallSites,
+  getSystemErrorMap, getSystemErrorName, getSystemErrorMessage, inherits, inspect, isArray, isDeepStrictEqual, promisify,
+  stripVTControlCharacters, toUSVString, transferableAbortSignal, transferableAbortController, aborted, types, parseEnv, parseArgs,
+  TextDecoder, TextEncoder, MIMEType, MIMEParams, diff, setTraceSigInt,
+};

package/node/prelude/util_types.js

@@ -74,12 +74,13 @@ export const isFloat64Array = (value) => tag(value) === "Float64Array";
 export const isBigInt64Array = (value) => tag(value) === "BigInt64Array";
 export const isBigUint64Array = (value) => tag(value) === "BigUint64Array";
 
-/* Node's order, which Object.keys(util.types) shows */
+/* Node 24's order, which Object.keys(util.types) shows */
 export default {
-  isArgumentsObject, isArrayBuffer, isAsyncFunction, isBigIntObject, isBooleanObject, isDataView, isDate, isExternal,
+  isArgumentsObject, isArrayBuffer, isAsyncFunction, isBigIntObject, isBooleanObject, isDate, isExternal,
   isGeneratorFunction, isGeneratorObject, isMap, isMapIterator, isModuleNamespaceObject, isNativeError, isNumberObject,
   isPromise, isProxy, isRegExp, isSet, isSetIterator, isSharedArrayBuffer, isStringObject, isSymbolObject, isWeakMap,
-  isWeakSet, isAnyArrayBuffer, isBoxedPrimitive, isArrayBufferView, isTypedArray, isUint8Array, isUint8ClampedArray,
+  isWeakSet, isAnyArrayBuffer, isBoxedPrimitive, isArrayBufferView, isDataView, isTypedArray, isUint8Array,
+  isUint8ClampedArray,
   isUint16Array, isUint32Array, isInt8Array, isInt16Array, isInt32Array, isFloat16Array, isFloat32Array,
   isFloat64Array, isBigInt64Array, isBigUint64Array, isKeyObject, isCryptoKey,
 };