Embedding

C API reference.

js.h now exposes opaque types and C linkage. C++ containers, exceptions, templates and engine-private addresses stay behind the ABI.

First lifecycle slice

typedef struct js_runtime js_runtime;
typedef struct js_value js_value;

js_runtime *js_runtime_new(void);
void js_runtime_free(js_runtime *runtime);

js_status js_eval(js_runtime *runtime,
                  const char *source,
                  js_value **result);
void js_value_free(js_runtime *runtime, js_value *value);

JS1 fixes values as opaque runtime-affine handles. JS3 now returns primitive completion values from evaluation. The source API is tested from C; binary compatibility remains a pre-release concern.

API families, in order

Runtime and errors

Creation, destruction, version information, evaluation, diagnostics and error clearing.

Values and roots

Type inspection, conversion, persistent handles and explicit ownership.

Objects and native functions

Properties, calls, user data, finalizers, exceptions and safe re-entry.

Jobs and modules

Host-controlled job draining and module resolution/loading callbacks.

ABI rules

  • No C++ exception crosses the public C boundary.
  • No private structure is exposed by value.
  • Ownership is documented for every returned pointer and handle.
  • JS_API_VERSION and js_api_version() identify preview ABI 0.1; SONAME 0 remains pre-release.
  • Thread safety is explicit per operation, never inferred.