@primafuture/jsonnet-runtime

In-process Jsonnet runtime for PrimaFuture projects.

The V1 runtime is backed by a patched jrsonnet-web WASM binding bundled in this npm package. It does not require an external jrsonnet executable.

V1 Contract

• One run uses one evaluator.
• No hybrid Hanazuki/jrsonnet evaluation.
• evaluateFile(...) and evaluateSnippet(...) return parsed JSON objects.
• importRootDirectories behave like Jsonnet -J/jpath roots.
• extVar maps string values to runtime external variables.
• extCode maps Jsonnet expressions to runtime external variables.
• nativeCallback(...) supports synchronous callbacks for direct Jsonnet std.native(...) usage.
• Async std.native(...) callbacks are intentionally out of V1 scope.

High-level Netson APIs can still support async custom matchers when those calls are dispatched outside Jsonnet.

Usage

import * as jsonnetRuntime from '@primafuture/jsonnet-runtime';

const jsonnet = jsonnetRuntime.createJsonnetRuntime({
  nativeCallbacks: {
    echo: {
      params: ['payload'],
      callback: (payload) => ({ echoed: payload }),
    },
  },
});

const config = await jsonnet.evaluateFile({
  filePath: '/path/to/config.jsonnet',
  importRootDirectories: ['/path/to/lib'],
  extVar: {
    env: 'dev',
  },
  extCode: {
    buildNumber: '100 + 23',
  },
});

Native callbacks are sync by design in V1. Returning a Promise from a direct Jsonnet std.native(...) callback throws a clear error.

Maintenance

The generated jrsonnet-web JavaScript/WASM binding is vendored in binding/. When upstream jrsonnet changes, follow docs/update-jrsonnet-web.md to rebase the patch, rebuild the WASM binding, and verify Netson compatibility.