Skip to main content

Compiler API

The Compiler API is the entry point that transforms YAML policy sources into a reusable compiled Policy artifact.

In the JavaScript SDK, the compiler surface is split into:

  • environment-neutral core compilation → fromStrings()
  • Node.js file-system helpers → fromFiles() and fromDirectory()

This page documents the compiler APIs.

Mental Model​

YAML -> Compiler -> Native Policy -> Policy Artifact

This is the first stage of every Actra integration.

Environment-Neutral Compilation​

fromStrings()​

Compile directly from YAML strings.

import { Actra } from "@getactra/actra"

const policy = await Actra.fromStrings(
  schemaYaml,
  policyYaml,
  governanceYaml,
)

This is the portable compiler API and works across environments where the engine is available.

Best for:

  • browser bundles
  • edge runtimes
  • generated config
  • remote policy fetch
  • test fixtures
  • CI pipelines

Node.js File-System APIs​

These APIs are Node.js-only conveniences built on top of filesystem loading.

They are not applicable in browser or edge environments where local filesystem access is unavailable.

Use fromStrings() instead for browser, edge, workers, and WASM-hosted runtimes.

fromFiles()​

Compile from explicit YAML file paths.

const policy = await Actra.fromFiles(
  "./policy/schema.yaml",
  "./policy/policy.yaml",
  "./policy/governance.yaml",
)

Best for:

  • Node services
  • scripts
  • CLI tools
  • local testing
  • CI jobs

Environment Note​

  • ✅ Node.js
  • ❌ Browser
  • ❌ Edge runtimes
  • ❌ Service worker environments

fromDirectory()​

Compile from a policy directory.

const policy = await Actra.fromDirectory("./policy")

This loads:

  • schema
  • policy
  • optional governance

from a standard directory layout.

This is the recommended production Node.js workflow.

Best for:

  • monorepos
  • governed policy repos
  • multi-team ownership
  • CI validation
  • enterprise policy packages

Environment Note​

This API depends on filesystem directory scanning.

Use only in:

  • ✅ Node.js

Not supported in:

  • ❌ Browser
  • ❌ Edge functions
  • ❌ Cloudflare Workers
  • ❌ Vercel Edge
  • ❌ Deno Deploy

For these environments, load policy content remotely and use fromStrings().

Compiler Version​

compilerVersion()​

Retrieve the native compiler version.

const version = await Actra.compilerVersion()

Useful for:

  • diagnostics
  • CI verification
  • artifact compatibility
  • support workflows
  • rollout validation

Failure Semantics​

Empty YAML​

If schema or policy content is empty:

ActraError

File Loading Failure​

fromFiles() and fromDirectory() wrap file-system failures as:

ActraError

Native Compilation Failure​

Compiler validation failures are wrapped as:

ActraError

This includes:

  • schema errors
  • policy errors
  • governance violations
  • invalid operators
  • engine initialization issues

Production Recommendations​

Node.js services​

Prefer:

Actra.fromDirectory()

Browser / Edge / Remote Config​

Prefer:

Actra.fromStrings()

This keeps the compiler portable across non-filesystem environments.

Production Mental Model​

Node files -> fromDirectory() -> Policy
Remote YAML -> fromStrings() -> Policy

This separation keeps the SDK environment-safe.

Next Steps​

  • Use Policy Artifact API
  • Integrate with Runtime API
  • Build Browser & Edge loading flows
  • Add Testing Policies