jseption 0.0.1 → 0.0.3

package/README.md

@@ -33,6 +33,7 @@ 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
+bun run bench/bytecode.ts file.js   # compile vs read precompiled bytecode vs run
 ```
 
 ## Installing
@@ -72,6 +73,37 @@ engine metadata kept in a `WeakMap`). Engine code signals exceptions with the
 the two conventions meet at the call boundary. See `docs/PORTING.md` and
 `docs/HOST_VALUES.md` for the internals.
 
+## Precompiled bytecode
+
+A script can be compiled ahead of time and loaded without parsing, as with QuickJS's
+`JS_WriteObject` / `JS_ReadObject`:
+
+```ts
+import { JS_Eval, JS_EVAL_TYPE_GLOBAL, JS_EVAL_FLAG_COMPILE_ONLY, JS_WriteObject, JS_ReadObject,
+         JS_EvalFunction, JS_IsException } from 'jseption';
+
+/* at build time */
+const fn = JS_Eval(ctx, src, 'runtime.js', JS_EVAL_TYPE_GLOBAL | JS_EVAL_FLAG_COMPILE_ONLY);
+const bytes = JS_WriteObject(ctx, fn);          /* Uint8Array, or null with an exception pending */
+
+/* at run time, in any runtime of the same jseption version */
+const loaded = JS_ReadObject(ctx2, bytes);      /* JS_EXCEPTION (a SyntaxError) on bad input */
+if (!JS_IsException(loaded)) JS_EvalFunction(ctx2, loaded);
+```
+
+Reading is 18x (host JIT on) to 37x (JIT off, as on iOS) faster than parsing a 300 KB
+bundle. Line numbers in error stacks are kept; function source text (for
+`Function.prototype.toString`) is dropped unless `JS_WRITE_OBJ_SOURCE` is passed. The
+bytes record the jseption version and only load in that version.
+
+**Only load bytecode you produced yourself.** As in QuickJS, the reader checks the format
+(version, bounds, tags, indices, instruction boundaries, a checksum) but not the meaning
+of the byte code: hand-made bytecode can reach engine states the parser never produces,
+so loading untrusted bytecode is not safe even though running untrusted source is. The
+checksum only catches accidental corruption; bytecode that passes through storage or a
+service you do not control needs a signature you verify before loading. See
+`docs/BYTECODE.md` for the format and the measurements.
+
 ## Passing values between host and guest
 
 Guest values are host values, but the sandbox forbids handing the guest an object whose
@@ -106,6 +138,7 @@ 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/bytecode.ts     bytecode serialization (JS_WriteObject / JS_ReadObject)
 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)
@@ -181,8 +214,9 @@ Differences from the C implementation:
 * 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.
+* ES modules (`import` / `export`), `Atomics` and `SharedArrayBuffer` threads are not
+  ported. `JS_WriteObject` / `JS_ReadObject` serialize compiled scripts (bytecode
+  function trees) only, not arbitrary values, in a jseption-specific format.
 * Number formatting and parsing use the host conversions (they are specified by
   ECMAScript, so the results are identical).
 

package/dist/bytecode.d.ts

@@ -0,0 +1,6 @@
+import { JSContext, JSValue } from './quickjs.ts';
+export declare const JS_WRITE_OBJ_SOURCE: number;
+export declare const BC_MAGIC: number[];
+export declare const BC_FORMAT = 1;
+export declare function JS_WriteObject(ctx: JSContext, obj: JSValue, flags?: number): Uint8Array | null;
+export declare function JS_ReadObject(ctx: JSContext, buf: Uint8Array): JSValue;