@suchipi/quickjs 0.2.1 → 0.3.0

package/LICENSE

@@ -2,7 +2,7 @@ QuickJS Javascript Engine
 
 Copyright (c) 2017-2021 Fabrice Bellard
 Copyright (c) 2017-2021 Charlie Gordon
-Copyright (c) 2022-2022 Lily Skye
+Copyright (c) 2022-2023 Lily Skye
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,11 +5,12 @@ Fork of the fantastic QuickJS engine by Fabrice Bellard, with the following chan
 ## Changes to `quickjs`:
 
 - A TypeScript `.d.ts` file is provided for all QuickJS-specific APIs (operator overloading APIs, BigInt extensions, BigFloat, BigDecimal, etc).
-- `Object.toPrimitive` is now available (static method that invokes ToPrimitive on the given value, using the optionally-provided hint).
-- `Object.isPrimitive` is now available (static method that returns a boolean indicating whether the given value is a primitive).
-- `Symbol.typeofValue` can be used to override the result of using the `typeof` operator on an object. However, you can only use it to return a different one of the builtin values `typeof` would normally return: `"object"`, `"boolean"`, `"number"`, etc.
+- Non-standard `Object.toPrimitive` added (static method that invokes ToPrimitive on the given value, using the optionally-provided hint).
+- Non-standard `Object.isPrimitive` added (static method that returns a boolean indicating whether the given value is a primitive).
+- Non-standard `Symbol.typeofValue` has been added which can be used to override the result of using the `typeof` operator on an object. However, you can only use it to return a different one of the builtin values `typeof` would normally return: `"object"`, `"boolean"`, `"number"`, etc.
 - Added support for Error constructor "cause" option (from ES2022).
 - Added support for relative indexing method `.at()` (from ES2022).
+- `String.cooked` added (no-op template tag, like the proposed [String.cooked](https://github.com/tc39/proposal-string-cooked)).
 - Added function `JS_EvalThis_Privileged`, which allows C code to run eval in Contexts that have eval disabled. With this, you can disable eval in a context for security purposes, but can still execute trusted code within it.
 - Additional functions are exposed that allow importing modules synchronously or asynchronously:
   - `JS_DynamicImportAsync`
@@ -29,26 +30,8 @@ Fork of the fantastic QuickJS engine by Fabrice Bellard, with the following chan
 - APIs in `std` and `os` no longer return errno anywhere; instead, Error objects are thrown. `errno` is available as a property on the thrown Error objects.
 - In places where APIs in `std` or `os` would return null on failure, now an error will be thrown instead.
 - Error messages from `std` and `os` include information in the message such as the path to the file that couldn't be loaded. This info is also available as properties on the Error object.
-- `.js` extensions can now be omitted from import specifiers; they're optional.
-- If your import specifier points to a folder, it will attempt to load `index.js` from that folder.
-
-## Additions to `quickjs-libc`:
-
-- A TypeScript `.d.ts` file is provided for all APIs (globals as well as stuff from `std`/`os`).
-- Synchronous import functions added (`require`, or the more flexible `std.importModule`).
-  - Both of these functions provide the same module record object you would get via dynamic (async) import.
-  - The `require` function is not fully CommonJS-compliant; for instance, `require.main` is not present.
-- Module resolution functions added (`require.resolve`, or `std.resolveModule`).
+- A TypeScript `.d.ts` file is now provided for all APIs (globals as well as stuff from `std`/`os`).
 - A builtin global function `inspect` is added, which pretty-prints any JS value as a string.
-- A builtin global object `Module` is added.
-  - `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.
-  - You can transform any file prior to evaluating it as a module by adding a function to the `Module.compilers` object. Useful for compile-to-ts languages like TypeScript, Coffeescript, etc.
-  - You can define custom builtin modules using the `Module.define` function.
-  - You can override module name normalization (aka module resolution) by replacing the `Module.resolve` function.
-    - Note that you must handle `Module.searchExtensions` yourself in your replacement implementation.
-  - You can override the method used to load modules by replacing the `Module.read` function.
-    - Note that you must handle `Module.compilers` yourself in your replacement implementation.
 - `os.access` function added (wrapper for libc `access`).
 - `FILE.prototype.sync` method added (wrapper for `fsync`).
 - `FILE.prototype.setvbuf` method added (wrapper for `setvbuf`).
@@ -56,12 +39,16 @@ Fork of the fantastic QuickJS engine by Fabrice Bellard, with the following chan
 - `os.{WUNTRACED,WEXITSTATUS,WTERMSIG,WSTOPSIG,WIFEXITED,WIFSIGNALED,WIFSTOPPED,WIFCONTINUED}` added, for working with `os.waitpid`.
 - `os.{S_IRWXU,S_IRUSR,S_IWUSR,S_IXUSR,S_IRWXG,S_IRGRP,S_IWGRP,S_IXGRP,S_IRWXO,S_IROTH,S_IWOTH,S_IXOTH}` added, for working with file modes.
 - `"b"` mode flag is now allowed in `std.fdopen`.
-- `std.strftime` is now available (wrapper for libc `strftime`).
-- `setTimeout` and `clearTimeout` are now available as globals.
-- `setInterval` and `clearInterval` are now available as globals.
-- `String.cooked` is now available (no-op template tag, like the proposed [String.cooked](https://github.com/tc39/proposal-string-cooked)).
-- `String.dedent` is now available (template tag function, like the proposed [String.dedent](https://github.com/tc39/proposal-string-dedent)).
+- `std.strftime` added (wrapper for libc `strftime`).
 - Added `std.getuid`, `std.geteuid`, `std.getgid`, and `std.getegid` (wrappers for the libc functions of the same names).
+- Most module-loading-related code was moved into `quickjs-modulesys`.
+- Synchronous import function added (`std.importModule`), which provides the same module record object you would get via dynamic (async) import.
+- JS api for using the engine's configured module name normalization function was added (`std.resolveModule`).
+- `setTimeout` and `clearTimeout` are now available as globals (previously they were only available as exports).
+- `setInterval` and `clearInterval` are added, available as globals.
+- `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.
 
 ## Changes to the `qjs` repl:
 
@@ -104,20 +91,52 @@ A barebones Module that exports a JS class which can be used to represent an opa
 
 ## New library: `quickjs-utils`
 
-Helper structs, functions, and macros that make it easier to work with QuickJS objects in C code.
+Helper structs, functions, and macros that make it easier to work with QuickJS in C code.
+
+- APIs for looping over every property in a JSValue
+- Helper function for loading a file from disk into char a buffer
+- Helper functions for printing JS errors to stderr
+
+## New library: `quickjs-modulesys`
+
+- Module-loading code in `quickjs-libc` was moved into `quickjs-modulesys`, with the following changes:
+  - `.js` extensions can now be omitted from import specifiers; they're optional.
+  - If your import specifier points to a folder, it will attempt to load `index.js` from that folder.
+- Adds the global `require`, a CommonJS-like synchronous module loading function.
+  - The `require` function is not fully CommonJS-compliant; for instance, `require.main` is not present. `require.resolve` is, though.
+- Adds `import.meta.require`
+  - 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`.
+- 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.
+  - You can transform any file prior to evaluating it as a module by adding a function to the `Module.compilers` object. Useful for compile-to-ts languages like TypeScript, Coffeescript, etc.
+  - You can define custom builtin modules using the `Module.define` function.
+  - You can override module name normalization (aka module resolution) by replacing the `Module.resolve` function.
+    - Note that you must handle `Module.searchExtensions` yourself in your replacement implementation.
+  - You can override the method used to load modules by replacing the `Module.read` function.
+    - Note that you must handle `Module.compilers` yourself in your replacement implementation.
+- The `eval_*` functions that were duplicated in each of the programs (`eval_buf`, `eval_file`, and `eval_binary`) were moved here
+- The default module loader function from quickjs-libc was moved here and augmented to support the features related to the `Module` global as mentioned above
+- When using `require` to load a module which contains an export named `__cjsExports`, the value of the `__cjsExports` property will be returned from `require` instead of the usual module namespace object. This can be leveraged by user-defined properties on `Module` to add some CommonJS <-> ESM interop. Note, however, that dynamic import and `std.importModule` always receive the usual module namespace object.
 
 ## Changes to project organization
 
 - Stuff is reorganized into separate folders under `src`.
 - Ninja is used instead of make. Ninja build config is generated via `.ninja.js` files which get loaded into [@suchipi/shinobi](https://github.com/suchipi/shinobi).
-- macOS binaries are now cross-compiled from Linux
-- we now compile ARM macOS binaries as well
-  - These should work on both M1/M2/etc macbooks as well as on jailbroken iPhones/iPads
-- we compile aarch64 (arm 64) binaries for linux, too
-  - these are statically linked, so should work on a raspi/etc, in theory. maybe android, too
 - Line endings have been made consistent and trailing whitespace has been removed
-- FreeBSD support added (but there's no cross-compilation set up, so you'll have to compile it yourself from a FreeBSD machine).
-- I'm in the process of converting the tests to a new format (which gets run by jest). But I haven't touched most of the old tests yet.
+- The tests are authored in a new format which leverages jest snapshot testing.
+
+## More target OSes/runtimes
+
+We now include support for more platforms, and cross-compilation scripts to build most of those platforms from any platform where Docker is available.
+
+See the `meta/ninja/envs` folder to see all the supported platforms. The `host` folder represents the machine where compilation is taking place, and the `target` folder represents the target platform for the output binaries.
+
+## Library Archives
+
+We create `.a` files containing all of quickjs as part of the build.
 
 ## Other changes
 
@@ -125,9 +144,19 @@ There are also probably some other miscellaneous changes I forgot to write down
 
 # Compiling
 
-The repo has stuff set up to compile quickjs binaries for Linux, macOS, iOS, FreeBSD, or Windows.
+The repo has stuff set up to compile quickjs binaries for:
 
-QuickJS itself has no external dependencies outside this repo except pthreads, and all of the code is C99. As such, it shouldn't be too difficult to get it compiling on other Unix-like OSes. OS-specific configuration is done by way of config files found in the `meta/ninja/env` folder.
+- Linux (amd64 and aarch64)
+  - glibc
+  - musl
+  - statically-linked
+- macOS/iOS (x86_64 and arm64)
+- Windows (x86_64)
+- FreeBSD (cross-compilation not supported; you need to compile from a FreeBSD host)
+- Cosmopolitan Libc (cross-platform `*.com` binaries). You need the cosmo toolchain installed for this one to work.
+- any arbitrary unix-like OS, if you set env vars for CC, CFLAGS, etc.
+
+QuickJS itself has no external dependencies outside this repo except pthreads, and all of the code is C99. As such, it shouldn't be too difficult to get it compiling on other Unix-like OSes.
 
 Linux, macOS, iOS, and Windows binaries can be compiled using Docker. Or, you can compile binaries for just your own unix system, without using Docker.
 
@@ -150,7 +179,3 @@ Or, to compile binaries for just your own unix system:
 - Build artifacts will be placed in the `build` folder. You're probably most interested in stuff in the `build/bin` and `build/lib` folders.
 
 If you are targeting an unsupported OS or would like to use a different compiler, set the environment variables `HOST` and `TARGET` both to "other", and then set the environment variables `CC`, `AR`, `CFLAGS`, and `LDFLAGS` as you see fit. There are some other variables you can set as well; see `meta/ninja/envs/target/other.ninja.js` and `meta/ninja/envs/host/other.ninja.js` for a list.
-
-## Notes
-
-The old tests for std and os aren't working right now; I really haven't touched them yet, so they're still expecting the old function signatures (returning errno, etc).

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

@@ -1149,153 +1149,6 @@ declare interface InspectFunction {
  */
 declare var inspect: InspectFunction;
 
-/**
- * A global which lets you configure the module loader (import/export/require).
- * You can use these properties to add support for importing new filetypes.
- *
- * This global can also be used to identify whether an object is a module
- * namespace record.
- */
-interface ModuleGlobal {
-  /**
-   * Returns true if `target` is a module namespace object.
-   */
-  [Symbol.hasInstance](target: any): target is {
-    [key: string | number | symbol]: any;
-  };
-
-  /**
-   * A list of filetype extensions that may be omitted from an import specifier
-   * string.
-   *
-   * Defaults to `[".js"]`. You can add more strings to this array to
-   * make the engine search for additional files when resolving a
-   * require/import.
-   *
-   * See the doc comment on {@link require} for more information.
-   *
-   * NOTE: If you add a new extension to this array, you will likely also want
-   * to add to {@link Module.compilers}.
-   */
-  searchExtensions: Array<string>;
-
-  /**
-   * User-defined functions which will handle getting the JavaScript code
-   * associated with a module.
-   *
-   * The key for each property in this object should be a file extension
-   * string with a leading dot, eg `".jsx"`. The value for each property should
-   * be a function which receives (1) the filepath to a module, and (2) that
-   * file's content as a UTF-8 string, and the function should return a string
-   * containing JavaScript code that corresponds to that module. In most cases,
-   * these functions will compile the contents of the file from one format into JavaScript.
-   *
-   * The function does not have to use the second 'content' argument it
-   * receives (ie. when loading binary files).
-   *
-   * By adding to this object, you can make it possible to import non-js
-   * filetypes; compile-to-JS languages like JSX, TypeScript, and CoffeeScript
-   * can be compiled at import time, and asset files like .txt files or .png
-   * files can be converted into an appropriate data structure at import time.
-   *
-   * As an example, to make it possible to import .txt files, you might do:
-   * ```js
-   * import * as std from "std";
-   *
-   * Module.compilers[".txt"] = (filename, content) => {
-   *   return `export default ${JSON.stringify(content)}`;
-   * }
-   * ```
-   * (leveraging `JSON.stringify`'s ability to escape quotes).
-   *
-   * Then, later in your code, you can do:
-   * ```js
-   * import names from "./names.txt";
-   * ```
-   *
-   * And `names` will be a string containing the contents of names.txt.
-   *
-   * NOTE: When adding to this object, you may also wish to add to
-   * {@link Module.searchExtensions}.
-   */
-  compilers: {
-    [extensionWithDot: string]: (filename: string, content: string) => string;
-  };
-
-  /**
-   * Create a virtual built-in module whose exports consist of the own
-   * enumerable properties of `obj`.
-   */
-  define(name: string, obj: { [key: string]: any }): void;
-
-  /**
-   * Resolves a require/import request from `fromFile` into a canonicalized path.
-   *
-   * To change native module resolution behavior, replace this function with
-   * your own implementation. Note that you must handle
-   * `Module.searchExtensions` yourself in your replacement implementation.
-   */
-  resolve(name: string, fromFile: string): string;
-
-  /**
-   * Reads the contents of the given resolved module name into a string.
-   *
-   * To change native module loading behavior, replace this function with your
-   * own implementation. Note that you must handle `Module.compilers` yourself
-   * in your replacement implementation.
-   */
-  read(modulePath: string): string;
-}
-
-declare var Module: ModuleGlobal;
-
-interface RequireFunction {
-  /**
-   * Synchronously import a module.
-   *
-   * `source` will be resolved relative to the calling file.
-   *
-   * If `source` does not have a file extension, and a file without an extension
-   * cannot be found, the engine will check for files with the extensions in
-   * {@link Module.searchExtensions}, and use one of those if present. This
-   * behavior also happens when using normal `import` statements.
-   *
-   * For example, if you write:
-   *
-   * ```js
-   * import something from "./somewhere";
-   * ```
-   *
-   * but there's no file named `somewhere` in the same directory as the file
-   * where that import appears, and `Module.searchExtensions` is the default
-   * value:
-   *
-   * ```js
-   * [".js"]
-   * ```
-   *
-   * then the engine will look for `somewhere.js`. If that doesn't exist, the
-   * engine will look for `somewhere/index.js`. If *that* doesn't exist, an error
-   * will be thrown.
-   *
-   * If you add more extensions to `Module.searchExtensions`, then the engine
-   * will use those, too. It will search in the same order as the strings appear
-   * in the `Module.searchExtensions` array.
-   */
-  (source: string): any;
-
-  /**
-   * Resolves the normalized path to a modules, relative to the calling file.
-   */
-  resolve: (source: string) => string;
-}
-
-declare var require: RequireFunction;
-
-interface ImportMeta {
-  require: RequireFunction;
-}
-
 declare var setTimeout: typeof import("quickjs:os").setTimeout;
 declare var clearTimeout: typeof import("quickjs:os").clearTimeout;
 
@@ -1305,16 +1158,6 @@ declare function setInterval(func: (...args: any) => any, ms: number): Interval;
 declare function clearInterval(interval: Interval): void;
 
 interface StringConstructor {
-  /**
-   * A no-op template literal tag.
-   *
-   * https://github.com/tc39/proposal-string-cooked
-   */
-  cooked(
-    strings: readonly string[] | ArrayLike<string>,
-    ...substitutions: any[]
-  ): string;
-
   /**
    * Remove leading minimum indentation from the string.
    * The first line of the string must be empty.

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

@@ -142,7 +142,6 @@ declare module "quickjs:context" {
        *
        * NOTE: The following globals, normally part of `js_std_add_helpers`, are NEVER added:
        *
-       * - Module
        * - scriptArgs
        *
        * If you need them in the new context, copy them over from your context's globalThis onto the child context's globalThis.

package/build/dts/quickjs.d.ts

@@ -19,6 +19,18 @@ interface ObjectConstructor {
   isPrimitive(input: any): boolean;
 }
 
+interface StringConstructor {
+  /**
+   * A no-op template literal tag.
+   *
+   * https://github.com/tc39/proposal-string-cooked
+   */
+  cooked(
+    strings: readonly string[] | ArrayLike<string>,
+    ...substitutions: any[]
+  ): string;
+}
+
 interface SymbolConstructor {
   /**
    * A method that changes the result of using the `typeof` operator on the

package/package.json

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

package/tsconfig.json

@@ -18,7 +18,7 @@
     "allowJs": true,
     "checkJs": true,
     "noEmit": true,
-    "lib": ["ES2020"],
+    "lib": ["ES2021"],
     "module": "ES2020",
     "moduleResolution": "node",
     "strictNullChecks": true,