@rcrsr/rill

Core runtime for rill — scripting designed for machine-generated code. Zero dependencies. Browser and Node.js compatible.

Experimental. Breaking changes will occur before stabilization.

Install

npm install @rcrsr/rill

Quick Start

import { parse, execute, createRuntimeContext, toCallable } from '@rcrsr/rill';
import type { ExtensionFactoryResult } from '@rcrsr/rill';

function createMyExtension(): ExtensionFactoryResult {
  return {
    value: {
      prompt: toCallable({
        params: [{ name: 'message', type: { kind: 'string' } }],
        fn: async (args) => await callYourLLM(args.message),
        annotations: { description: 'Call your LLM' },
        returnType: { kind: 'string' },
      }),
    },
  };
}

const ext = createMyExtension();
const ctx = createRuntimeContext({
  variables: { app: ext.value },
});

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

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

API

Core Pipeline

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 | | toCallable(def) | Convert a RillFunction to an ApplicationCallable | | createTestContext(extensions) | Wire extensions for testing without config infrastructure |

Runtime Options

const ext = createMyExtension();

const ctx = createRuntimeContext({
  // Extension values injected as variables (recommended)
  variables: {
    app: ext.value,
    config: { greeting: 'hello' },
  },

  // Legacy: direct function registration (still supported)
  functions: {
    prompt: {
      params: [{ name: 'text', type: { kind: 'string' } }],
      fn: async (args, ctx, location) => { /* ... */ },
      annotations: {},
      returnType: { kind: 'string' },
    },
  },

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

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

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

Stepper API

Step through execution one statement at a time:

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);
}

Additional Exports

| 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 |

Error Handling

import { parse, execute, createRuntimeContext, RuntimeHaltSignal, getStatus, atomName } from '@rcrsr/rill';

try {
  const result = await execute(parse(script), ctx);
} catch (err) {
  if (err instanceof RuntimeHaltSignal) {
    const status = getStatus(err.value);
    if (atomName(status.code) === 'DISPOSED') {
      // Execution was cancelled via AbortSignal
    }
    // err.catchable indicates whether guard/retry can recover
  }
  // Runtime errors include source location and error code
}

Type Guards

| 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 |

Extensions

Extensions (fs, fetch, exec, kv, crypto) live in the rill-ext repository. The core package provides the extension framework (types, contracts, lifecycle hooks) but ships no extension implementations.

Documentation

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

License

MIT