oakscriptjs 0.13.2 → 0.14.1

package/dist/esm/check/harness.js

@@ -0,0 +1,317 @@
+/**
+ * @fileoverview Runs a script source the way a host app runs a script written in its editor: the source is the body
+ * of the script, with every value export of `oakscriptjs/script` but `executeScript` as an implicit global, on
+ * deterministic synthetic bars (or given bars), with a chart context and, for a strategy, a small order engine.
+ * Used by {@link checkScript}, the `oakscript check` command and the tests of the agent guide.
+ *
+ * @module check/harness
+ */
+import * as lib from '../index.js';
+import * as api from '../script/index.js';
+import { executeScript, } from '../script/index.js';
+/** The implicit globals of a script: every value export of the script API but the host entry. */
+export const SCRIPT_GLOBALS = Object.keys(api).filter((k) => k !== 'default' && k !== 'executeScript' && /^[A-Za-z_$][\w$]*$/.test(k));
+/** Name of the parameter that receives the `oakscriptjs` module in a compiled script (its `import` statements). */
+export const LIBRARY_PARAMETER = '__oakscriptjs';
+/** The values of {@link SCRIPT_GLOBALS}, then the `oakscriptjs` module, in the order of the compiled parameters. */
+export function scriptArguments() {
+    return [...SCRIPT_GLOBALS.map((k) => api[k]), lib];
+}
+/**
+ * Rewrites the `import { a, b as c } from "oakscriptjs"` statements of a script into `const { a, b: c } = ...` on the
+ * same lines (the line numbers of the source do not change). Throws on an import of another module: a script runs
+ * self-contained.
+ */
+export function rewriteImports(source) {
+    return source.replace(/^([ \t]*)import\s*(\{[^}]*\}|\*\s+as\s+[A-Za-z_$][\w$]*)\s*from\s*(['"])([^'"]+)\3\s*;?/gm, (all, indent, what, _q, from) => {
+        if (from !== 'oakscriptjs' && from !== 'oakscriptjs/script') {
+            throw new SyntaxError(`A script can only import from "oakscriptjs" (found "${from}").`);
+        }
+        const lines = all.split('\n').length - 1;
+        const binding = what.startsWith('*')
+            ? what.replace(/^\*\s+as\s+/, '')
+            : what.replace(/\s+as\s+/g, ': ').replace(/\s+/g, ' ');
+        return `${indent}const ${binding} = ${LIBRARY_PARAMETER};${'\n'.repeat(lines)}`;
+    });
+}
+/**
+ * Start and end of the function the script source is wrapped in. The globals are the parameters of an outer function
+ * and the source is the body of an inner one, so a script can declare a name of a global (`const size = 2`), as in an
+ * app that imports the globals at the top of a module. The start goes on the first line of the source.
+ */
+export const SCRIPT_PREFIX = '"use strict"; return (function () { ';
+export const SCRIPT_SUFFIX = '\n})();';
+/** The source of the function body of a compiled script (imports rewritten, lines kept). */
+export function wrapSource(source) {
+    return SCRIPT_PREFIX + rewriteImports(source) + SCRIPT_SUFFIX;
+}
+/** Compiles a script source into a body for executeScript(); throws a SyntaxError on invalid code. */
+export function compileScript(source) {
+    const fn = new Function(...SCRIPT_GLOBALS, LIBRARY_PARAMETER, wrapSource(source));
+    const values = scriptArguments();
+    return () => fn(...values);
+}
+const HOUR = 3600;
+/** 2024-01-01 00:00 UTC, in seconds. */
+const START = 1704067200;
+/** Deterministic synthetic bars: two waves, a slow trend and seeded noise. `step`: seconds between bars. */
+export function syntheticBars(count, step = HOUR, seed = 1) {
+    let s = seed >>> 0 || 1;
+    const rand = () => {
+        s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+        return s / 2 ** 32;
+    };
+    const scale = Math.sqrt(step / HOUR);
+    const bars = [];
+    let prev = 100;
+    for (let i = 0; i < count; i++) {
+        const t = (i * step) / HOUR;
+        const close = 100 + 12 * Math.sin(t / 60) + 4 * Math.sin(t / 11) + t * 0.004 + (rand() - 0.5) * 1.5 * scale;
+        const open = prev;
+        const high = Math.max(open, close) + rand() * 0.8 * scale;
+        const low = Math.min(open, close) - rand() * 0.8 * scale;
+        bars.push({ time: START + i * step, open, high, low, close, volume: Math.round(1000 + rand() * 4000) });
+        prev = close;
+    }
+    return bars;
+}
+/** Seconds of a timeframe string ("1", "60", "240", "D", "1D", "W", "M"); NaN when it is not one. */
+export function timeframeSeconds(timeframe) {
+    const m = /^(\d*)([SDWM]?)$/.exec(timeframe.trim().toUpperCase());
+    if (!m)
+        return NaN;
+    const n = m[1] ? Number(m[1]) : 1;
+    const unit = { '': 60, S: 1, D: 86400, W: 7 * 86400, M: 30 * 86400 }[m[2]];
+    return n * unit;
+}
+/** The timeframe of bars from the most common spacing of their times ("60", "D", "W"...); "60" for fewer than 2 bars. */
+export function inferTimeframe(bars) {
+    const counts = new Map();
+    for (let i = 1; i < bars.length; i++) {
+        const d = bars[i].time - bars[i - 1].time;
+        if (d > 0)
+            counts.set(d, (counts.get(d) ?? 0) + 1);
+    }
+    let step = 0;
+    let best = 0;
+    for (const [d, c] of counts)
+        if (c > best)
+            [step, best] = [d, c];
+    if (!step)
+        return '60';
+    if (step >= 28 * 86400)
+        return 'M';
+    if (step >= 7 * 86400)
+        return 'W';
+    if (step >= 86400)
+        return 'D';
+    if (step < 60)
+        return `${step}S`;
+    return String(Math.round(step / 60));
+}
+/**
+ * Chart context of the test runs: a 24x7 symbol in UTC. Higher timeframes of the chart symbol are resampled from the
+ * chart bars by the library; other symbols get synthetic bars of their own (seeded by the symbol name).
+ */
+export function testChart(bars, options = {}) {
+    const timezone = options.timezone ?? 'Etc/UTC';
+    const session = options.session ?? '24x7';
+    const chartStep = timeframeSeconds(options.timeframe ?? '60') || HOUR;
+    const span = bars.length ? bars[bars.length - 1].time - bars[0].time + chartStep : 0;
+    return {
+        tickerid: options.tickerid ?? 'TEST:SYN',
+        timeframe: options.timeframe ?? '60',
+        timezone,
+        session,
+        mintick: 0.01,
+        pointvalue: 1,
+        mincontract: 1,
+        currency: 'USD',
+        bars: (symbol, timeframe) => {
+            const step = timeframeSeconds(timeframe);
+            if (!step)
+                return [];
+            // a run on zero bars (the declaration run of a host) gets one empty bar: no bars at all is an invalid symbol
+            if (!bars.length)
+                return [{ time: 0, open: 0, high: 0, low: 0, close: 0, volume: 0 }];
+            const first = bars[0].time;
+            return syntheticBars(Math.ceil(span / step), step, symbol.length + 7).map((b) => ({
+                ...b,
+                time: first + (b.time - START),
+            }));
+        },
+        symbolInfo: () => ({ timezone, session, mintick: 0.01, currency: 'USD' }),
+    };
+}
+/**
+ * A small order engine for checks and tests (the library does not fill orders). Market entries and closes fill at the
+ * next bar open; `strategy.exit` stop / limit levels are checked inside each bar (stop first when both are hit).
+ * Entry limit / stop prices, pyramiding and process_orders_on_close are not simulated.
+ */
+export class TestEngine {
+    setup;
+    closed = [];
+    open = null;
+    pendingEntry = null;
+    pendingClose = false;
+    exits = new Map();
+    net = 0;
+    bar = 0;
+    constructor(setup) {
+        this.setup = setup;
+    }
+    get bars() {
+        return this.setup.bars;
+    }
+    equity(price) {
+        return this.setup.properties.initial_capital + this.net + this.openProfit(price);
+    }
+    openProfit(price) {
+        return this.open ? (price - this.open.entry_price) * this.open.size : 0;
+    }
+    commission(value) {
+        const p = this.setup.properties;
+        return p.commission_type === 'percent' ? (Math.abs(value) * p.commission_value) / 100 : 0;
+    }
+    closeAt(price, exitId) {
+        const t = this.open;
+        if (!t)
+            return;
+        const commission = t.commission + this.commission(price * t.size);
+        const profit = (price - t.entry_price) * t.size - commission;
+        this.net += profit;
+        this.closed.push({
+            ...t,
+            commission,
+            profit,
+            profit_percent: (profit / Math.abs(t.entry_price * t.size)) * 100,
+            exit_id: exitId,
+            exit_price: price,
+            exit_bar_index: this.bar,
+            exit_time: this.bars[this.bar].time * 1000,
+        });
+        this.open = null;
+        this.exits.clear();
+    }
+    /** The open trade, if any. */
+    get openTradeNow() {
+        return this.open;
+    }
+    processBar(bar) {
+        this.bar = bar;
+        const b = this.bars[bar];
+        if (this.pendingClose)
+            this.closeAt(b.open, 'Close');
+        this.pendingClose = false;
+        const e = this.pendingEntry;
+        this.pendingEntry = null;
+        if (e && !(this.open && Math.sign(this.open.size) === (e.direction === 'long' ? 1 : -1))) {
+            if (this.open)
+                this.closeAt(b.open, e.id);
+            const p = this.setup.properties;
+            const equity = this.equity(b.open);
+            const qty = e.qty ??
+                (p.default_qty_type === 'fixed'
+                    ? p.default_qty_value
+                    : p.default_qty_type === 'cash'
+                        ? p.default_qty_value / b.open
+                        : (equity * p.default_qty_value) / 100 / b.open);
+            const size = e.direction === 'long' ? qty : -qty;
+            this.open = {
+                entry_id: e.id,
+                entry_price: b.open,
+                entry_bar_index: bar,
+                entry_time: b.time * 1000,
+                size,
+                profit: 0,
+                profit_percent: 0,
+                commission: this.commission(b.open * size),
+                max_runup: 0,
+                max_runup_percent: 0,
+                max_drawdown: 0,
+                max_drawdown_percent: 0,
+            };
+        }
+        const t = this.open;
+        if (!t)
+            return;
+        for (const [id, x] of this.exits) {
+            if (x.from_entry !== undefined && x.from_entry !== t.entry_id)
+                continue;
+            const long = t.size > 0;
+            if (x.stop !== undefined && (long ? b.low <= x.stop : b.high >= x.stop)) {
+                this.closeAt(long ? Math.min(b.open, x.stop) : Math.max(b.open, x.stop), id);
+                return;
+            }
+            if (x.limit !== undefined && (long ? b.high >= x.limit : b.low <= x.limit)) {
+                this.closeAt(long ? Math.max(b.open, x.limit) : Math.min(b.open, x.limit), id);
+                return;
+            }
+        }
+    }
+    processClose() { }
+    entry(id, direction, options) {
+        this.pendingEntry = { id, direction, qty: options.qty };
+    }
+    order(id, direction, options) {
+        this.entry(id, direction, options);
+    }
+    exit(id, options) {
+        this.exits.set(id, options);
+    }
+    close(id, _options) {
+        if (this.open?.entry_id === id)
+            this.pendingClose = true;
+    }
+    close_all() {
+        if (this.open)
+            this.pendingClose = true;
+    }
+    cancel(id) {
+        this.exits.delete(id);
+        if (this.pendingEntry?.id === id)
+            this.pendingEntry = null;
+    }
+    cancel_all() {
+        this.exits.clear();
+        this.pendingEntry = null;
+    }
+    rules = [];
+    risk(rule) {
+        this.rules.push(rule);
+    }
+    get(variable) {
+        const price = this.bars[this.bar]?.close ?? NaN;
+        const wins = this.closed.filter((t) => t.profit > 0).length;
+        const values = {
+            position_size: this.open?.size ?? 0,
+            position_avg_price: this.open?.entry_price ?? NaN,
+            initial_capital: this.setup.properties.initial_capital,
+            equity: this.equity(price),
+            netprofit: this.net,
+            openprofit: this.openProfit(price),
+            opentrades: this.open ? 1 : 0,
+            closedtrades: this.closed.length,
+            wintrades: wins,
+            losstrades: this.closed.length - wins,
+            account_currency: 'USD',
+        };
+        return values[variable];
+    }
+    openTrade(index) {
+        return index === 0 && this.open ? this.open : undefined;
+    }
+    closedTrade(index) {
+        return this.closed[index];
+    }
+}
+/** Runs a script source on `bars` with the test chart context and, for a strategy, the test engine. */
+export function runScript(source, bars, inputs = {}, options = {}) {
+    let engine;
+    const body = (options.compile ?? compileScript)(source);
+    const run = executeScript(body, bars, inputs, testChart(bars, options), {
+        strategyEngine: (setup) => (engine = new TestEngine(setup)),
+    });
+    return { run, engine };
+}
+//# sourceMappingURL=harness.js.map

package/dist/esm/check/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../../src/check/harness.ts"],"names":[],"mappings":"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"}

package/dist/esm/check/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview Checks a script source: runs it like a host (a declaration run on zero bars, then a run on bars) and
+ * returns a report an agent or a host can act on: what the script declares (inputs, outputs, strategy), what its outputs
+ * contain (values, warm-up, ranges, signal counts, trades), warnings for the mistakes that give no error (an empty plot,
+ * a signal on every bar or never, an input that changes nothing...), and the result of a spec (the expected inputs,
+ * outputs and signals) and of a reference (expected values per bar). The `oakscript check` command prints it.
+ *
+ * ```ts
+ * import { checkScript } from 'oakscriptjs/check';
+ * const report = checkScript(source, { spec: { overlay: true, outputs: ['Fast', 'Slow'] } });
+ * report.ok; report.errors; report.warnings; report.spec?.items;
+ * ```
+ *
+ * @module check
+ */
+import type { Bar } from '../types/index.js';
+import type { InputConfig } from '../runtime/types.js';
+import { type TestChartOptions } from './harness.js';
+import { type CheckContext, type CheckItem } from './checks.js';
+export { validateSpec, specJsonSchema, SPEC_FIELDS, SPEC_FILE_FIELDS } from './spec.js';
+export { runChecks, signalBars, type CheckContext, type CheckItem, type CheckPlot, type CheckSignal, type SignalBars } from './checks.js';
+export { formatReport, assertCheck } from './format.js';
+export { compileScript, inferTimeframe, rewriteImports, runScript, scriptArguments, syntheticBars, testChart, timeframeSeconds, LIBRARY_PARAMETER, SCRIPT_GLOBALS, SCRIPT_PREFIX, SCRIPT_SUFFIX, TestEngine, wrapSource, type RunScriptOptions, type ScriptRun, type TestChartOptions, } from './harness.js';
+/** Expected count of a signal (a shape, character, arrow, alert condition, background or bar colour) over the bars. */
+export interface SignalSpec {
+    /** At least this many bars with the signal. */
+    min?: number;
+    /** At most this many bars with the signal. */
+    max?: number;
+    /** At least this share of the bars (0 to 1). */
+    minShare?: number;
+    /** At most this share of the bars (0 to 1). */
+    maxShare?: number;
+}
+/** Expected values of a plot. */
+export interface PlotSpec {
+    /** Every value is at least this. */
+    min?: number;
+    /** Every value is at most this. */
+    max?: number;
+    /** The first value comes at this bar index or before (the warm-up). */
+    warmup?: number;
+}
+/** Expected input: the keys are compared when given. */
+export interface InputSpec {
+    type?: InputConfig['type'];
+    defval?: unknown;
+    title?: string;
+    min?: number;
+    max?: number;
+    options?: string[];
+}
+/**
+ * What the user asked for, written before the script: each given entry is checked. Inputs, plots and signals are
+ * found by id or title (case insensitive).
+ */
+export interface CheckSpec {
+    kind?: 'indicator' | 'strategy';
+    title?: string;
+    overlay?: boolean;
+    /** Inputs that must exist, with the expected type, default... */
+    inputs?: Record<string, InputSpec>;
+    /** Outputs that must exist (a title, or a title and a kind: plot, shape, char, arrow, candle, bar, hline, bgcolor, barcolor, alertcondition). */
+    outputs?: Array<string | {
+        title: string;
+        kind?: string;
+    }>;
+    /** Value checks per plot. */
+    plots?: Record<string, PlotSpec>;
+    /** Count checks per signal. */
+    signals?: Record<string, SignalSpec>;
+    /** Number of closed trades of a strategy. */
+    trades?: {
+        min?: number;
+        max?: number;
+    };
+}
+/** Expected values per bar, e.g. the outputs of the Pine script a port follows, on the same bars. */
+export interface CheckReference {
+    /** Bar times (UNIX seconds). */
+    times: number[];
+    /** Expected values per plot id or title, aligned with `times` (NaN or null: na). */
+    columns: Record<string, Array<number | null>>;
+    /** Equal when |a - b| <= tolerance * max(1, |a|, |b|) (default 1e-10), or both na. */
+    tolerance?: number;
+    /** A column without a plot of that id or title is listed as ignored instead of failing (a chart export holds other columns). */
+    ignoreUnknown?: boolean;
+}
+/** A run on edge-case bars (`scenarios: true`): a short history, daily bars, flat prices, no volume, a gap. */
+export interface CheckScenario {
+    name: string;
+    description: string;
+    timeframe: string;
+    bars: () => Bar[];
+}
+export interface CheckOptions extends TestChartOptions {
+    /** Bars of the run (default: 1,500 deterministic synthetic bars of the timeframe). */
+    bars?: Bar[];
+    /** Input values by id (default: the defaults). */
+    inputs?: Record<string, unknown>;
+    spec?: CheckSpec;
+    reference?: CheckReference;
+    /** Compiles the source (default: `new Function`; the CLI compiles with the file name for error lines). */
+    compile?: (source: string) => () => void;
+    /** Wraps each run (the CLI stops a run that takes too long). */
+    run?: <T>(fn: () => T) => T;
+    /** File name of the source, to read the error lines from the stack (`<file>:line:column`). */
+    filename?: string;
+    /** Re-run with each input changed to find inputs that change no output (default true). */
+    inputSweep?: boolean;
+    /** Behaviour checks: called with the outputs of the run per bar (see {@link CheckContext}); their results join the spec items. */
+    checks?: (t: CheckContext) => void;
+    /** Also run on the edge-case bars of {@link SCENARIOS} (or the given ones): their errors fail the check. */
+    scenarios?: boolean | CheckScenario[];
+}
+export type CheckStage = 'syntax' | 'types' | 'declaration' | 'run' | 'timeout' | 'spec' | 'reference' | 'scenario';
+export interface CheckError {
+    stage: CheckStage;
+    message: string;
+    line?: number;
+    column?: number;
+    /** TypeScript error code (stage "types"). */
+    code?: string;
+}
+export interface CheckWarning {
+    code: 'empty-plot' | 'constant-plot' | 'late-start' | 'signal-never' | 'signal-everywhere' | 'one-colour' | 'unused-input' | 'input-error' | 'no-trades' | 'no-output';
+    message: string;
+    /** Output or input title (or id). */
+    target?: string;
+}
+export interface PlotSummary {
+    id: string;
+    title: string;
+    /** Bars with a value (not na). */
+    values: number;
+    /** Bar index of the first value (-1: none). */
+    firstBar: number;
+    min: number | null;
+    max: number | null;
+    /** Values of the last 5 bars (null: na). */
+    last: Array<number | null>;
+    /** Distinct per-bar colours (0: the plot colour is the same on every bar). */
+    colours: number;
+}
+export interface SignalSummary {
+    kind: 'shape' | 'char' | 'arrow' | 'alertcondition' | 'bgcolor' | 'barcolor';
+    id: string;
+    title: string;
+    /** Bars with the signal. */
+    count: number;
+    /** count / number of bars. */
+    share: number;
+    firstBar: number;
+    lastBar: number;
+}
+export interface TradeSummary {
+    entry: string;
+    direction: 'long' | 'short';
+    entryBar: number;
+    entryPrice: number;
+    exitBar: number | null;
+    exitPrice: number | null;
+    profit: number;
+}
+export interface CheckReport {
+    /** No error, no failed spec or reference check. Warnings do not change it. */
+    ok: boolean;
+    bars: {
+        count: number;
+        first: number | null;
+        last: number | null;
+        timeframe: string;
+        synthetic: boolean;
+    };
+    errors: CheckError[];
+    warnings: CheckWarning[];
+    declaration?: {
+        kind: 'indicator' | 'strategy';
+        title: string;
+        shortTitle?: string;
+        overlay: boolean;
+        inputs: Array<Pick<InputConfig, 'id' | 'type' | 'defval' | 'title' | 'min' | 'max' | 'options'>>;
+        outputs: Array<{
+            kind: string;
+            id: string;
+            title: string;
+        }>;
+        strategy?: Record<string, unknown>;
+    };
+    plots: PlotSummary[];
+    signals: SignalSummary[];
+    drawings: {
+        labels: number;
+        lines: number;
+        boxes: number;
+        tables: number;
+        polylines: number;
+        linefills: number;
+    };
+    /** alert() calls of the script (all bars). */
+    alertCalls: number;
+    strategy?: {
+        closedTrades: number;
+        openTrade: boolean;
+        netProfit: number;
+        wins: number;
+        first: TradeSummary[];
+    };
+    /** Spec items and behaviour checks. */
+    spec?: {
+        passed: number;
+        failed: number;
+        items: CheckItem[];
+    };
+    reference?: Array<{
+        column: string;
+        output?: string;
+        /** No plot of this id or title, and `ignoreUnknown` is set. */
+        ignored?: boolean;
+        equal: number;
+        total: number;
+        firstMismatch?: {
+            bar: number;
+            time: number;
+            expected: number | null;
+            actual: number | null;
+        };
+    }>;
+    /** Runs on edge-case bars: their errors (also in `errors`, stage "scenario") and the plots with no value the main run does not have. */
+    scenarios?: Array<{
+        name: string;
+        description: string;
+        bars: number;
+        errors: CheckError[];
+        warnings: CheckWarning[];
+    }>;
+}
+/** Line and column of a script error, from `error.scriptLine` or the `<filename>:line:column` frames of its stack. */
+export declare function errorLocation(error: unknown, filename?: string): {
+    line?: number;
+    column?: number;
+};
+/** Default number of synthetic bars of a check. */
+export declare const CHECK_BARS = 1500;
+/** The edge-case bars of `scenarios: true`. */
+export declare const SCENARIOS: readonly CheckScenario[];
+/**
+ * Checks a script source (the body of a script, as a host runs it): compiles it, runs it on zero bars (the
+ * declarations) and on the bars, and reports its declarations, outputs, warnings and the spec / reference results.
+ * Never throws for a script error: the errors are in the report.
+ */
+export declare function checkScript(source: string, options?: CheckOptions): CheckReport;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/check/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/check/index.ts"],"names":[],"mappings":"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"}