Roid Runner

Key Types

type RoidMemory = Map<string, Record<string, unknown>>;
// key   = variable name declared in the script (e.g. "sma", "pos")
// value = channel map: { values: number[], timestamps: number[], … }
// Arrays grow by one element per frame.

interface CompiledStep {
  exec: (memory: RoidMemory, frameIdx: number) => void;
  meta: CompiledStepMeta;
}

interface CompiledStepMeta {
  varName:   string;
  funcName:  string;
  kind:      'source' | 'compute';
  inputRefs: string[];          // variable names of input nodes
  args:      Record<string, string | number>; // baked param values
}

interface CompiledRoid {
  steps:       CompiledStep[];
  totalFrames: number; // length of the first source's arrays
}

interface RoidRunResult {
  success: boolean;
  memory:  RoidMemory;
  errors:  string[];  // e.g. "frame 42: TypeError: …"
}

interface IncrementalRunner {
  push(inputs: Record<string, unknown>[]): Record<string, unknown>;
}

type RunnerFactory =
  (args: Record<string, string | number>) => IncrementalRunner;

compileRoid()

export async function compileRoid(
  source: string,
  prefetchedData?: Record<string, unknown>,
): Promise<CompiledRoid>

The optional prefetchedData parameter allows callers to supply pre-loaded market data. When omitted, each source step calls the appropriate SOURCES function to fetch data asynchronously on compilation.

Compilation Steps

How compute steps extract inputs

Each frame, a compute step reads the latest value from every input channel:

// Inside the CompiledStep.exec closure for a compute step:
const bars = inputRefs.map(ref => {
  const data = memory.get(ref)!;
  const bar: Record<string, unknown> = {};
  for (const ch of Object.keys(data)) {
    const val = data[ch];
    // Extract last element of arrays; pass scalars through as-is
    bar[ch] = Array.isArray(val) ? val[val.length - 1] : val;
  }
  return bar;
});
// bars[0] = { c: 150.2, h: 151.0, l: 149.5, t: 1715000000 }  ← latest bar
const out = runner.push(bars);

runRoid() & runRoidAsync()

function runRoid(roid: CompiledRoid): RoidRunResult

function runRoidAsync(
  roid:       CompiledRoid,
  delayMs:    number,
  onProgress: (frame, total, memory) => void,
  onDone:     (result) => void,
): () => void  // cancel function

Runner Modules

Each runner module exports a Record<string, RunnerFactory> constant. The Roid Runner merges all of them with the ?? fallback chain to look up the correct factory by command name.

Writing a RunnerFactory

A factory receives the baked parameter map and returns an IncrementalRunner. Stateful variables are captured in the factory's closure. Example — a simple SMA runner:

const SMA: RunnerFactory = (args) => {
  const period = args.period as number;
  const window: number[] = [];   // rolling window — closed over
  let sum = 0;

  return {
    push(inputs) {
      const src = inputs[0];
      const close = src.c as number;
      window.push(close);
      sum += close;
      if (window.length > period) sum -= window.shift()!;
      return {
        values:     window.length >= period ? sum / period : null,
        timestamps: src.t,
      };
    },
  };
};

RoidPositionState

RoidPositionState.ts is a module-level singleton that tracks a single open position across the OPENPOSITION and CLOSEPOSITION runner closures within one Roid execution. It is reset by resetRoidPositionState() at the start of every compileRoid() call.

RoidRunnerSources — SOURCES

The SOURCES map is keyed by command name (STOCK, CRYPTO, FOREX) and maps to an async function that accepts the baked args and returns a Record<string, unknown> containing the full OHLCV arrays. The Roid compiler calls this at compile time; subsequent frames just index into the pre-fetched arrays.

// Pattern of a SOURCES entry:
const SOURCES: Record<string, (args: Record<string, string | number>) => Promise<Record<string, unknown>>> = {
  STOCK: async (args) => {
    const { symbol, timespan, multiplier } = args;
    // Fetch from API...
    return { t: [...], o: [...], h: [...], l: [...], c: [...], v: [...] };
  },
  CRYPTO: async (args) => { … },
  FOREX:  async (args) => { … },
};

The prefetchedData argument to compileRoid() bypasses the source function entirely, allowing callers (e.g. the backtesting engine) to inject pre-loaded data without additional network requests.

Usage Example

import { compileRoid, runRoid, runRoidAsync } from './roidRunner/RoidRunner';

const source = `
s    = sc.STOCK("AAPL", "day", 1)
fast = ta.SMA(s, 10)
slow = ta.SMA(s, 50)
sig  = dm.CROSSOVER(fast, slow)
`;

// ── Synchronous run ──────────────────────────────────────────────────
const roid = await compileRoid(source);
const result = runRoid(roid);
if (result.success) {
  const sigValues = result.memory.get('sig')?.values as (number | null)[];
  const lastSignal = sigValues?.at(-1);
  console.log('Last signal:', lastSignal); // 1 = bullish crossover, 0 = not
}

// ── Async run with live progress ─────────────────────────────────────
const cancel = runRoidAsync(
  roid,
  16,  // ~60fps
  (frame, total, memory) => {
    const pct = Math.round((frame / total) * 100);
    console.log(`${pct}% — fast[${frame}] = ${
      (memory.get('fast')?.values as number[]).at(-1)
    }`);
  },
  (result) => {
    console.log('Done. Errors:', result.errors);
  },
);

// Optionally cancel mid-run:
// cancel();