@rcrsr/rill

Embeddable, sandboxed scripting runtime for rill. Zero dependencies. Browser and Node.js compatible.

> Experimental. Breaking changes will occur before stabilization.

Install

``bash
npm install @rcrsr/rill
`

Quick Start

`typescript
import { parse, execute, createRuntimeContext } from '@rcrsr/rill';

const script =
prompt("Analyze this code for issues")
-> .contains("ERROR") ? error($) ! "Analysis complete"
;

const ctx = createRuntimeContext({
functions: {
prompt: {
params: [{ name: 'message', type: 'string' }],
fn: async (args) => await callYourLLM(args[0]),
},
},
});

const result = await execute(parse(script), ctx);
console.log(result.value);
`

API

$3

`
Source Text → parse() → AST → execute() → Result
`

| Export | Purpose |
|--------|---------|
| parse(source) | Parse rill source into an AST |
| execute(ast, ctx) | Execute an AST with a runtime context |
| createRuntimeContext(opts) | Create a configured runtime context |
| callable(fn, isProperty?) | Wrap a function as a rill-callable value |
| prefixFunctions(prefix, fns) | Namespace host functions (e.g., app::) |

$3

`typescript
const ctx = createRuntimeContext({
// Host functions available to scripts
functions: {
prompt: {
params: [{ name: 'text', type: 'string' }],
fn: async (args, ctx, location) => { / ... / },
},
},

// Variables injected into script scope
variables: {
config: { greeting: 'hello' },
},

// Callbacks
callbacks: {
onLog: (value) => console.log(value),
},

// Observability hooks
observability: {
onStepStart: (e) => { / ... / },
onStepEnd: (e) => { / ... / },
},

// Execution limits
timeout: 30000,
signal: abortController.signal,
});
`

$3

Step through execution one statement at a time:

`typescript
import { parse, createRuntimeContext, createStepper } from '@rcrsr/rill';

const stepper = createStepper(parse(script), createRuntimeContext());

let step;
while (!(step = await stepper.next()).done) {
console.log(step.value);
}
`

$3

| Export | Purpose |
|--------|---------|
| parseWithRecovery(source) | Parse with error recovery (for editors) |
| tokenize(source) | Tokenize source into a token stream |
| TOKEN_HIGHLIGHT_MAP | Syntax highlighting category map |
| getLanguageReference() | LLM-optimized language reference text |
| getDocumentationCoverage() | Coverage stats for doc examples |
| getFunctions() | List of built-in function metadata |
| VERSION / VERSION_INFO | Runtime version string and metadata |

$3

`typescript
import { parse, execute, createRuntimeContext, AbortError } from '@rcrsr/rill';

try {
const result = await execute(parse(script), ctx);
} catch (err) {
if (err instanceof AbortError) {
// Execution was cancelled via signal
}
// Runtime errors include source location and error code
}
`

$3

| Export | Purpose |
|--------|---------|
| isDict(value) | Check if value is a rill dict |
| isTuple(value) | Check if value is a rill tuple |
| isCallable(value) | Check if value is any callable |
| isScriptCallable(value) | Check if value is a script-defined closure |
| isApplicationCallable(value)` | Check if value is a host-provided callable |

Documentation

| Document | Description |
|----------|-------------|
| Host Integration | Embedding guide |
| Host API Reference | Complete TypeScript API |
| Language Reference | Language specification |
| Extensions | Reusable host function packages |

License

MIT