@suchipi/quickjs 0.4.2 → 0.5.0

package/README.md

@@ -49,6 +49,7 @@ Fork of the fantastic QuickJS engine by Fabrice Bellard, with the following chan
 - `String.dedent` added (template tag function, like the proposed [String.dedent](https://github.com/tc39/proposal-string-dedent)).
 - Several C-side helper functions were moved out of quickjs-libc and into quickjs-utils.
 - Most module-related code (setting import.meta, etc) was moved into quickjs-modulesys.
+- Added `std.setExitCode`, `std.getExitCode`, and made `std.exit`'s parameter optional. The value passed to `std.setExitCode` will be used when the process exits normally, or when `std.exit` is called without any arguments. `std.setExitCode`, `std.getExitCode`, and `std.exit` throw if called from a thread other than the main thread (ie. a Worker).
 
 ## Changes to the `qjs` repl:
 
@@ -108,6 +109,9 @@ Helper structs, functions, and macros that make it easier to work with QuickJS i
   - It's the same as the global `require`; it's just added to import.meta for compatibility with bundlers that output `import.meta.require`, like `bun`.
 - Adds `import.meta.resolve`
   - Similar to [the one in the browser](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve#specifications), but it's actually just `require.resolve` exposed via `import.meta`.
+- Makes `import.meta.main` configurable
+  - You can use `std.setMainModule` to make `import.meta.main` true within that module's code. Note, however, that it does not work retroactively; only modules loaded after the `setMainModule` call will be affected. To defer module load, use `import()`, `std.importModule`, or `require`.
+  - You can use `std.isMainModule` to check if a given module would be the main module without loading it.
 - Adds the global object `Module`.
   - `instanceof Module` can be used to identify module namespace objects.
   - You can specify additional implicit import specifier extensions by adding to the `Module.searchExtensions` array.

package/build/dts/quickjs-libc.d.ts

@@ -129,54 +129,42 @@ declare interface FILE {
 
 declare module "quickjs:std" {
   /**
-   * Exit the process with the provided status code.
+   * Set the exit code that the process should exit with in the future, if it
+   * exits normally.
    *
-   * @param statusCode The exit code; 0 for success, nonzero for failure.
-   */
-  export function exit(statusCode: number): void;
-
-  /**
-   * Evaluate the string `code` as a script (global eval).
+   * Can only be called from the main thread.
    *
-   * @param code - The code to evaluate.
-   * @param options - An optional object containing the following optional properties:
-   * @property backtraceBarrier - Boolean (default = false). If true, error backtraces do not list the stack frames below the evalScript.
-   * @property filename - String (default = "<evalScript>"). The filename to associate with the code being executed.
-   * @returns The result of the evaluation.
-   */
-  export function evalScript(
-    code: string,
-    options?: { backtraceBarrier?: boolean; filename?: string }
-  ): any;
-
-  /**
-   * Evaluate the file `filename` as a script (global eval).
+   * This exit code will only be used if the process exits "normally", ie, when
+   * there are no more pending JS tasks/listeners. If an unhandled exception is
+   * thrown, the process will always exit with status `1`, regardless of the
+   * status code passed to `setExitCode`. If someone calls {@link exit} and
+   * passes in a status code, that status code will take precedence over the
+   * status code passed to `setExitCode`.
    *
-   * @param filename - The relative or absolute path to the file to load. Relative paths are resolved relative to the process's current working directory.
-   * @returns The result of the evaluation.
+   * @param statusCode The future exit code; 0 for success, nonzero for failure.
    */
-  export function loadScript(filename: string): any;
+  export function setExitCode(statusCode: number): void;
 
   /**
-   * Evaluate the file `filename` as a module. Effectively a synchronous dynamic `import()`.
+   * Return the exit code that was previously set by {@link setExitCode}, or 0 if
+   * it hasn't yet been set.
    *
-   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
-   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
-   * @returns The result of the evaluation (module namespace object).
+   * Can only be called from the main thread.
    */
-  export function importModule(
-    filename: string,
-    basename?: string
-  ): { [key: string]: any };
+  export function getExitCode(): number;
 
   /**
-   * Return the resolved path to a module.
+   * Exit the process with the provided status code.
+   *
+   * Can only be called from the main thread.
+   *
+   * If `statusCode` is not provided, a value previously passed into
+   * {@link setExitCode} will be used. If no value was previously passed into
+   * setExitCode, `0` will be used.
    *
-   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
-   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
-   * @returns The resolved module path.
+   * @param statusCode The exit code; 0 for success, nonzero for failure.
    */
-  export function resolveModule(filename: string, basename?: string): string;
+  export function exit(statusCode?: number): never;
 
   /**
    * Load the file `filename` and return it as a string assuming UTF-8 encoding.
@@ -185,15 +173,6 @@ declare module "quickjs:std" {
    */
   export function loadFile(filename: string): string;
 
-  /**
-   * Read the script of module filename from an active stack frame, then return it as a string.
-   *
-   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
-   *
-   * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
-   */
-  export function getFileNameFromStack(stackLevels?: number): string;
-
   /**
    * Return a boolean indicating whether the provided value is a FILE object.
    *

package/build/dts/quickjs-libcontext.d.ts

@@ -44,6 +44,10 @@ declare module "quickjs:context" {
      * - Symbol
      * - eval (but it doesn't work unless the `eval` option is enabled)
      * - globalThis
+     *
+     * Note that new contexts don't have a `scriptArgs` global. If you need one
+     * to be present in the new context, you can add one onto the Context's
+     * `globalThis` property.
      */
     constructor(options?: {
       /** Enables `Date`. Defaults to `true` */
@@ -55,6 +59,9 @@ declare module "quickjs:context" {
       /** Enables `String.prototype.normalize`. Defaults to `true`. */
       stringNormalize?: boolean;
 
+      /** Enables `String.dedent`. Defaults to `true`. */
+      stringDedent?: boolean;
+
       /** Enables `RegExp`. Defaults to `true`. */
       regExp?: boolean;
 
@@ -121,32 +128,22 @@ declare module "quickjs:context" {
        */
       operators?: boolean;
 
-      /** Enables "use math". Defaults to `true`. */
+      /** Enables `"use math"`. Defaults to `true`. */
       useMath?: boolean;
 
+      /** Enables `inspect`. Defaults to `true`. */
+      inspect?: boolean;
+      /** Enables `console`. Defaults to `true`. */
+      console?: boolean;
+      /** Enables `print`. Defaults to `true`. */
+      print?: boolean;
+      /** Enables `require` and `Module`. Defaults to `true`. */
+      moduleGlobals?: boolean;
       /**
-       * Enables:
-       *
-       * - inspect
-       * - console
-       * - print
-       * - require (and require.resolve)
-       * - setTimeout
-       * - clearTimeout
-       * - setInterval
-       * - clearInterval
-       * - String.cooked
-       * - String.dedent
-       *
-       * Defaults to `true`.
-       *
-       * NOTE: The following globals, normally part of `js_std_add_helpers`, are NEVER added:
-       *
-       * - scriptArgs
-       *
-       * If you need them in the new context, copy them over from your context's globalThis onto the child context's globalThis.
+       * Enables `setTimeout`, `clearTimeout`, `setInterval`, and
+       * `clearInterval`. Defaults to `true`.
        */
-      stdHelpers?: boolean;
+      timers?: boolean;
 
       /** Enable builtin modules. */
       modules?: {
@@ -158,6 +155,8 @@ declare module "quickjs:context" {
         "quickjs:bytecode"?: boolean;
         /** Enables the "quickjs:context" module. Defaults to `true`. */
         "quickjs:context"?: boolean;
+        /** Enables the "quickjs:module" module. Defaults to `true`. */
+        "quickjs:module"?: boolean;
       };
     });
 

package/build/dts/quickjs-libmodule.d.ts

@@ -0,0 +1,72 @@
+declare module "quickjs:module" {
+  /**
+   * Return whether the provided resolved module path is set as the main module.
+   *
+   * In other words, return what the value of `import.meta.main` would be within
+   * the module.
+   *
+   * The main module can be set via {@link setMainModule}.
+   */
+  export function isMainModule(resolvedFilepath: string): boolean;
+
+  /**
+   * Set the main module to the module with the provided resolved path.
+   *
+   * This will affect the value of `import.meta.main` for modules loaded in the
+   * future, but it will NOT retroactively change the value of
+   * `import.meta.main` in existing already-loaded modules.
+   */
+  export function setMainModule(resolvedFilepath: string): void;
+
+  /**
+   * Evaluate the string `code` as a script (global eval).
+   *
+   * @param code - The code to evaluate.
+   * @param options - An optional object containing the following optional properties:
+   * @property backtraceBarrier - Boolean (default = false). If true, error backtraces do not list the stack frames below the evalScript.
+   * @property filename - String (default = "<evalScript>"). The filename to associate with the code being executed.
+   * @returns The result of the evaluation.
+   */
+  export function evalScript(
+    code: string,
+    options?: { backtraceBarrier?: boolean; filename?: string }
+  ): any;
+
+  /**
+   * Evaluate the file `filename` as a script (global eval).
+   *
+   * @param filename - The relative or absolute path to the file to load. Relative paths are resolved relative to the process's current working directory.
+   * @returns The result of the evaluation.
+   */
+  export function runScript(filename: string): any;
+
+  /**
+   * Evaluate the file `filename` as a module. Effectively a synchronous dynamic `import()`.
+   *
+   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
+   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
+   * @returns The result of the evaluation (module namespace object).
+   */
+  export function importModule(
+    filename: string,
+    basename?: string
+  ): { [key: string]: any };
+
+  /**
+   * Return the resolved path to a module.
+   *
+   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
+   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
+   * @returns The resolved module path.
+   */
+  export function resolveModule(filename: string, basename?: string): string;
+
+  /**
+   * Read the script of module filename from an active stack frame, then return it as a string.
+   *
+   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
+   *
+   * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
+   */
+  export function getFileNameFromStack(stackLevels?: number): string;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@suchipi/quickjs",
   "description": "Suchipi's QuickJS Fork",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "main": "./npm/index.js",
   "bin": {
     "qjs": "npm/cli/qjs.js",