QuickJS-NG

https://quickjs-ng.github.io/quickjs
Admin
QuickJS-NG is a small and embeddable JavaScript engine that aims to support the latest ECMAScript...
Tokens:14,943
Snippets:179
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install QuickJS from Source

Source: https://quickjs-ng.github.io/quickjs/installation

After building QuickJS from source, run 'make install' to install it on your system. The default installation path is /usr/local.

```bash
make install
```

--------------------------------

### Compile QuickJS with Make

Source: https://quickjs-ng.github.io/quickjs/building

This command builds the default executables like `qjs` and `qjsc`, along with test tools. Ensure you have the necessary build tools installed.

```bash
make
```

--------------------------------

### Install jsvu Package Manager

Source: https://quickjs-ng.github.io/quickjs/installation

To install QuickJS using jsvu, first install the jsvu package globally using npm. This command is applicable for versions 2.2.0 and later.

```bash
npm install jsvu -g
```

--------------------------------

### Get Platform Information

Source: https://quickjs-ng.github.io/quickjs/stdlib

Returns a string indicating the current operating system platform.

```javascript
platform
```

--------------------------------

### Get All Environment Variables

Source: https://quickjs-ng.github.io/quickjs/stdlib

Returns an object containing all environment variables as key-value pairs.

```javascript
const envVars = std.getenviron();

```

--------------------------------

### Get Environment Variable

Source: https://quickjs-ng.github.io/quickjs/stdlib

Retrieves the value of an environment variable.

```javascript
std.getenv("PATH");

```

--------------------------------

### Get File Status

Source: https://quickjs-ng.github.io/quickjs/stdlib

Retrieves file status information. Use `lstat` for symbolic links.

```javascript
stat(path)
lstat(path)
```

--------------------------------

### Get Error Description

Source: https://quickjs-ng.github.io/quickjs/stdlib

Returns a string describing a given error number.

```javascript
std.strerror(std.Error.EINVAL);

```

--------------------------------

### Get or set opaque data for an object

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

Retrieve or assign C opaque data to a JavaScript object using JS_GetOpaque and JS_SetOpaque. This allows binding C data structures to JS objects.

```c
void *JS_GetOpaque(JSValueConst obj, JSClassID class_id);
```

```c
void JS_SetOpaque(JSValue obj, void *opaque);
```

--------------------------------

### QuickJS Tools Overview

Source: https://quickjs-ng.github.io/quickjs/cli

Introduction to the primary tools provided by QuickJS: the JavaScript interpreter 'qjs' and the JavaScript compiler 'qjsc'.

```markdown
* `qjs` - The QuickJS JavaScript interpreter
  * Creating standalone executables
* `qjsc` - The QuickJS JavaScript compiler
```

--------------------------------

### Compile C file with QuickJS

Source: https://quickjs-ng.github.io/quickjs/cli

Compile a C file (e.g., hello.c) along with QuickJS source files to create a standalone executable. Ensure you are in the QuickJS source directory.

```bash
cc hello.c dtoa.c libregexp.c libunicode.c quickjs.c quickjs-libc.c -I. -o hello
```

--------------------------------

### Execute Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Launches a new process. Options control blocking behavior, path searching, working directory, I/O redirection, environment variables, and user/group IDs.

```javascript
exec(args[, options])
```

--------------------------------

### Clone QuickJS Repository

Source: https://quickjs-ng.github.io/quickjs/building

Use this command to download the QuickJS source code from GitHub.

```bash
git clone https://github.com/quickjs-ng/quickjs.git
cd quickjs
```

--------------------------------

### Signal Handling

Source: https://quickjs-ng.github.io/quickjs/stdlib

Sets up signal handlers.

```APIDOC
## `signal(signal, func)`

### Description
Call the function `func` when the signal `signal` happens. Only a single handler per signal number is supported. Use `null` to set the default handler or `undefined` to ignore the signal. Signal handlers can only be defined in the main thread.

### Supported Signals
- `SIGINT`
- `SIGABRT`
- `SIGFPE`
- `SIGILL`
- `SIGSEGV`
- `SIGTERM`

These are POSIX signal numbers.
```

--------------------------------

### Execute compiled C program

Source: https://quickjs-ng.github.io/quickjs/cli

Run the compiled 'hello' executable. The output 'Hello World' will be displayed.

```bash
./hello
```

--------------------------------

### Run Test262 Suite

Source: https://quickjs-ng.github.io/quickjs/building

Execute the test262 JavaScript conformance test suite to verify QuickJS functionality. This requires the test262 suite to be present.

```bash
make test262
```

--------------------------------

### qjsc Compiler Usage

Source: https://quickjs-ng.github.io/quickjs/cli

Displays the available command-line options for the `qjsc` JavaScript compiler. Use this to understand how to generate bytecode or C code from JavaScript files.

```bash
$ qjsc  
usage: qjsc [options] [files]  
  
options are:  
-b          output raw bytecode instead of C code  
-e          output main() and bytecode in a C file  
-o output   set the output filename  
-n script_name    set the script name (as used in stack traces)  
-N cname    set the C name of the generated data  
-m          compile as JavaScript module (default=autodetect)  
-D module_name         compile a dynamically loaded module or worker  
-M module_name[,cname] add initialization code for an external C module  
-p prefix   set the prefix of the generated C names  
-s          strip the source code, specify twice to also strip debug info  
-S n        set the maximum stack size to 'n' bytes (default=262144)  

```

--------------------------------

### qjs Interpreter Usage

Source: https://quickjs-ng.github.io/quickjs/cli

Displays the available command-line options for the `qjs` interpreter. Use this to understand how to execute scripts, enter interactive mode, or compile files.

```bash
$ qjs  
usage: qjs [options] [file [args]]  
-h  --help         list options  
-e  --eval EXPR    evaluate EXPR  
-i  --interactive  go to interactive mode  
-m  --module       load as ES6 module (default=autodetect)  
    --script       load as ES6 script (default=autodetect)  
-I  --include file include an additional file  
    --std          make 'std', 'os' and 'bjson' available to script  
-T  --trace        trace memory allocation  
-d  --dump         dump the memory usage stats  
-D  --dump-flags   flags for dumping debug data (see DUMP_* defines)  
-c  --compile FILE compile the given JS file as a standalone executable  
-o  --out FILE     output file for standalone executables  
    --exe          select the executable to use as the base, defaults to the current one  
    --memory-limit n       limit the memory usage to 'n' Kbytes  
    --stack-size n         limit the stack size to 'n' Kbytes  
    --unhandled-rejection  dump unhandled promise rejections  
-q  --quit         just instantiate the interpreter and quit  

```

--------------------------------

### qjs:std Module

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides wrappers to libc (stdlib.h and stdio.h) and other utilities.

```APIDOC
## `qjs:std` Module

The `std` module provides wrappers to libc (`stdlib.h` and `stdio.h`) and a few other utilities.

### `exit(n)`

#### Description
Exit the process.

#### Parameters
- **n** (number) - Required - The exit code.

### `evalScript(str, options = undefined)`

#### Description
Evaluate the string `str` as a script (global eval).

#### Parameters
- **str** (string) - Required - The script string to evaluate.
- **options** (object) - Optional - Options for script evaluation.
  - **backtrace_barrier** (boolean) - Optional - If true, error backtraces do not list the stack frames below the evalScript.
  - **async** (boolean) - Optional - If true, `await` is accepted in the script and a promise is returned. The promise is resolved with an object whose `value` property holds the value returned by the script.

### `loadScript(filename)`

#### Description
Evaluate the file `filename` as a script (global eval).

#### Parameters
- **filename** (string) - Required - The path to the script file.

### `loadFile(filename, [options])`

#### Description
Load the file `filename` and return it as a string assuming UTF-8 encoding. Return `null` in case of I/O error.

#### Parameters
- **filename** (string) - Required - The path to the file to load.
- **options** (object) - Optional - Options for loading the file.
  - **binary** (boolean) - Optional - If true, returns a `Uint8Array` instead of a string.

### `writeFile(filename, data)`

#### Description
Create the file `filename` and write `data` into it. Throws an exception if the file cannot be created or written to.

#### Parameters
- **filename** (string) - Required - The path to the file to write.
- **data** (string | TypedArray | ArrayBuffer) - Required - The data to write to the file.

### `open(filename, flags, errorObj = undefined)`

#### Description
Open a file (wrapper to the libc `fopen()`). Return the FILE object or `null` in case of I/O error. If `errorObj` is not undefined, set its `errno` property to the error code or to 0 if no error occurred.

#### Parameters
- **filename** (string) - Required - The name of the file to open.
- **flags** (string) - Required - The file opening flags.
- **errorObj** (object) - Optional - An object to store error information.

### `popen(command, flags, errorObj = undefined)`

#### Description
Open a process by creating a pipe (wrapper to the libc `popen()`). Return the FILE object or `null` in case of I/O error. If `errorObj` is not undefined, set its `errno` property to the error code or to 0 if no error occurred.

#### Parameters
- **command** (string) - Required - The command to execute.
- **flags** (string) - Required - The file opening flags.
- **errorObj** (object) - Optional - An object to store error information.

### `fdopen(fd, flags, errorObj = undefined)`

#### Description
Open a file from a file handle (wrapper to the libc `fdopen()`). Return the FILE object or null`in case of I/O error. If`errorObj`is not undefined, set its`errno`property to the error code or to 0 if no error occurred.

#### Parameters
- **fd** (number) - Required - The file descriptor.
- **flags** (string) - Required - The file opening flags.
- **errorObj** (object) - Optional - An object to store error information.

### `tmpfile(errorObj = undefined)`

#### Description
Open a temporary file. Return the FILE object or `null` in case of I/O error. If `errorObj` is not undefined, set its `errno` property to the error code or to 0 if no error occurred.

#### Parameters
- **errorObj** (object) - Optional - An object to store error information.

### `puts(str)`

#### Description
Equivalent to `std.out.puts(str)`.

#### Parameters
- **str** (string) - Required - The string to print.

### `printf(fmt, ...args)`

#### Description
Equivalent to `std.out.printf(fmt, ...args)`.

#### Parameters
- **fmt** (string) - Required - The format string.
- **...args** (any) - Optional - Arguments for the format string.

### `sprintf(fmt, ...args)`

#### Description
Equivalent to the libc sprintf().

#### Parameters
- **fmt** (string) - Required - The format string.
- **...args** (any) - Optional - Arguments for the format string.

### `in`, `out`, `err`

#### Description
Wrappers to the libc file `stdin`, `stdout`, `stderr`.

### `Error`

#### Description
Enumeration object containing the integer value of common errors (additional error codes may be defined).

#### Properties
- **EINVAL** (number)
- **EIO** (number)
- **EACCES** (number)
- **EEXIST** (number)
- **ENOSPC** (number)
- **ENOSYS** (number)
- **EBUSY** (number)
- **ENOENT** (number)
- **EPERM** (number)
- **EPIPE** (number)

### `strerror(errno)`

#### Description
Return a string that describes the error `errno`.

#### Parameters
- **errno** (number) - Required - The error number.

### `gc()`

#### Description
Manually invoke the cycle removal algorithm. The cycle removal algorithm is automatically started when needed, so this function is useful in case of specific memory constraints or for testing.

### `getenv(name)`

#### Description
Return the value of the environment variable `name` or `undefined` if it is not defined.

#### Parameters
- **name** (string) - Required - The name of the environment variable.

### `setenv(name, value)`

#### Description
Set the value of the environment variable `name` to the string `value`.

#### Parameters
- **name** (string) - Required - The name of the environment variable.
- **value** (string) - Required - The value to set.

### `unsetenv(name)`

#### Description
Delete the environment variable `name`.

#### Parameters
- **name** (string) - Required - The name of the environment variable.

### `getenviron()`

#### Description
Return an object containing the environment variables as key-value pairs.

```

--------------------------------

### Execute Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Executes a new process with specified arguments and options.

```APIDOC
## `exec(args[, options])`

### Description
Execute a process with the arguments `args`. `options` is an object containing optional parameters:

- `block` - Boolean (default = true). If true, wait until the process is terminated. In this case, `exec` returns the exit code if positive or the negated signal number if the process was interrupted by a signal. If false, do not block and return the process id of the child.
- `usePath` - Boolean (default = true). If true, the file is searched in the `PATH` environment variable.
- `file` - String (default = `args[0]`). Set the file to be executed.
- `cwd` - String. If present, set the working directory of the new process.
- `stdin`, `stdout`, `stderr` - If present, set the handle in the child for stdin, stdout or stderr.
- `env` - Object. If present, set the process environment from the object key-value pairs. Otherwise use the same environment as the current process.
- `uid` - Integer. If present, the process uid with `setuid`.
- `gid` - Integer. If present, the process gid with `setgid`.
- `groups` - Array of integer. If present, the supplementary group IDs with `setgroup`.
```

--------------------------------

### qjs:os Module - Directory and Temporary File Operations

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides functions for creating directories and temporary files.

```APIDOC
## `qjs:os` module - Directory and Temporary File Operations

### `mkdir(path, mode = 0o777)`

Create a directory at `path`. Return 0 if OK or `-errno`.

### `mkdtemp(pattern = "tmpXXXXXX")`

Create a temporary directory. `XXXXXX` must be at the end of the pattern string and is replaced with a random name. The directory is created with file mode `0o700`.
Return `[path, err]` where `path` is a string and `err` is 0 or `-errno`.
Not available on Windows and WASI.

### `mkstemp(pattern = "tmpXXXXXX")`

Create a temporary file and open it. `XXXXXX` must be at the end of the pattern string and is replaced with a random name. The file is created with file mode `0o600` and opened in read/write mode.
Return `[path, fd]` where `path` is a string and `fd` is the file descriptor or `-errno`, i.e., the error code if less than zero.
Unlike `std.tmpfile()`, the file is not automatically deleted on close.
See also `std.fdopen()`.
Not available on Windows and WASI.
```

--------------------------------

### Create Standalone Executable with qjs

Source: https://quickjs-ng.github.io/quickjs/cli

Compiles a JavaScript file (`app.js`) into a standalone executable named `app` using the `qjs` CLI. The `--exe qjs` flag specifies the base executable to use.

```bash
$ qjs -c app.js -o app --exe qjs  

```

--------------------------------

### qjs:os Module - File Access

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides functions for low-level file access operations.

```APIDOC
## `qjs:os` module - File Access

The `os` module provides Operating System specific functions:
  * low level file access
  * signals
  * timers
  * basic asynchronous I/O
  * workers (threads)

The OS functions usually return 0 if OK or an OS specific negative error code.

### `open(filename, flags, mode = 0o666)`

Open a file. Return a handle or < 0 if error.

Supported flags:
  * `O_RDONLY`
  * `O_WRONLY`
  * `O_RDWR`
  * `O_APPEND`
  * `O_CREAT`
  * `O_EXCL`
  * `O_TRUNC`

POSIX open flags.
  * `O_TEXT`

(Windows specific). Open the file in text mode. The default is binary mode.

### `close(fd)`

Close the file handle `fd`.

### `seek(fd, offset, whence)`

Seek in the file. Use `std.SEEK_*` for `whence`. `offset` is either a number or a BigInt. If `offset` is a BigInt, a BigInt is returned too.

### `read(fd, buffer, offset, length)`

Read `length` bytes from the file handle `fd` to the ArrayBuffer `buffer` at byte position `offset`. Return the number of read bytes or < 0 if error.

### `write(fd, buffer, offset, length)`

Write `length` bytes to the file handle `fd` from the ArrayBuffer `buffer` at byte position `offset`. Return the number of written bytes or < 0 if error.

### `remove(filename)`

Remove a file. Return 0 if OK or `-errno`.

### `rename(oldname, newname)`

Rename a file. Return 0 if OK or `-errno`.
```

--------------------------------

### Compile Debug Build of QuickJS

Source: https://quickjs-ng.github.io/quickjs/building

This command creates an unoptimized debug build, which is useful for development and debugging purposes. It may increase build times.

```bash
make debug
```

--------------------------------

### Global Objects and Utilities

Source: https://quickjs-ng.github.io/quickjs/stdlib

Global variables and utility functions available in the QuickJS environment.

```APIDOC
## Globals

### Description
Provides access to global variables and utility functions within the QuickJS runtime.

### Globals
- **`argv0`**: (string) The name of the executed script.
- **`scriptArgs`**: (array) An array of script arguments.
- **`print(...args)`**: Prints arguments to standard output.
- **`console.log(...args)`**: Logs arguments to the console.
- **`navigator.userAgent`**: (string) The user agent string.
- **`gc()`**: Manually triggers garbage collection.

## `qjs:bjson` Module

### Description
Provides binary JSON (bjson) serialization and deserialization capabilities.

### Methods
- **`bjson.write(obj, [flags])`**: Writes an object to bjson format.
- **`bjson.read(buf, [pos], [len], [flags])`**: Reads an object from bjson format.

## `qjs:os` Module

### Description
Provides operating system-level functionalities.

### Methods
- **`open(filename, flags, mode = 0o666)`**: Opens a file.
- **`close(fd)`**: Closes a file descriptor.
- **`seek(fd, offset, whence)`**: Seeks within a file descriptor.
- **`read(fd, buffer, offset, length)`**: Reads from a file descriptor.
- **`write(fd, buffer, offset, length)`**: Writes to a file descriptor.
- **`isatty(fd)`**: Checks if a file descriptor is a TTY.
- **`ttyGetWinSize(fd)`**: Gets TTY window size.
- **`ttySetRaw(fd)`**: Sets TTY to raw mode.
- **`remove(filename)`**: Removes a file.
- **`rename(oldname, newname)`**: Renames a file.
- **`realpath(path)`**: Resolves the real path of a file.
- **`getcwd()`**: Gets the current working directory.
- **`exePath()`**: Gets the path of the executable.
- **`chdir(path)`**: Changes the current working directory.
- **`mkdir(path, mode = 0o777)`**: Creates a directory.
- **`mkdtemp(pattern = "tmpXXXXXX")`**: Creates a temporary directory.
- **`mkstemp(pattern = "tmpXXXXXX")`**: Creates a temporary file.
- **`stat(path)` / `lstat(path)`**: Gets file status.
- **`utimes(path, atime, mtime)`**: Sets file access and modification times.
- **`symlink(target, linkpath)`**: Creates a symbolic link.
- **`readlink(path)`**: Reads a symbolic link.
- **`readdir(path)`**: Reads a directory.
- **`setReadHandler(fd, func)`**: Sets a read event handler.
- **`setWriteHandler(fd, func)`**: Sets a write event handler.
- **`signal(signal, func)`**: Sets a signal handler.
- **`kill(pid, sig)`**: Sends a signal to a process.
- **`exec(args[, options])`**: Executes a command.
- **`waitpid(pid, options)`**: Waits for a child process.
- **`dup(fd)`**: Duplicates a file descriptor.
- **`dup2(oldfd, newfd)`**: Duplicates a file descriptor to a specific one.
- **`pipe()`**: Creates a pipe.
- **`sleep(delay_ms)`**: Sleeps for a specified duration.
- **`sleepAsync(delay_ms)`**: Asynchronously sleeps for a specified duration.
- **`setTimeout(func, delay)`**: Sets a timeout.
- **`clearTimeout(id)`**: Clears a timeout.
- **`platform`**: (string) The operating system platform.
- **`Worker(module_filename)`**: Creates a worker thread.

## `qjs:std` Module

### Description
Provides standard I/O, script execution, and environment utilities.

### Methods
- **`exit(n)`**: Exits the process.
- **`evalScript(str, options = undefined)`**: Evaluates a JavaScript string.
- **`loadScript(filename)`**: Loads and executes a JavaScript file.
- **`loadFile(filename, [options])`**: Loads a file.
- **`writeFile(filename, data)`**: Writes data to a file.
- **`open(filename, flags, errorObj = undefined)`**: Opens a file.
- **`popen(command, flags, errorObj = undefined)`**: Opens a process pipe.
- **`fdopen(fd, flags, errorObj = undefined)`**: Opens a file descriptor.
- **`tmpfile(errorObj = undefined)`**: Creates a temporary file.
- **`puts(str)`**: Outputs a string.
- **`printf(fmt, ...args)`**: Formatted printing.
- **`sprintf(fmt, ...args)`**: Formatted string output.
- **`in`, `out`, `err`**: Standard input, output, and error streams.
- **`Error`**: Standard Error object.
- **`strerror(errno)`**: Returns the string description of an error number.
- **`gc()`**: Manually triggers garbage collection.
- **`getenv(name)`**: Gets an environment variable.
- **`setenv(name, value)`**: Sets an environment variable.
- **`unsetenv(name)`**: Unsets an environment variable.
- **`getenviron()`**: Gets all environment variables.
- **`urlGet(url, options = undefined)`**: Downloads a URL (see Network Utilities section).
- **`FILE`**: File object (see File Object API section).
```

--------------------------------

### Standard Output Functions

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides wrappers for standard output operations like puts and printf.

```javascript
std.puts("Hello from puts!");

```

```javascript
std.printf("Value: %d\n", 42);

```

--------------------------------

### Create and Use a Worker Thread

Source: https://quickjs-ng.github.io/quickjs/stdlib

Demonstrates the basic usage of the Worker class to create a new thread. Messages are sent using postMessage and received via the onmessage handler.

```javascript
const w = new Worker("worker.js");
w.postMessage("hello");
w.onmessage = (event) => {
  console.log("Received:", event.data);
};

```

--------------------------------

### qjs:os Module - TTY and Path Operations

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides functions for TTY manipulation and path-related operations.

```APIDOC
## `qjs:os` module - TTY and Path Operations

### `isatty(fd)`

Return `true` is `fd` is a TTY (terminal) handle.

### `ttyGetWinSize(fd)`

Return the TTY size as `[width, height]` or `null` if not available.

### `ttySetRaw(fd)`

Set the TTY in raw mode.

### `realpath(path)`

Return `[str, err]` where `str` is the canonicalized absolute pathname of `path` and `err` the error code.

### `getcwd()`

Return `[str, err]` where `str` is the current working directory and `err` the error code.

### `exePath()`

Returns the full path of the current executable or `undefined` if not available / supported.

### `chdir(path)`

Change the current directory. Return 0 if OK or `-errno`.
```

--------------------------------

### Global Objects

Source: https://quickjs-ng.github.io/quickjs/stdlib

Provides information about globally available objects and functions in the QuickJS runtime.

```APIDOC
## Globals

### `argv0`

Provides the executable path.

### `scriptArgs`

Provides the command line arguments. The first argument is the script name.

### `print(...args)`

Print the arguments separated by spaces and a trailing newline.

### `console.log(...args)`

Same as `print()`.

### `navigator.userAgent`

Returns `quickjs-ng/<version>`.

### `gc()`

Shorthand for `std.gc()`.
```

--------------------------------

### Create Symbolic Link

Source: https://quickjs-ng.github.io/quickjs/stdlib

Creates a symbolic link at `linkpath` pointing to `target`.

```javascript
symlink(target, linkpath)
```

--------------------------------

### Open File

Source: https://quickjs-ng.github.io/quickjs/stdlib

Opens a file for reading or writing. Can optionally capture errno.

```javascript
const file = std.open("input.txt", "r");

```

```javascript
const errorObj = {};
const file = std.open("input.txt", "r", errorObj);

```

--------------------------------

### Bundle JavaScript with esbuild

Source: https://quickjs-ng.github.io/quickjs/cli

Bundles and minifies a JavaScript application using `esbuild` for use with QuickJS. The `--external:qjs:*` flag ensures QuickJS-specific modules are not bundled.

```bash
npx esbuild my-app/index.js \  
    --bundle \  
    --outfile=app.js \  
    --external:qjs:* \  
    --minify \  
    --target=es2023 \  
    --platform=neutral \  
    --format=esm \  
    --main-fields=main,module  

```

--------------------------------

### Create Pipe

Source: https://quickjs-ng.github.io/quickjs/stdlib

Creates a pipe for inter-process communication, returning read and write file descriptors.

```javascript
pipe()
```

--------------------------------

### String Formatting

Source: https://quickjs-ng.github.io/quickjs/stdlib

Formats a string according to a format string and arguments, similar to C's sprintf.

```javascript
const formattedString = std.sprintf("Name: %s, Age: %d", "Alice", 30);

```

--------------------------------

### Create Pipe

Source: https://quickjs-ng.github.io/quickjs/stdlib

Creates a pipe for inter-process communication.

```APIDOC
## `pipe()`

### Description
`pipe` Unix system call. Return two handles as `[read_fd, write_fd]` or null in case of error.
```

--------------------------------

### Write Data to File

Source: https://quickjs-ng.github.io/quickjs/stdlib

Writes string or binary data to a file. Throws an exception on failure.

```javascript
std.writeFile("output.txt", "Hello, world!");

```

```javascript
const buffer = new Uint8Array([1, 2, 3]);
std.writeFile("output.bin", buffer);

```

--------------------------------

### Add functions, setters, and getters

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

JS_SetPropertyFunctionList provides a shortcut to add functions, setters, and getters to a given object. Ensure proper handling of JSValues by duplicating or freeing them as needed.

```c
int JS_SetPropertyFunctionList(JSContext *ctx, JSValue obj, const JSCFunctionListEntry *tab, int len);
```

--------------------------------

### Provide custom memory allocation functions

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

Supply custom memory allocation functions when creating a new runtime using JS_NewRuntime2. This allows for fine-grained control over memory management.

```c
JSRuntime *JS_NewRuntime2(JSMallocCallbacks *malloc_funcs, void *opaque);
```

--------------------------------

### Load and Evaluate Script File

Source: https://quickjs-ng.github.io/quickjs/stdlib

Loads and evaluates a JavaScript file as a script.

```javascript
std.loadScript("my_script.js");

```

--------------------------------

### qjs:bjson Module

Source: https://quickjs-ng.github.io/quickjs/stdlib

Documentation for the 'bjson' module, used for serializing and de-serializing JavaScript objects using QuickJS's internal format.

```APIDOC
## `qjs:bjson` module

### `bjson.write(obj, [flags])`

Serializes the given object into the QuickJS internal serialization format. Returns an ArrayBuffer with the serialized data.

Supported flags:
  * `WRITE_OBJ_BYTECODE`: allow serializing functions and modules
  * `WRITE_OBJ_REFERENCE`: allow serializing object references
  * `WRITE_OBJ_SAB`: allow serializing SharedArrayBuffer instances
  * `WRITE_OBJ_STRIP_DEBUG`: strip debugging information when serializing
  * `WRITE_OBJ_STRIP_SOURCE`: strip the source information when serializing

### `bjson.read(buf, [pos], [len], [flags])`

De-serialize the given ArrayBuffer (in QuickJS internal serialization format) back into a JavaScript value.

Supported flags:
  * `READ_OBJ_BYTECODE`: allow de-serializing functions and modules
  * `READ_OBJ_REFERENCE`: allow de-serializing object references

Security caveat: `bjson.read()` is resilient against malformed input (the wire format is checksummed) but is not designed to withstand adversarial attacks. Don't feed it untrusted input.
```

--------------------------------

### Symbolic Link Creation

Source: https://quickjs-ng.github.io/quickjs/stdlib

Creates a symbolic link.

```APIDOC
## `symlink(target, linkpath)`

### Description
Create a link at `linkpath` containing the string `target`. Return 0 if OK or `-errno`.
```

--------------------------------

### Read Directory Contents

Source: https://quickjs-ng.github.io/quickjs/stdlib

Lists the filenames within a directory. Always includes '.' and '..'.

```javascript
readdir(path)
```

--------------------------------

### Open Process Pipe

Source: https://quickjs-ng.github.io/quickjs/stdlib

Opens a pipe to a child process. Can optionally capture errno.

```javascript
const pipe = std.popen("ls -l", "r");

```

```javascript
const errorObj = {};
const pipe = std.popen("cat", "w", errorObj);

```

--------------------------------

### Open File from File Descriptor

Source: https://quickjs-ng.github.io/quickjs/stdlib

Opens a FILE object from an existing file descriptor. Can optionally capture errno.

```javascript
const file = std.fdopen(0, "r");

```

```javascript
const errorObj = {};
const file = std.fdopen(1, "w", errorObj);

```

--------------------------------

### Load File Content

Source: https://quickjs-ng.github.io/quickjs/stdlib

Loads the content of a file as a string or a Uint8Array. Returns null on I/O error.

```javascript
std.loadFile("data.txt");

```

```javascript
std.loadFile("binary_data.bin", { binary: true });

```

--------------------------------

### Open Temporary File

Source: https://quickjs-ng.github.io/quickjs/stdlib

Opens a temporary file. Can optionally capture errno.

```javascript
const tempFile = std.tmpfile();

```

```javascript
const errorObj = {};
const tempFile = std.tmpfile(errorObj);

```

--------------------------------

### Worker API

Source: https://quickjs-ng.github.io/quickjs/stdlib

Documentation for the Worker class, used for creating and managing threads in QuickJS ng.

```APIDOC
## Worker Constructor

### Description
Constructor to create a new thread (worker) with an API close to that of `WebWorkers`. `module_filename` is a string specifying the module filename which is executed in the newly created thread. Threads normally don't share any data and communicate between each other with messages. Nested workers are not supported.

### Parameters
#### Path Parameters
- **module_filename** (string) - Required - The filename of the module to execute in the new thread.

### Static Properties
- **Worker.parent** (object) - In the created worker, `Worker.parent` represents the parent worker and is used to send or receive messages.

### Instance Methods
- **postMessage(msg)**
  - **Description**: Send a message to the corresponding worker. `msg` is cloned in the destination worker using an algorithm similar to the `HTML` structured clone algorithm. `SharedArrayBuffer` are shared between workers.
  - **Parameters**:
    - **msg** (any) - Required - The message to send.

- **onmessage** (function)
  - **Description**: Getter and setter. Set a function which is called each time a message is received. The function is called with a single argument. It is an object with a `data` property containing the received message. The thread is not terminated if there is at least one non `null` `onmessage` handler.
  - **Parameters**:
    - **callback** (function) - Optional - The function to handle incoming messages.
```

--------------------------------

### Duplicate File Descriptor

Source: https://quickjs-ng.github.io/quickjs/stdlib

Creates a copy of an existing file descriptor.

```javascript
dup(fd)
```

--------------------------------

### Send Signal to Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Sends a signal to a specified process.

```APIDOC
## `kill(pid, sig)`

### Description
Send the signal `sig` to the process `pid`.
```

--------------------------------

### Register a new JavaScript class

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

Register a new class ID and JS class using JS_NewClassID and JS_NewClass. This is the first step to attaching C opaque data to JavaScript objects.

```c
int JS_NewClassID(void);
```

```c
int JS_NewClass(JSContext *ctx, int class_id, const JSClassDef *class_def);
```

--------------------------------

### Set Environment Variable

Source: https://quickjs-ng.github.io/quickjs/stdlib

Sets the value of an environment variable.

```javascript
std.setenv("MY_VAR", "my_value");

```

--------------------------------

### Platform Information

Source: https://quickjs-ng.github.io/quickjs/stdlib

Retrieves the current platform identifier.

```APIDOC
## `platform`

### Description
Return a string representing the platform: `"linux"`, `"darwin"`, `"win32"` or `"js"`.
```

--------------------------------

### Read Symbolic Link Target

Source: https://quickjs-ng.github.io/quickjs/stdlib

Retrieves the target path of a symbolic link.

```javascript
readlink(path)
```

--------------------------------

### File Object API

Source: https://quickjs-ng.github.io/quickjs/stdlib

Methods for interacting with file objects.

```APIDOC
## `FILE` Object

### Description
Represents a file object with various methods for reading, writing, and manipulating file content and state.

### Methods
#### `close()`
- **Description**: Closes the file.
- **Returns**: 0 if OK, or -errno in case of I/O error.

#### `puts(str)`
- **Description**: Outputs the string with UTF-8 encoding.
- **Parameters**:
  - **str** (string) - The string to output.
- **Returns**: Number of bytes written or an error code.

#### `printf(fmt, ...args)`
- **Description**: Formatted printf. Supports standard C library printf formats. Integer format types truncate Numbers or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to truncate to 64 bits.
- **Parameters**:
  - **fmt** (string) - The format string.
  - **...args** (any) - The arguments to format.
- **Returns**: Number of bytes written or an error code.

#### `flush()`
- **Description**: Flushes the buffered file.
- **Returns**: 0 if OK or -errno in case of I/O error.

#### `seek(offset, whence)`
- **Description**: Seeks to a given file position. `whence` can be `std.SEEK_SET`, `std.SEEK_CUR`, or `std.SEEK_END`. `offset` can be a number or a BigInt.
- **Parameters**:
  - **offset** (number | BigInt) - The offset to seek to.
  - **whence** (number) - The seek base (std.SEEK_SET, std.SEEK_CUR, std.SEEK_END).
- **Returns**: 0 if OK or -errno in case of I/O error.

#### `tell()`
- **Description**: Returns the current file position.
- **Returns**: (number) The current file position.

#### `tello()`
- **Description**: Returns the current file position as a BigInt.
- **Returns**: (BigInt) The current file position.

#### `eof()`
- **Description**: Returns true if the end of the file has been reached.
- **Returns**: (boolean) True if at end of file, false otherwise.

#### `fileno()`
- **Description**: Returns the associated OS handle.
- **Returns**: (number) The file descriptor.

#### `error()`
- **Description**: Returns true if an error has occurred.
- **Returns**: (boolean) True if an error occurred, false otherwise.

#### `clearerr()`
- **Description**: Clears the error indication for the file.

#### `read(buffer, position = 0, length = buffer.length)`
- **Description**: Reads `length` bytes from the file into the ArrayBuffer `buffer` at byte position `position`. Wrapper to the libc function `fread`.
- **Parameters**:
  - **buffer** (ArrayBuffer) - The buffer to read data into.
  - **position** (number) - Optional (default = 0) - The starting position in the buffer.
  - **length** (number) - Optional (default = buffer.length) - The number of bytes to read.
- **Returns**: Number of bytes read or an error code.

#### `write(buffer, position = 0, length = buffer.length)`
- **Description**: Writes `length` bytes to the file from the ArrayBuffer or string `buffer` at byte position `position`. Wrapper to the libc function `fwrite`.
- **Parameters**:
  - **buffer** (ArrayBuffer | string) - The buffer or string to write.
  - **position** (number) - Optional (default = 0) - The starting position in the buffer.
  - **length** (number) - Optional (default = buffer.length) - The number of bytes to write.
- **Returns**: Number of bytes written or an error code.

#### `getline()`
- **Description**: Returns the next line from the file, assuming UTF-8 encoding, excluding the trailing line feed.
- **Returns**: (string) The next line, or null if EOF.

#### `readAsArrayBuffer(max_size = undefined)`
- **Description**: Reads `max_size` bytes from the file and returns them as an ArrayBuffer. If `max_size` is not present, the file is read until its end.
- **Parameters**:
  - **max_size** (number) - Optional - The maximum number of bytes to read.
- **Returns**: (ArrayBuffer) The file content as an ArrayBuffer.

#### `readAsString(max_size = undefined)`
- **Description**: Reads `max_size` bytes from the file and returns them as a string assuming UTF-8 encoding. If `max_size` is not present, the file is read until its end.
- **Parameters**:
  - **max_size** (number) - Optional - The maximum number of bytes to read.
- **Returns**: (string) The file content as a string.

#### `getByte()`
- **Description**: Returns the next byte from the file.
- **Returns**: (number) The next byte, or -1 if EOF is reached.

#### `putByte(c)`
- **Description**: Writes one byte to the file.
- **Parameters**:
  - **c** (number) - The byte to write (0-255).
- **Returns**: 0 if OK or -errno in case of I/O error.
```

--------------------------------

### qjs Dump Flags

Source: https://quickjs-ng.github.io/quickjs/cli

Lists the supported flags for the `qjs -D` option, used for debugging and analyzing memory and bytecode. These flags control the level of detail in diagnostic output.

```text
DUMP_BYTECODE_FINAL   0x01  /* dump pass 3 final byte code */  
DUMP_BYTECODE_PASS2   0x02  /* dump pass 2 code */  
DUMP_BYTECODE_PASS1   0x04  /* dump pass 1 code */  
DUMP_BYTECODE_HEX     0x10  /* dump bytecode in hex */  
DUMP_BYTECODE_PC2LINE 0x20  /* dump line number table */  
DUMP_BYTECODE_STACK   0x40  /* dump compute_stack_size */  
DUMP_BYTECODE_STEP    0x80  /* dump executed bytecode */  
DUMP_READ_OBJECT     0x100  /* dump the marshalled objects at load time */  
DUMP_FREE            0x200  /* dump every object free */  
DUMP_GC              0x400  /* dump the occurrence of the automatic GC */  
DUMP_GC_FREE         0x800  /* dump objects freed by the GC */  
DUMP_MODULE_RESOLVE 0x1000  /* dump module resolution steps */  
DUMP_PROMISE        0x2000  /* dump promise steps */  
DUMP_LEAKS          0x4000  /* dump leaked objects and strings in JS_FreeRuntime */  
DUMP_ATOM_LEAKS     0x8000  /* dump leaked atoms in JS_FreeRuntime */  
DUMP_MEM           0x10000  /* dump memory usage in JS_FreeRuntime */  
DUMP_OBJECTS       0x20000  /* dump objects in JS_FreeRuntime */  
DUMP_ATOMS         0x40000  /* dump atoms in JS_FreeRuntime */  
DUMP_SHAPES        0x80000  /* dump shapes in JS_FreeRuntime */  

```

--------------------------------

### Network Utilities

Source: https://quickjs-ng.github.io/quickjs/stdlib

Functions for performing network requests.

```APIDOC
## `urlGet(url, options)`

### Description
Download `url` using the `curl` command line utility. `options` is an optional object containing configurable properties.

### Method
`urlGet`

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to download.

#### Query Parameters
- **options** (object) - Optional - Configuration options for the download.
  - **binary** (boolean) - Optional (default = false) - If true, the response is an ArrayBuffer instead of a string. When a string is returned, the data is assumed to be UTF-8 encoded.
  - **full** (boolean) - Optional (default = false) - If true, return an object containing `response`, `responseHeaders`, and `status`. `response` is `null` in case of protocol or network error. If `full` is false, only the response is returned if the status is between 200 and 299, otherwise `null` is returned.

### Request Example
```json
{
  "url": "https://example.com/data.json",
  "options": {
    "binary": false,
    "full": true
  }
}
```

### Response
#### Success Response (200)
- **response** (string | ArrayBuffer | object) - The content of the response, or an object with response details if `full` is true.
- **responseHeaders** (string) - The response headers (only if `full` is true).
- **status** (number) - The HTTP status code (only if `full` is true).

#### Response Example
```json
{
  "response": "{\"message\": \"Success\"}",
  "responseHeaders": "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: 25\r\n\r\n",
  "status": 200
}
```
```

--------------------------------

### Standard Streams

Source: https://quickjs-ng.github.io/quickjs/stdlib

Access to standard input, output, and error streams.

```javascript
std.in

```

```javascript
std.out

```

```javascript
std.err

```

--------------------------------

### Wait for Child Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Waits for a child process to change state.

```APIDOC
## `waitpid(pid, options)`

### Description
`waitpid` Unix system call. Return the array `[ret, status]`. `ret` contains `-errno` in case of error.

### Options
- `WNOHANG` - Constant for the `options` argument of `waitpid`.
```

--------------------------------

### Read Symbolic Link Target

Source: https://quickjs-ng.github.io/quickjs/stdlib

Reads the target of a symbolic link.

```APIDOC
## `readlink(path)`

### Description
Return `[str, err]` where `str` is the link target and `err` the error code.
```

--------------------------------

### Wait for Child Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Suspends execution until a child process changes state. Options like `WNOHANG` can be used.

```javascript
waitpid(pid, options)
```

--------------------------------

### Define a prototype for a JS class

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

Use JS_SetClassProto to define the prototype for a given class in a specific JSContext. This prototype will be used when creating new objects of that class.

```c
int JS_SetClassProto(JSContext *ctx, JSClassID class_id, JSValue obj);
```

--------------------------------

### Read Directory Contents

Source: https://quickjs-ng.github.io/quickjs/stdlib

Reads the contents of a directory.

```APIDOC
## `readdir(path)`

### Description
Return `[array, err]` where `array` is an array of strings containing the filenames of the directory `path`. `err` is the error code. `array` contains at least `.` and `..` if successful.
```

--------------------------------

### Set maximum system stack size

Source: https://quickjs-ng.github.io/quickjs/developer-guide/intro

Control the maximum system stack size for the JavaScript engine using JS_SetMaxStackSize. This is important for preventing stack overflows in deep recursion scenarios.

```c
void JS_SetMaxStackSize(JSRuntime *rt, size_t value);
```

--------------------------------

### Send Signal to Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Sends a specified POSIX signal to a process identified by its PID.

```javascript
kill(pid, sig)
```

--------------------------------

### File Status Information

Source: https://quickjs-ng.github.io/quickjs/stdlib

Retrieves file status information. `lstat` provides information about the link itself.

```APIDOC
## `stat(path)` / `lstat(path)`

### Description
Return `[obj, err]` where `obj` is an object containing the file status of `path`. `err` is the error code. The following fields are defined in `obj`: `dev`, `ino`, `mode`, `nlink`, `uid`, `gid`, `rdev`, `size`, `blocks`, `atime`, `mtime`, `ctime`. The times are specified in milliseconds since 1970. `lstat()` is the same as `stat()` excepts that it returns information about the link itself.

### Constants for Mode Interpretation
- `S_IFMT`
- `S_IFIFO`
- `S_IFCHR`
- `S_IFDIR`
- `S_IFBLK`
- `S_IFREG`
- `S_IFSOCK`
- `S_IFLNK`
- `S_ISGID`
- `S_ISUID`

These constants are used to interpret the `mode` property returned by `stat()`. They have the same value as in the C system header `sys/stat.h`.
```

--------------------------------

### Update Test262 Reports

Source: https://quickjs-ng.github.io/quickjs/building

Run the test262 suite and update the pass/error reports. This is useful after implementing new features that might affect test results.

```bash
make test262-update
```

--------------------------------

### Register Signal Handler

Source: https://quickjs-ng.github.io/quickjs/stdlib

Sets a function to be called when a specific POSIX signal is received. Only one handler per signal is supported.

```javascript
signal(signal, func)
```

--------------------------------

### Set Write Handler

Source: https://quickjs-ng.github.io/quickjs/stdlib

Registers a callback function to be executed when data can be written to a file descriptor.

```javascript
setWriteHandler(fd, func)
```

--------------------------------

### Exit Process

Source: https://quickjs-ng.github.io/quickjs/stdlib

Exits the current process with a specified exit code.

```javascript
std.exit(0);

```
Tokens:
Raw