openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/engine/session/record.ts

@@ -0,0 +1,191 @@
+/**
+ * The per-bar session facts, derived from the instrument record.
+ *
+ * **The session is a range of hours in the instrument record and nothing else**
+ * (`host-interface.md` 4.3). A host states `start`, `end` and the days it opens
+ * on, once, at load; the per-bar facts follow from those hours, the bar's own
+ * time and the instrument's timezone. The host is never asked whether a session
+ * begins on a bar, because `language.md` 7.2 fixes the facts a host states
+ * about an execution at four and `host-interface.md` 6.1 says an engine must
+ * not ask a host for one of the rest. Two engines built from those pages
+ * therefore anchor a session study on the same bar, which is the whole reason
+ * the line between stated and derived is drawn where it is.
+ *
+ * **`isFirstBar` is the first bar delivered inside the hours.** A venue that
+ * opened late still has a first bar, and a study anchored to the session has to
+ * start on it; a rule that waited for the scheduled open would anchor nothing
+ * at all on a day trading began a minute late.
+ *
+ * **`isLastBar` is the last bar of the schedule**, which is the fact that earns
+ * the field its place: it is true even when trading stopped early, so a
+ * strategy that must be flat by the close acts on it rather than on the
+ * appearance of a new bar, which arrives too late. That is a bar slot measured
+ * against the scheduled close, so it needs the interval, and a host that states
+ * none leaves it absent rather than answered by the bar spacing, which the
+ * specification does not promise is uniform.
+ *
+ * **Absence, never a guess.** A host that states no session leaves both facts
+ * absent, which is what 4.1's record says a script sees: absent, and the per-bar
+ * session facts absent with it. Absence is a value a script can test, and a
+ * guessed session start would anchor every session study in this language to a
+ * minute nobody chose.
+ *
+ * **A record that contradicts itself is refused instead**, at load, by
+ * `recordProblem` below. A session with no zone to read its wall clock in, or
+ * one spelled in a form the record does not take, is a host that believes it
+ * stated a session, and answering that with the same absence an honest record
+ * gives is how a host loses every session study and is told nothing.
+ */
+import { fieldsIn } from '../../stdlib/index.js';
+import { standingIn } from './hours.js';
+import type { Hours, Standing } from './hours.js';
+
+/** The instrument's trading session, as `host-interface.md` 4.3 prints it. */
+export interface SessionHours {
+  /** A wall clock time, `"HH:MM"`, read in the instrument's timezone. */
+  readonly start: string;
+  /** The same, where `"24:00"` is midnight at the end of the day. */
+  readonly end: string;
+  /** Monday as 1 through Sunday as 7, or nothing for every day. */
+  readonly days?: readonly number[];
+}
+
+/** What a bar's session comes to, absent where the record cannot say. */
+export interface SessionFacts {
+  readonly isFirstBar: boolean | null;
+  readonly isLastBar: boolean | null;
+}
+
+/** No session stated, so neither fact has an answer. */
+export const NO_SESSION: SessionFacts = { isFirstBar: null, isLastBar: null };
+
+/** The bar falls in no session, which is an answer rather than an absence. */
+const BETWEEN: SessionFacts = { isFirstBar: false, isLastBar: false };
+
+/** `"HH:MM"`, where `"24:00"` is midnight at the end of the day. */
+const CLOCK = /^(\d{2}):(\d{2})$/;
+
+function clockMinutes(text: unknown): number | null {
+  if (typeof text !== 'string') return null;
+  const parts = CLOCK.exec(text);
+  if (parts === null) return null;
+  const hour = Number(parts[1]);
+  const minute = Number(parts[2]);
+  if (hour > 24 || minute > 59) return null;
+  if (hour === 24 && minute !== 0) return null;
+  return hour * 60 + minute;
+}
+
+/** The record's session as hours, or nothing when the host stated none. */
+function hoursOf(stated: SessionHours | undefined): Hours | null {
+  if (stated === undefined || stated === null) return null;
+  const from = clockMinutes(stated.start);
+  const to = clockMinutes(stated.end);
+  if (from === null || to === null) return null;
+  const listed = stated.days;
+  return { from, to, days: Array.isArray(listed) ? [...listed] : null };
+}
+
+/**
+ * What the record is missing before any session fact can be read from it.
+ *
+ * `host-interface.md` 4.1 marks every fact here optional and 4.3 says what a
+ * script sees when the session is one of them: absence, which a script can test.
+ * That is the answer for a host that schedules no session, and it is not the
+ * answer for the three records below, each of which is a host that believes it
+ * stated one:
+ *
+ * - **A session and no timezone.** `start` and `end` are wall clock, so a
+ *   window with no zone to read it in is not a window. Nothing about the record
+ *   says which hours were meant, and every session study on that host draws
+ *   nothing.
+ * - **A session whose clock times are not `"HH:MM"`.** `"9:00"` is the spelling
+ *   a host writes first and the one the record does not take.
+ * - **Days outside one to seven.** Monday is 1 (`stdlib.md` 12.2), so a host
+ *   numbering Sunday as 0 states a week the instrument never opens in.
+ *
+ * Each of the three is reported at load rather than answered with absence,
+ * because absence there is indistinguishable from the honest case and the honest
+ * case is the one a reader will assume. This decides nothing about what a bare
+ * read of an instrument fact returns, which is issue 0002 and is open: a record
+ * the host contradicts itself in is a different question from a fact it did not
+ * state.
+ */
+export function recordProblem(
+  stated: SessionHours | undefined,
+  zone: string | null,
+): string | undefined {
+  if (zone !== null && fieldsIn(0, zone) === null) return 'a timezone the calendar can read';
+  if (stated === undefined || stated === null) return undefined;
+  if (zone === null) return 'a timezone, which the session it states is read in';
+  if (hoursOf(stated) === null) return 'a session whose start and end are spelled HH:MM';
+  const days = stated.days;
+  if (days === undefined || days === null) return undefined;
+  const numbered = (one: unknown): boolean =>
+    typeof one === 'number' && Number.isInteger(one) && one >= 1 && one <= 7;
+  if (days.length === 0 || !days.every(numbered)) {
+    return 'session days numbered 1 to 7, where Monday is 1';
+  }
+  return undefined;
+}
+
+/** Reads one run's session facts, one bar at a time. */
+export interface SessionReader {
+  /** This bar's facts, given the bar before it, or nothing before it. */
+  factsAt(time: number | null, previousTime: number | null): SessionFacts;
+}
+
+const NOTHING: SessionReader = { factsAt: () => NO_SESSION };
+
+/**
+ * The reader for one run.
+ *
+ * Built once, because the instrument record is read once at load and is
+ * constant for the whole run (`host-interface.md` 4.4). A fact that changed
+ * mid-run would make the first bars of a chart disagree with the rest of it.
+ */
+export function sessionReader(
+  stated: SessionHours | undefined,
+  zone: string | null,
+  barMinutes: number | null,
+): SessionReader {
+  const hours = hoursOf(stated);
+  if (hours === null || zone === null) return NOTHING;
+
+  // The bar before this one was this bar last time, so its reading is kept
+  // rather than read twice. Memoisation and nothing else: the answer for an
+  // instant is the same answer every time, and clearing it between two bars
+  // would change how long a chart took and nothing else.
+  let priorTime: number | null = null;
+  let priorReading: Standing | null = null;
+
+  const readingAt = (time: number | null): Standing | null => {
+    if (time === null || !Number.isFinite(time)) return null;
+    if (time === priorTime) return priorReading;
+    const civil = fieldsIn(time, zone);
+    return civil === null ? null : standingIn(hours, civil);
+  };
+
+  return {
+    factsAt(time: number | null, previousTime: number | null): SessionFacts {
+      const here = readingAt(time);
+      // Read before the slot is written over, so the bar before this one is the
+      // reading this bar's own call left behind.
+      const before = here !== null && here.inside ? readingAt(previousTime) : null;
+      priorTime = time;
+      priorReading = here;
+      if (here === null) return NO_SESSION;
+      if (!here.inside) return BETWEEN;
+      // A bar with nothing before it inside the same session is the first of
+      // it, which includes the oldest bar of a chart that opens mid-session: a
+      // study anchored to the session has to start somewhere, and the left edge
+      // of the data is the only honest place.
+      const opened =
+        before === null || !before.inside || before.openingDay !== here.openingDay;
+      return {
+        isFirstBar: opened,
+        isLastBar: barMinutes === null ? null : here.remaining <= barMinutes,
+      };
+    },
+  };
+}

package/src/core/engine/session/spec.ts

@@ -0,0 +1,45 @@
+/**
+ * `session.isIn(spec, zone)`: the session range spec of `stdlib.md` 12.5.
+ *
+ * The spec is a string a script writes: `"0915-1530"`, with an optional day
+ * list after a colon, `"0915-1530:12345"`. Days number Monday as 1 through
+ * Sunday as 7, matching `date.dayOfWeek`. This file is the spelling and nothing
+ * else: what the hours then mean is `hours.ts`, which the instrument's own
+ * session reads through as well, so a script's range and an instrument's
+ * session cannot come to differ about midnight or about a day list.
+ *
+ * A malformed spec is OS3008 at compile time when it is a literal. A computed
+ * one that is malformed is absence here rather than a refusal: the alternative
+ * would stop a chart on a string the script built on one bar out of forty
+ * thousand, and absence is a value a script can test.
+ */
+import type { Civil } from '../../stdlib/index.js';
+import { standingIn } from './hours.js';
+import type { Hours } from './hours.js';
+
+/** `HHMM-HHMM` with an optional `:` and a run of day digits. */
+const SPEC = /^(\d{2})(\d{2})-(\d{2})(\d{2})(?::([1-7]{1,7}))?$/;
+
+function parse(spec: string): Hours | null {
+  const parts = SPEC.exec(spec);
+  if (parts === null) return null;
+  const fromHour = Number(parts[1]);
+  const fromMinute = Number(parts[2]);
+  const toHour = Number(parts[3]);
+  const toMinute = Number(parts[4]);
+  // "2400" is midnight at the end of the day, and it is the one hour past 23
+  // the spec allows.
+  if (fromHour > 23 || fromMinute > 59 || toMinute > 59) return null;
+  if (toHour > 24 || (toHour === 24 && toMinute !== 0)) return null;
+  const listed = parts[5];
+  const days = listed === undefined ? null : [...listed].map((one) => Number(one));
+  return { from: fromHour * 60 + fromMinute, to: toHour * 60 + toMinute, days };
+}
+
+/** Whether a bar's wall clock reading falls inside the hours a spec names. */
+export function sessionHolds(spec: string | null, at: Civil | null): boolean | null {
+  if (spec === null || at === null) return null;
+  const hours = parse(spec);
+  if (hours === null) return null;
+  return standingIn(hours, at).inside;
+}

package/src/core/engine/timeframe.ts

@@ -0,0 +1,161 @@
+/**
+ * Timeframe strings, and the buckets a read folds bars into.
+ *
+ * `stdlib.md` section 15.2 fixes the spelling: a count and a unit, with the
+ * unit letters case sensitive so `"1M"` is one month and `"1m"` one minute, and
+ * a bare number read as minutes because that is the form an interval input
+ * supplies. This file is that grammar and the arithmetic that follows from it,
+ * and nothing else.
+ *
+ * **A bucket is named by a key rather than by a range**, because a key is one
+ * integer per bar and a range is two comparisons and an edge case. Two bars
+ * belong to the same requested bar exactly when their open instants give the
+ * same key, and a bucket has begun on the first bar whose key is new. Every
+ * boundary question in `requests.ts` reduces to that one comparison, which is
+ * what keeps the off-by-one out of the fold.
+ *
+ * **The two families are keyed differently, and the specification says why.**
+ * An intraday request is folded by counting, so its key is the instant divided
+ * by the period: buckets fall on the same boundaries for every engine, a
+ * session gap moves nothing, and a chart whose bars are not evenly spaced still
+ * folds. A day, week or month request is folded by the calendar, so its key is
+ * a civil date read in the instrument's timezone. That is OS6015's distinction,
+ * which exempts the calendar units from the whole multiple rule for exactly
+ * this reason.
+ *
+ * **A calendar bucket with no timezone has no key.** A host states the zone or
+ * it does not, and an engine that quietly folded days in UTC would put a day
+ * boundary in the middle of a session for most of the world and look right. It
+ * is the same answer `library/dates.ts` gives for the same question: a host that
+ * states no timezone leaves the call absent rather than answered in a zone
+ * nobody chose. A read in that position is absent on every bar of the run, so
+ * `request-plan.ts` gives it the reason `req.error` reports: an absence with no
+ * explanation is the one failure a trader cannot get past on their own.
+ */
+import { dayNumber, fieldsIn } from '../stdlib/index.js';
+
+export type TimeframeUnit = 'm' | 'h' | 'D' | 'W' | 'M';
+
+export interface Timeframe {
+  readonly count: number;
+  readonly unit: TimeframeUnit;
+  /** The string as it was written, for a diagnostic that has to name it. */
+  readonly text: string;
+}
+
+/** The grammar of 15.2. A bare number is minutes, which is the interval form. */
+const WRITTEN = /^([0-9]+)(m|h|D|W|M)?$/;
+
+const MINUTE = 60_000;
+
+/** The nominal length of one unit, in minutes, for ordering two timeframes. */
+const NOMINAL: Readonly<Record<TimeframeUnit, number>> = {
+  m: 1,
+  h: 60,
+  D: 1440,
+  W: 10_080,
+  M: 43_200,
+};
+
+export function parseTimeframe(text: string): Timeframe | undefined {
+  const match = WRITTEN.exec(text.trim());
+  if (match === null) return undefined;
+  const count = Number(match[1]);
+  if (!Number.isInteger(count) || count < 1) return undefined;
+  return { count, unit: (match[2] ?? 'm') as TimeframeUnit, text };
+}
+
+/** Whether this timeframe is folded by counting rather than by the calendar. */
+export function isIntraday(timeframe: Timeframe): boolean {
+  return timeframe.unit === 'm' || timeframe.unit === 'h';
+}
+
+/** Minutes one bar covers, for an intraday timeframe only. */
+export function minutesOf(timeframe: Timeframe): number | undefined {
+  return isIntraday(timeframe) ? timeframe.count * NOMINAL[timeframe.unit] : undefined;
+}
+
+/**
+ * One timeframe's length in minutes, with a month treated as thirty days.
+ *
+ * Two uses and neither of them folds anything: ordering two timeframes, which
+ * is "is the request finer than the chart" and therefore OS6002, and sizing the
+ * range of history a host is asked to fetch, which is a floor. A month is not a
+ * fixed number of minutes, and where a bucket actually begins is the calendar's
+ * job below.
+ */
+export function nominalMinutes(timeframe: Timeframe): number {
+  return timeframe.count * NOMINAL[timeframe.unit];
+}
+
+/**
+ * Minutes one bar of a chart's own interval covers, or nothing where the host
+ * stated no interval this engine can read.
+ *
+ * A month is counted at its nominal length here, which is the answer the
+ * session facts need and not a claim about a calendar: any bar of a day or more
+ * spans a whole session whatever the exact figure, so every number past the
+ * length of a session gives those facts the same answer.
+ */
+export function barMinutesOf(interval: string | undefined): number | null {
+  if (interval === undefined) return null;
+  const timeframe = parseTimeframe(interval);
+  return timeframe === undefined ? null : nominalMinutes(timeframe);
+}
+
+/**
+ * The bucket an instant falls in, or nothing when no key can be worked out.
+ *
+ * Nothing comes back for a calendar unit with no zone, and for an instant that
+ * is not a finite number. Both leave the read absent rather than folded into a
+ * bucket the engine invented.
+ */
+export function bucketKeyOf(
+  instant: number,
+  timeframe: Timeframe,
+  zone: string | null,
+): number | undefined {
+  if (!Number.isFinite(instant)) return undefined;
+  const minutes = minutesOf(timeframe);
+  if (minutes !== undefined) return Math.floor(instant / (minutes * MINUTE));
+
+  if (zone === null) return undefined;
+  const civil = fieldsIn(instant, zone);
+  if (civil === null) return undefined;
+
+  if (timeframe.unit === 'M') {
+    return Math.floor((civil.year * 12 + (civil.month - 1)) / timeframe.count);
+  }
+  const days = dayNumber(civil.year, civil.month, civil.day);
+  if (timeframe.unit === 'D') return Math.floor(days / timeframe.count);
+  // 1970-01-01 was a Thursday, so shifting by three puts a Monday at the start
+  // of week zero, which is the week start `stdlib.md` 12.2 fixes.
+  return Math.floor(Math.floor((days + 3) / 7) / timeframe.count);
+}
+
+/** Why a requested timeframe cannot be folded onto the chart's, if it cannot. */
+export type FoldRefusal =
+  | { readonly code: 'OS6002' }
+  | { readonly code: 'OS6015'; readonly suggestion: string };
+
+/**
+ * Whether the chart's bars can be folded into the requested ones.
+ *
+ * Two refusals and no third. A request finer than the chart is OS6002, because
+ * folding cannot invent bars that were never loaded, and an intraday request
+ * that is not a whole multiple of the chart's is OS6015, because an intraday
+ * bucket is counted rather than dated and a bucket boundary that fell inside a
+ * chart bar would put part of one bar in two requested bars. A day, week or
+ * month request is dated, so the multiple rule does not apply to it.
+ */
+export function foldRefusal(
+  requested: Timeframe,
+  chart: Timeframe,
+): FoldRefusal | undefined {
+  if (nominalMinutes(requested) < nominalMinutes(chart)) return { code: 'OS6002' };
+  const wanted = minutesOf(requested);
+  const have = minutesOf(chart);
+  if (wanted === undefined || have === undefined) return undefined;
+  if (wanted % have === 0) return undefined;
+  return { code: 'OS6015', suggestion: `${Math.ceil(wanted / have) * have}` };
+}

package/src/core/engine/types.ts

@@ -0,0 +1,47 @@
+/**
+ * The compiled program, as the engine sees it.
+ *
+ * The shape is the emitter's, and deliberately not a second declaration of it.
+ * `compiled-program.md` is the contract, `emit/program.ts` is that contract
+ * written in types, and an engine that declared its own copy would be the first
+ * place the two could drift: a field renamed on one side and not the other
+ * would compile on both and fail at a customer's.
+ *
+ * Nothing is imported at run time. Every import here is a type, so the engine
+ * carries no dependency on the emitter in a build: a host that only runs
+ * compiled programs never loads a line of the compiler.
+ */
+export type {
+  Alert,
+  Band,
+  CallSite,
+  CandleChannels,
+  Cell,
+  Channel,
+  Colour,
+  CompiledFunction,
+  CompiledInput,
+  CompiledProgram,
+  Constant,
+  Debug,
+  Field,
+  Grid,
+  InputReference,
+  Instruction,
+  Level,
+  Library,
+  LibraryFunction,
+  Limits,
+  Loop,
+  Marker,
+  Meta,
+  Outputs,
+  Plot,
+  Position,
+  Register,
+  Request,
+  RequestBody,
+  RequestField,
+  RequestInput,
+  StateRegion,
+} from '../emit/index.js';