bump quickjs version to get setStackFrameMapper

Author: suchipi

meta/generated-docs/README.md

@@ -289,6 +289,7 @@ For convenience, two of the builtin modules from QuickJS are also available as g
 [`TypeValidator`]: /meta/generated-docs/types.md#typevalidator-type
 [`JSX.pragma`]: /meta/generated-docs/jsx.md#jsxpragma-exported-string
 [`setMainModule`]: /meta/generated-docs/engine.md#quickjsenginesetmainmodule-exported-function
+[`setStackFrameMapper`]: /meta/generated-docs/engine.md#quickjsenginesetstackframemapper-exported-function
 [`setExitCode`]: /meta/generated-docs/cmdline.md#quickjsstdsetexitcode-exported-function
 [`FILE.seek`]: /meta/generated-docs/std.md#fileseek-method
 [`FILE.setvbuf`]: /meta/generated-docs/std.md#filesetvbuf-method

meta/generated-docs/bytecode.md

@@ -66,8 +66,7 @@ cycles, pass `preserveReferences: false`.
 To serialize Error instances (including `TypeError`, `RangeError`,
 `SyntaxError`, `ReferenceError`, `URIError`, `EvalError`,
 `AggregateError`, and `InternalError`), pass `serializeErrors: true`.
-Without it, attempting to serialize any Error instance throws
-"unsupported object class".
+Without it, attempting to serialize any Error instance throws.
 
 ```ts
 export function fromValue(

meta/generated-docs/engine.md

@@ -10,6 +10,9 @@
   - ["quickjs:engine".defineBuiltinModule (exported function)](#quickjsenginedefinebuiltinmodule-exported-function)
   - ["quickjs:engine".ModuleDelegate (exported ModuleDelegate)](#quickjsenginemoduledelegate-exported-moduledelegate)
   - ["quickjs:engine".gc (exported function)](#quickjsenginegc-exported-function)
+  - ["quickjs:engine".StackFrameMapper (exported type)](#quickjsenginestackframemapper-exported-type)
+  - ["quickjs:engine".setStackFrameMapper (exported function)](#quickjsenginesetstackframemapper-exported-function)
+  - ["quickjs:engine".getStackFrameMapper (exported function)](#quickjsenginegetstackframemapper-exported-function)
   - ["quickjs:engine".formatValue (exported function)](#quickjsengineformatvalue-exported-function)
   - ["quickjs:engine".\_\_printObject (exported function)](#quickjsengine__printobject-exported-function)
 
@@ -54,6 +57,22 @@ declare module "quickjs:engine" {
   ): void;
   export const ModuleDelegate: ModuleDelegate;
   export function gc(): void;
+  export type StackFrameMapper = (
+    filename: string,
+    line: number,
+    column: number,
+  ) =>
+    | {
+        filename: string;
+        line: number;
+        column: number;
+      }
+    | null
+    | undefined;
+  export function setStackFrameMapper(
+    mapper: StackFrameMapper | null | undefined,
+  ): void;
+  export function getStackFrameMapper(): StackFrameMapper | null;
   export function formatValue(
     value: any,
     options?: {
@@ -221,6 +240,94 @@ function is useful in case of specific memory constraints or for testing.
 export function gc(): void;
 ```
 
+## "quickjs:engine".StackFrameMapper (exported type)
+
+A callback that translates the location of a stack frame as an error's
+backtrace is built. See [setStackFrameMapper](/meta/generated-docs/engine.md#quickjsenginesetstackframemapper-exported-function) for details.
+
+`line` and `column` are 1-based, both for the values passed in and for the
+values returned. To change the frame's location, return an object
+containing all three of `filename`, `line`, and `column`. Return `null` or
+`undefined` (or an object missing any field) to leave the location
+unchanged.
+
+```ts
+type StackFrameMapper = (
+  filename: string,
+  line: number,
+  column: number,
+) =>
+  | {
+      filename: string;
+      line: number;
+      column: number;
+    }
+  | null
+  | undefined;
+```
+
+## "quickjs:engine".setStackFrameMapper (exported function)
+
+Register a callback that translates the location of each stack frame as an
+error's backtrace is built. This is the hook to use for source-map support:
+the engine itself knows nothing about source maps, so the callback is where
+you map a compiled `(filename, line, column)` back to its original source
+location.
+
+The callback is invoked once per frame while the backtrace string is being
+assembled. The location it returns is used both in the human-readable
+`error.stack` string AND in the `fileName` / `lineNumber` / `columnNumber`
+own properties set on the error object, so they stay consistent.
+
+`line` and `column` are 1-based, both for the values passed to the callback
+and for the values it returns.
+
+To take effect, the callback must return an object containing all three of
+`filename`, `line`, and `column`. If it instead returns `null` or
+`undefined`, returns an object missing any of those fields, returns a
+non-object, or throws, the frame's original location is kept unchanged (a
+thrown error is swallowed rather than propagated into backtrace
+construction).
+
+Only one mapper can be registered at a time; registering a new one replaces
+the previous one. Pass `null` or `undefined` to unregister, restoring the
+default behavior of reporting compiled locations.
+
+While the mapper is running, it is temporarily disabled for any error thrown
+from within it, so an error thrown inside the mapper will not recurse
+infinitely; that nested error's backtrace simply reports its original
+(unmapped) locations.
+
+- `@param` _mapper_ — The translation callback, or `null`/`undefined` to unregister.
+
+```ts
+export function setStackFrameMapper(
+  mapper: StackFrameMapper | null | undefined,
+): void;
+```
+
+## "quickjs:engine".getStackFrameMapper (exported function)
+
+Return the stack frame mapper currently registered via
+[setStackFrameMapper](/meta/generated-docs/engine.md#quickjsenginesetstackframemapper-exported-function), or `null` if none is registered.
+
+This is useful for composing mappers: read the existing one, then register
+a new mapper that adds your own behavior and delegates to the previous one.
+
+```js
+const previous = getStackFrameMapper();
+setStackFrameMapper((filename, line, column) => {
+  const mapped = previous ? previous(filename, line, column) : null;
+  const location = mapped ?? { filename, line, column };
+  // ...apply your own additional adjustments to `location`...
+  return location;
+});
+```
+
+```ts
+export function getStackFrameMapper(): StackFrameMapper | null;
+```
+
 ## "quickjs:engine".formatValue (exported function)
 
 Format a value for debugging using QuickJS's built-in C-level printer.

meta/scripts/lib/generated-doc-links.json5

@@ -143,6 +143,7 @@
   TypeValidator: "/meta/generated-docs/types.md#typevalidator-type",
   "JSX.pragma": "/meta/generated-docs/jsx.md#jsxpragma-exported-string",
   setMainModule: "/meta/generated-docs/engine.md#quickjsenginesetmainmodule-exported-function",
+  setStackFrameMapper: "/meta/generated-docs/engine.md#quickjsenginesetstackframemapper-exported-function",
   setExitCode: "/meta/generated-docs/cmdline.md#quickjsstdsetexitcode-exported-function",
   "FILE.seek": "/meta/generated-docs/std.md#fileseek-method",
   "FILE.setvbuf": "/meta/generated-docs/std.md#filesetvbuf-method",
@@ -194,7 +195,7 @@
   '"quickjs:os"': "/meta/generated-docs/os.md#quickjsos-namespace",
   '"quickjs:bytecode"': "/meta/generated-docs/bytecode.md#quickjsbytecode-namespace",
   '"quickjs:context"': "/meta/generated-docs/quickjs-context.md#quickjscontext-namespace",
-  "import(\"quickjs:context\")": "/meta/generated-docs/quickjs-context.md#quickjscontext-namespace",
+  'import("quickjs:context")': "/meta/generated-docs/quickjs-context.md#quickjscontext-namespace",
   '"quickjs:encoding"': "/meta/generated-docs/encoding.md#quickjsencoding-namespace",
   '"quickjs:engine"': "/meta/generated-docs/engine.md#quickjsengine-namespace",
   '"quickjs:cmdline"': "/meta/generated-docs/cmdline.md#quickjscmdline-namespace",

package-lock.json

@@ -10,7 +10,7 @@
     "@suchipi/dtsmd": "^1.4.0",
     "@suchipi/macaroni": "^0.3.0",
     "@suchipi/print": "^2.5.0",
-    "@suchipi/quickjs": "^0.16.0",
+    "@suchipi/quickjs": "^0.16.1",
     "@suchipi/shinobi": "^3.0.0",
     "@types/coffeescript": "^2.5.7",
     "@types/minimatch": "^5.1.2",

package.json

@@ -6508,6 +6508,78 @@ declare module "quickjs:engine" {
    */
   export function gc(): void;
 
+  /**
+   * A callback that translates the location of a stack frame as an error's
+   * backtrace is built. See {@link setStackFrameMapper} for details.
+   *
+   * `line` and `column` are 1-based, both for the values passed in and for the
+   * values returned. To change the frame's location, return an object
+   * containing all three of `filename`, `line`, and `column`. Return `null` or
+   * `undefined` (or an object missing any field) to leave the location
+   * unchanged.
+   */
+  export type StackFrameMapper = (
+    filename: string,
+    line: number,
+    column: number
+  ) => { filename: string; line: number; column: number } | null | undefined;
+
+  /**
+   * Register a callback that translates the location of each stack frame as an
+   * error's backtrace is built. This is the hook to use for source-map support:
+   * the engine itself knows nothing about source maps, so the callback is where
+   * you map a compiled `(filename, line, column)` back to its original source
+   * location.
+   *
+   * The callback is invoked once per frame while the backtrace string is being
+   * assembled. The location it returns is used both in the human-readable
+   * `error.stack` string AND in the `fileName` / `lineNumber` / `columnNumber`
+   * own properties set on the error object, so they stay consistent.
+   *
+   * `line` and `column` are 1-based, both for the values passed to the callback
+   * and for the values it returns.
+   *
+   * To take effect, the callback must return an object containing all three of
+   * `filename`, `line`, and `column`. If it instead returns `null` or
+   * `undefined`, returns an object missing any of those fields, returns a
+   * non-object, or throws, the frame's original location is kept unchanged (a
+   * thrown error is swallowed rather than propagated into backtrace
+   * construction).
+   *
+   * Only one mapper can be registered at a time; registering a new one replaces
+   * the previous one. Pass `null` or `undefined` to unregister, restoring the
+   * default behavior of reporting compiled locations.
+   *
+   * While the mapper is running, it is temporarily disabled for any error thrown
+   * from within it, so an error thrown inside the mapper will not recurse
+   * infinitely; that nested error's backtrace simply reports its original
+   * (unmapped) locations.
+   *
+   * @param mapper - The translation callback, or `null`/`undefined` to unregister.
+   */
+  export function setStackFrameMapper(
+    mapper: StackFrameMapper | null | undefined
+  ): void;
+
+  /**
+   * Return the stack frame mapper currently registered via
+   * {@link setStackFrameMapper}, or `null` if none is registered.
+   *
+   * This is useful for composing mappers: read the existing one, then register
+   * a new mapper that adds your own behavior and delegates to the previous one.
+   *
+   * ```js
+   * const previous = getStackFrameMapper();
+   * setStackFrameMapper((filename, line, column) => {
+   *   const mapped = previous ? previous(filename, line, column) : null;
+   *   const location = mapped ?? { filename, line, column };
+   *   // ...apply your own additional adjustments to `location`...
+   *   return location;
+   * });
+   * ```
+   */
+  export function getStackFrameMapper(): StackFrameMapper | null;
+
   /**
    * Format a value for debugging using QuickJS's built-in C-level printer.
    *
@@ -6609,8 +6681,7 @@ declare module "quickjs:bytecode" {
    * To serialize Error instances (including `TypeError`, `RangeError`,
    * `SyntaxError`, `ReferenceError`, `URIError`, `EvalError`,
    * `AggregateError`, and `InternalError`), pass `serializeErrors: true`.
-   * Without it, attempting to serialize any Error instance throws
-   * "unsupported object class".
+   * Without it, attempting to serialize any Error instance throws.
    */
   export function fromValue(
     value: any,