jseption 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+jseption: TypeScript port of QuickJS
+Copyright (c) 2026 jseption contributors
+
+QuickJS Javascript Engine
+Copyright (c) 2017-2025 Fabrice Bellard
+Copyright (c) 2017-2025 Charlie Gordon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# jseption
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**jseption** is a TypeScript port of [QuickJS](https://bellard.org/quickjs/), Fabrice
+Bellard's small and complete JavaScript engine, turned into a sandboxed JavaScript engine
+that runs anywhere JavaScript runs (browsers, including workers, Bun, Node, Deno) at close
+to host speed.
+
+The front end is QuickJS: a single-pass parser that emits QuickJS bytecode, the
+`resolve_variables` / `resolve_labels` compiler passes, the same opcode set (including the
+short opcodes), and the standard library declared with `JSCFunctionListEntry`-style
+tables. The back end is new: guest values are host values whose prototype chains are
+owned by the guest (see `docs/HOST_VALUES.md`), functions are compiled from bytecode to
+host JavaScript once they are hot, with on-stack replacement of running loops (see
+`docs/JIT.md`), and hot builtins forward
+to the host's natives behind guest-prototyped wrappers. The `JS_CallInternal` interpreter
+remains as the fallback tier for generators, async functions, direct `eval` and `with`.
+
+Guest code can only reach guest intrinsics: nothing it can name or traverse to leads to a
+host object (`tests/sandbox.test.ts` and `tests/sandbox-audit.test.ts` check this,
+including through host-raised errors, iterators, proxies, `eval` and `Function`).
+
+The reference version is QuickJS 2025-04-26. Development uses [Bun](https://bun.sh) as
+the package manager and test runner.
+
+```sh
+bun install
+bun test                       # run the test suite (bun test runner)
+bun run src/qjs.ts file.js     # run a script with the qjs-like CLI
+bun run src/qjs.ts -e 'print(1 + 2)'
+bun run src/qjs.ts -d -e 'let x = 1'   # dump the generated bytecode
+bun run src/qjs.ts             # REPL
+JSEPTION_JIT=0 bun test        # run the suite on the interpreter tier only
+JSEPTION_JIT=always bun test   # compile every function that runs (no lazy tier-up)
+JSEPTION_JIT_DUMP=1 bun run src/qjs.ts file.js   # print the generated host code
+bun run bench/inproc.ts        # host vs tier modes, incl. cold-code bundles
+```
+
+## Installing
+
+```sh
+npm install jseption        # or: bun add jseption
+npx jseption -e 'print(1 + 2)'
+```
+
+The `jseption` entry point is host-neutral (browsers, workers, Bun, Node, Deno);
+`jseption/std` and the `jseption` command need Node. Releases are published from
+GitHub Actions, see `docs/RELEASING.md`.
+
+## Using the engine from TypeScript
+
+The public API mirrors the QuickJS C API:
+
+```ts
+import { JS_NewRuntime, JS_NewContext, JS_Eval, JS_IsException, JS_GetException,
+         JS_ToString, JS_EVAL_TYPE_GLOBAL, runPendingJobs } from 'jseption';
+
+const rt = JS_NewRuntime();
+const ctx = JS_NewContext(rt);
+const val = JS_Eval(ctx, '[1, 2, 3].map(x => x * 2).join()', '<input>', JS_EVAL_TYPE_GLOBAL);
+if (JS_IsException(val)) {
+  console.error(JS_ToString(ctx, JS_GetException(ctx)));
+} else {
+  console.log(val); // "2,4,6"
+}
+runPendingJobs(rt); // run the promise jobs
+```
+
+Guest values are host values: primitives are the same host primitives, objects are host
+objects with guest prototypes (`JS_IsObject`, `JS_GetOpaque` and the class ids work on
+engine metadata kept in a `WeakMap`). Engine code signals exceptions with the
+`JS_EXCEPTION` sentinel exactly like in C; compiled guest code and host natives throw, and
+the two conventions meet at the call boundary. See `docs/PORTING.md` and
+`docs/HOST_VALUES.md` for the internals.
+
+## Passing values between host and guest
+
+Guest values are host values, but the sandbox forbids handing the guest an object whose
+prototype chain reaches a host intrinsic. `src/embed.ts` marshals values at the boundary:
+
+```ts
+import { expose, toGuest, fromGuest, guestPromiseToHost } from 'jseption';
+
+// plain data, functions and promises become guest values; host class instances are
+// rejected unless a `custom` converter is given
+expose(ctx, 'fetch', async (url: string) => {
+  const res = await fetch(url);
+  return { status: res.status, json: () => res.json(), text: () => res.text() };
+});
+const p = JS_Eval(ctx, '(async () => (await (await fetch(u)).json()).id)()', 'guest.js', JS_EVAL_TYPE_GLOBAL);
+const id = await guestPromiseToHost(ctx, p);   // guest promise -> host promise
+const data = fromGuest(ctx, value);            // guest object graph -> plain host data
+```
+
+Primitives cross unchanged. `toGuest` copies objects, arrays, Date, RegExp, Map, Set,
+typed arrays and Errors into guest equivalents, wraps host functions in guest functions
+(host exceptions become guest errors, returned promises are bridged, guest promise jobs
+run when they settle) and preserves shared references and cycles. `fromGuest` does the
+reverse, turning guest functions into host functions that call into the guest. See
+`examples/fetch.ts`.
+
+## Layout
+
+```
+src/atoms.ts        atom table (JS_ATOM_*), tagged integer atoms, atom -> property key
+src/values.ts       JSValue, object metadata, bytecode & frame structures
+src/opcodes.ts      opcode table generated from quickjs-opcode.h
+src/quickjs.ts      runtime, context, property layer over Reflect, calls, conversions, jobs
+src/parser.ts       tokenizer, parser, bytecode emitter, variable/label resolution, eval
+src/interpreter.ts  JS_CallInternal, closures, generators, async functions (fallback tier)
+src/jit.ts          bytecode -> host JavaScript compiler (stack-to-register, relooper)
+src/jit_runtime.ts  the helpers generated code calls into (the only engine touchpoint)
+src/builtins/       standard library; native.ts borrows host natives behind guest wrappers
+src/std.ts          print / console / std / os helpers for the CLI (subset of quickjs-libc)
+src/qjs.ts          command line interpreter
+src/dump.ts         bytecode disassembler
+src/embed.ts        host <-> guest value marshalling (expose, toGuest, fromGuest, promises)
+examples/           embedding examples (fetch facade)
+bench/              benchmark programs and runners (host vs compiled vs interpreted)
+tests/              bun tests, including the QuickJS test suite files in tests/qjs/
+```
+
+## Status
+
+The test suite (`bun test`) has 480+ tests, including QuickJS's own `test_language.js`,
+`test_closure.js`, `test_loop.js`, `test_builtin.js` and `test_bigint.js` run unmodified
+inside the engine (only the two tests that need a deterministic garbage collector are
+skipped). The suite passes in every mode (`JSEPTION_JIT=0`, the default, `always`). QuickJS's
+`microbench.js` runs with `bun run src/qjs.ts tests/qjs/microbench.js`. The compiled tier
+is the only part that generates code from strings (`new Function`, CSP `'unsafe-eval'`);
+where the host forbids it, the tier turns itself off and the interpreter runs everything
+(see docs/JIT.md).
+
+Performance (`bench/inproc.ts`, Bun 1.4 / JavaScriptCore, time relative to running the same
+program directly on the host; function-local variants keep their state in locals, the
+others in top-level globals, which cost about 20 ns per access). The default mode (`hot`)
+compiles a function once it is hot and replaces running interpreter loops with compiled
+code; `always` compiles every function that runs:
+
+| program | default (hot) / host | always / host | interpreted / host |
+| --- | --- | --- | --- |
+| integer loop (function-local) | 1.0x | 1.0x | 18x |
+| string building and methods | 1.3x | 1.3x | 4x |
+| array push / sort / map / filter | 2.1x | 1.9x | 100x |
+| object allocation + method calls (function-local) | 2.8x | 2.8x | 650x |
+| closures + try/catch (function-local) | 4.3x | 3.0x | 190x |
+| recursive fib (function-local) | 3.4x | 2.9x | 85x |
+| the same programs on top-level globals | 4x to 19x | 3x to 18x | |
+| 2000 / 8000 functions that each run once | 12x / 7.5x | 42x / 39x | 12x / 7.6x |
+
+The last row is application start-up: code that runs once is cheaper to interpret than
+to compile (300 to 400 µs per compiled function, most of it the host compiling the
+generated source), which is why `hot` is the default. See docs/JIT.md for the details.
+
+Implemented: the complete ES2023 language (classes with private members and static
+blocks, generators, async functions and async generators, destructuring, spread,
+optional chaining, template literals, labeled statements, `with`, direct and indirect
+`eval`, `new.target`, `super`, BigInt, ...), the QuickJS bytecode compiler with its
+peephole optimizations and short opcodes, and the standard library.
+
+Differences from the C implementation:
+
+* The object model is the host's (see `docs/HOST_VALUES.md`): property storage,
+  descriptors, frozen objects, Proxy invariants and typed array indexing are implemented
+  by the host engine; the QuickJS shapes, exotic method tables and reference counting are
+  gone.
+* Hot builtins (`Array`, `String`, `Object`, `Math`, `Number`, `JSON`, `Map`, `Set`,
+  `RegExp`, ...) forward to the host natives, so their error messages are the host's and
+  `Math.random` is the host generator. Builtins that must follow QuickJS (`eval`,
+  `Function`, `Error`, `Promise` and the job queue, `Date`, generators) stay ported.
+* Compiled functions have no interpreter frame; see `docs/JIT.md` for how error locations
+  are recovered.
+
+* Regular expressions are executed by the host JavaScript engine (libregexp is not
+  ported); the `RegExp` builtin reproduces the QuickJS/ECMAScript semantics on top of it.
+* Errors raised by the host for native operations (typed array element conversion,
+  Proxy invariant violations, array length limits, ...) carry the host engine's messages;
+  errors raised by the engine itself keep the QuickJS messages.
+* Mapped `arguments` objects alias the parameters through accessor properties, and
+  constructors always have a `prototype` own property (`undefined` when the
+  specification has none, e.g. `Proxy`).
+* Memory management relies on the host garbage collector: there is no reference
+  counting, `JS_FreeValue`/`JS_DupValue` are no-ops, and `WeakRef` / `FinalizationRegistry`
+  use the host weak references.
+* ES modules (`import` / `export`), `Atomics`, `SharedArrayBuffer` threads and the
+  bytecode serialization (`JS_WriteObject` / `JS_ReadObject`) are not ported.
+* Number formatting and parsing use the host conversions (they are specified by
+  ECMAScript, so the results are identical).
+
+## License
+
+MIT, like QuickJS. The test files under `tests/qjs/` come from the QuickJS distribution
+(copyright Fabrice Bellard and Charlie Gordon).

package/dist/atoms.d.ts

@@ -0,0 +1,255 @@
+export type JSAtom = number;
+export declare const JS_ATOM_NULL: JSAtom;
+export declare const predefinedAtomNames: string[];
+export declare const JS_ATOM_null = 1;
+export declare const JS_ATOM_false: number;
+export declare const JS_ATOM_true: number;
+export declare const JS_ATOM_if: number;
+export declare const JS_ATOM_else: number;
+export declare const JS_ATOM_return: number;
+export declare const JS_ATOM_var: number;
+export declare const JS_ATOM_this: number;
+export declare const JS_ATOM_delete: number;
+export declare const JS_ATOM_void: number;
+export declare const JS_ATOM_typeof: number;
+export declare const JS_ATOM_new: number;
+export declare const JS_ATOM_in: number;
+export declare const JS_ATOM_instanceof: number;
+export declare const JS_ATOM_do: number;
+export declare const JS_ATOM_while: number;
+export declare const JS_ATOM_for: number;
+export declare const JS_ATOM_break: number;
+export declare const JS_ATOM_continue: number;
+export declare const JS_ATOM_switch: number;
+export declare const JS_ATOM_case: number;
+export declare const JS_ATOM_default: number;
+export declare const JS_ATOM_throw: number;
+export declare const JS_ATOM_try: number;
+export declare const JS_ATOM_catch: number;
+export declare const JS_ATOM_finally: number;
+export declare const JS_ATOM_function: number;
+export declare const JS_ATOM_debugger: number;
+export declare const JS_ATOM_with: number;
+export declare const JS_ATOM_class: number;
+export declare const JS_ATOM_const: number;
+export declare const JS_ATOM_enum: number;
+export declare const JS_ATOM_export: number;
+export declare const JS_ATOM_extends: number;
+export declare const JS_ATOM_import: number;
+export declare const JS_ATOM_super: number;
+export declare const JS_ATOM_implements: number;
+export declare const JS_ATOM_interface: number;
+export declare const JS_ATOM_let: number;
+export declare const JS_ATOM_package: number;
+export declare const JS_ATOM_private: number;
+export declare const JS_ATOM_protected: number;
+export declare const JS_ATOM_public: number;
+export declare const JS_ATOM_static: number;
+export declare const JS_ATOM_yield: number;
+export declare const JS_ATOM_await: number;
+export declare const JS_ATOM_empty_string: number;
+export declare const JS_ATOM_length: number;
+export declare const JS_ATOM_fileName: number;
+export declare const JS_ATOM_lineNumber: number;
+export declare const JS_ATOM_columnNumber: number;
+export declare const JS_ATOM_message: number;
+export declare const JS_ATOM_cause: number;
+export declare const JS_ATOM_errors: number;
+export declare const JS_ATOM_stack: number;
+export declare const JS_ATOM_name: number;
+export declare const JS_ATOM_toString: number;
+export declare const JS_ATOM_toLocaleString: number;
+export declare const JS_ATOM_valueOf: number;
+export declare const JS_ATOM_eval: number;
+export declare const JS_ATOM_prototype: number;
+export declare const JS_ATOM_constructor: number;
+export declare const JS_ATOM_configurable: number;
+export declare const JS_ATOM_writable: number;
+export declare const JS_ATOM_enumerable: number;
+export declare const JS_ATOM_value: number;
+export declare const JS_ATOM_get: number;
+export declare const JS_ATOM_set: number;
+export declare const JS_ATOM_of: number;
+export declare const JS_ATOM___proto__: number;
+export declare const JS_ATOM_undefined: number;
+export declare const JS_ATOM_number: number;
+export declare const JS_ATOM_boolean: number;
+export declare const JS_ATOM_string: number;
+export declare const JS_ATOM_object: number;
+export declare const JS_ATOM_symbol: number;
+export declare const JS_ATOM_integer: number;
+export declare const JS_ATOM_unknown: number;
+export declare const JS_ATOM_arguments: number;
+export declare const JS_ATOM_callee: number;
+export declare const JS_ATOM_caller: number;
+export declare const JS_ATOM__eval_: number;
+export declare const JS_ATOM__ret_: number;
+export declare const JS_ATOM__var_: number;
+export declare const JS_ATOM__arg_var_: number;
+export declare const JS_ATOM__with_: number;
+export declare const JS_ATOM_lastIndex: number;
+export declare const JS_ATOM_target: number;
+export declare const JS_ATOM_index: number;
+export declare const JS_ATOM_input: number;
+export declare const JS_ATOM_defineProperties: number;
+export declare const JS_ATOM_apply: number;
+export declare const JS_ATOM_join: number;
+export declare const JS_ATOM_concat: number;
+export declare const JS_ATOM_split: number;
+export declare const JS_ATOM_construct: number;
+export declare const JS_ATOM_getPrototypeOf: number;
+export declare const JS_ATOM_setPrototypeOf: number;
+export declare const JS_ATOM_isExtensible: number;
+export declare const JS_ATOM_preventExtensions: number;
+export declare const JS_ATOM_has: number;
+export declare const JS_ATOM_deleteProperty: number;
+export declare const JS_ATOM_defineProperty: number;
+export declare const JS_ATOM_getOwnPropertyDescriptor: number;
+export declare const JS_ATOM_ownKeys: number;
+export declare const JS_ATOM_add: number;
+export declare const JS_ATOM_done: number;
+export declare const JS_ATOM_next: number;
+export declare const JS_ATOM_values: number;
+export declare const JS_ATOM_source: number;
+export declare const JS_ATOM_flags: number;
+export declare const JS_ATOM_global: number;
+export declare const JS_ATOM_unicode: number;
+export declare const JS_ATOM_raw: number;
+export declare const JS_ATOM_new_target: number;
+export declare const JS_ATOM_this_active_func: number;
+export declare const JS_ATOM_home_object: number;
+export declare const JS_ATOM_computed_field: number;
+export declare const JS_ATOM_static_computed_field: number;
+export declare const JS_ATOM_class_fields_init: number;
+export declare const JS_ATOM_brand: number;
+export declare const JS_ATOM_hash_constructor: number;
+export declare const JS_ATOM_as: number;
+export declare const JS_ATOM_from: number;
+export declare const JS_ATOM_meta: number;
+export declare const JS_ATOM__default_: number;
+export declare const JS_ATOM__star_: number;
+export declare const JS_ATOM_Module: number;
+export declare const JS_ATOM_then: number;
+export declare const JS_ATOM_resolve: number;
+export declare const JS_ATOM_reject: number;
+export declare const JS_ATOM_promise: number;
+export declare const JS_ATOM_proxy: number;
+export declare const JS_ATOM_revoke: number;
+export declare const JS_ATOM_async: number;
+export declare const JS_ATOM_exec: number;
+export declare const JS_ATOM_groups: number;
+export declare const JS_ATOM_indices: number;
+export declare const JS_ATOM_status: number;
+export declare const JS_ATOM_reason: number;
+export declare const JS_ATOM_globalThis: number;
+export declare const JS_ATOM_bigint: number;
+export declare const JS_ATOM_minus_zero: number;
+export declare const JS_ATOM_Infinity: number;
+export declare const JS_ATOM_minus_Infinity: number;
+export declare const JS_ATOM_NaN: number;
+export declare const JS_ATOM_not_equal: number;
+export declare const JS_ATOM_timed_out: number;
+export declare const JS_ATOM_ok: number;
+export declare const JS_ATOM_toJSON: number;
+export declare const JS_ATOM_Object: number;
+export declare const JS_ATOM_Array: number;
+export declare const JS_ATOM_Error: number;
+export declare const JS_ATOM_Number: number;
+export declare const JS_ATOM_String: number;
+export declare const JS_ATOM_Boolean: number;
+export declare const JS_ATOM_Symbol: number;
+export declare const JS_ATOM_Arguments: number;
+export declare const JS_ATOM_Math: number;
+export declare const JS_ATOM_JSON: number;
+export declare const JS_ATOM_Date: number;
+export declare const JS_ATOM_Function: number;
+export declare const JS_ATOM_GeneratorFunction: number;
+export declare const JS_ATOM_ForInIterator: number;
+export declare const JS_ATOM_RegExp: number;
+export declare const JS_ATOM_ArrayBuffer: number;
+export declare const JS_ATOM_SharedArrayBuffer: number;
+export declare const JS_ATOM_Uint8ClampedArray: number;
+export declare const JS_ATOM_Int8Array: number;
+export declare const JS_ATOM_Uint8Array: number;
+export declare const JS_ATOM_Int16Array: number;
+export declare const JS_ATOM_Uint16Array: number;
+export declare const JS_ATOM_Int32Array: number;
+export declare const JS_ATOM_Uint32Array: number;
+export declare const JS_ATOM_BigInt64Array: number;
+export declare const JS_ATOM_BigUint64Array: number;
+export declare const JS_ATOM_Float32Array: number;
+export declare const JS_ATOM_Float64Array: number;
+export declare const JS_ATOM_DataView: number;
+export declare const JS_ATOM_BigInt: number;
+export declare const JS_ATOM_WeakRef: number;
+export declare const JS_ATOM_FinalizationRegistry: number;
+export declare const JS_ATOM_Map: number;
+export declare const JS_ATOM_Set: number;
+export declare const JS_ATOM_WeakMap: number;
+export declare const JS_ATOM_WeakSet: number;
+export declare const JS_ATOM_Map_Iterator: number;
+export declare const JS_ATOM_Set_Iterator: number;
+export declare const JS_ATOM_Array_Iterator: number;
+export declare const JS_ATOM_String_Iterator: number;
+export declare const JS_ATOM_RegExp_String_Iterator: number;
+export declare const JS_ATOM_Generator: number;
+export declare const JS_ATOM_Proxy: number;
+export declare const JS_ATOM_Promise: number;
+export declare const JS_ATOM_PromiseResolveFunction: number;
+export declare const JS_ATOM_PromiseRejectFunction: number;
+export declare const JS_ATOM_AsyncFunction: number;
+export declare const JS_ATOM_AsyncFunctionResolve: number;
+export declare const JS_ATOM_AsyncFunctionReject: number;
+export declare const JS_ATOM_AsyncGeneratorFunction: number;
+export declare const JS_ATOM_AsyncGenerator: number;
+export declare const JS_ATOM_EvalError: number;
+export declare const JS_ATOM_RangeError: number;
+export declare const JS_ATOM_ReferenceError: number;
+export declare const JS_ATOM_SyntaxError: number;
+export declare const JS_ATOM_TypeError: number;
+export declare const JS_ATOM_URIError: number;
+export declare const JS_ATOM_InternalError: number;
+export declare const JS_ATOM_Private_brand: number;
+export declare const JS_ATOM_Symbol_toPrimitive: number;
+export declare const JS_ATOM_Symbol_iterator: number;
+export declare const JS_ATOM_Symbol_match: number;
+export declare const JS_ATOM_Symbol_matchAll: number;
+export declare const JS_ATOM_Symbol_replace: number;
+export declare const JS_ATOM_Symbol_search: number;
+export declare const JS_ATOM_Symbol_split: number;
+export declare const JS_ATOM_Symbol_toStringTag: number;
+export declare const JS_ATOM_Symbol_isConcatSpreadable: number;
+export declare const JS_ATOM_Symbol_hasInstance: number;
+export declare const JS_ATOM_Symbol_species: number;
+export declare const JS_ATOM_Symbol_unscopables: number;
+export declare const JS_ATOM_Symbol_asyncIterator: number;
+export declare const JS_ATOM_END: number;
+export declare const JS_ATOM_TYPE_STRING = 1;
+export declare const JS_ATOM_TYPE_GLOBAL_SYMBOL = 2;
+export declare const JS_ATOM_TYPE_SYMBOL = 3;
+export declare const JS_ATOM_TYPE_PRIVATE = 4;
+export declare const JS_ATOM_TAG_INT = 2147483648;
+export declare const JS_ATOM_MAX_INT = 2147483647;
+export declare function __JS_AtomIsTaggedInt(v: JSAtom): boolean;
+export declare function __JS_AtomFromUInt32(v: number): JSAtom;
+export declare function __JS_AtomToUInt32(atom: JSAtom): number;
+export declare function js_well_known_symbol(name: string): symbol | null;
+export declare function is_num_string(str: string): number;
+export declare class AtomTable {
+    private names;
+    private types;
+    private strMap;
+    private symMap;
+    constructor();
+    newAtomStr(str: string): JSAtom;
+    newAtomUInt32(n: number): JSAtom;
+    newSymbol(description: string | undefined, atom_type: number): symbol;
+    symbolToAtom(sym: symbol): JSAtom;
+    getType(atom: JSAtom): number;
+    isString(atom: JSAtom): boolean;
+    isSymbol(atom: JSAtom): boolean;
+    getSymbol(atom: JSAtom): symbol;
+    toKey(atom: JSAtom): string | number | symbol;
+    toStr(atom: JSAtom): string;
+    toDisplayStr(atom: JSAtom): string;
+}