openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/index.ts

@@ -1,11 +1,22 @@
 /**
- * OpenScript, the compiler tier.
+ * OpenScript, the compiler and the engine.
  *
- * This is the whole of what a host needs to turn a script into a compiled
- * program, and it knows nothing about a chart, an editor or a broker. It
- * imports no package and touches no browser global, so the same file runs in a
- * worker, on a server and inside somebody else's application under a content
- * security policy that forbids turning text into code.
+ * This is the whole of what a host needs to take a script and produce values,
+ * and it knows nothing about a chart, an editor or a broker. It imports no
+ * package and touches no browser global, so the same file runs in a worker, on
+ * a server and inside somebody else's application under a content security
+ * policy that forbids turning text into code.
+ *
+ * Three things a host does, and the names that do them:
+ *
+ *     sourceFile, parse, check, emit   source text becomes a compiled program
+ *     load                             a program is verified and made runnable
+ *     Engine.run, Engine.append        it runs over bars, and values come out
+ *
+ * Every name below is a promise to somebody who is not in this repository, so
+ * the surface is a decision rather than everything the modules hold: a pass, a
+ * table or an instruction stays behind its module's door, and a host never has
+ * to reach past this file to compile or run a script.
  *
  * The tiers above it are separate entry points, so a host that wants only this
  * one never loads the editor intelligence or an adapter.
@@ -144,4 +155,115 @@ export {
 export { lex } from './lex/index.js';
 
 export { parse, parseTokens } from './parse/index.js';
+
+export type {
+  Binding,
+  BindingKind,
+  CheckedCall,
+  CheckedDeclaration,
+  CheckedFunction,
+  CheckedInput,
+  CheckedOutput,
+  CheckedRequest,
+  CheckedScript,
+  HandleKind,
+  InputKind,
+  LibraryEntry,
+  LibraryParameter,
+  ObjectKind,
+  RequestMode,
+  Storage,
+  Type,
+  ValueKind,
+  WarmupRule,
+  Warmup,
+} from './check/index.js';
+export {
+  BAR_ZERO,
+  HANDLE_KINDS,
+  NAMESPACES,
+  OBJECT_KINDS,
+  STRATEGY_NAMESPACES,
+  VALUE_KINDS,
+  accepts,
+  allOf,
+  arrayOf,
+  atBar,
+  atLeastBar,
+  check,
+  delayed,
+  earlier,
+  elementOf,
+  isLibraryName,
+  isNamespace,
+  isNever,
+  isSeries,
+  join,
+  later,
+  libraryEntries,
+  libraryNames,
+  membersOf,
+  sameType,
+  seriesOf,
+  typeText,
+} from './check/index.js';
+export { REQUEST_NAMES } from './check/index.js';
 export { COMPILED_FORMAT_VERSION, VERSION } from './version/index.js';
+
+/**
+ * The emitter: a checked script becomes the compiled program.
+ *
+ * The program is plain data, so a host may store it, send it, and run it here
+ * or on an engine somebody else wrote from the specification.
+ *
+ * `canonicalise` is the encoding the two hashes are taken over and the bytes
+ * that travel. A host that records the source hash and the program hash beside
+ * a result can later prove an engine upgrade did not change it, which is what
+ * `compiled-program.md` 9.5 promises.
+ */
+export { emit } from './emit/index.js';
+export type { EmitOptions, EmitResult } from './emit/index.js';
+export type { CompiledProgram } from './emit/index.js';
+export { canonicalise, programHash, sourceHash } from './emit/index.js';
+
+/**
+ * The engine: a program in, one bar at a time, values out.
+ *
+ * `load` verifies the program in full before a bar executes and answers with a
+ * diagnostic rather than an exception, because a host runs many scripts in one
+ * process and one failing script must take nothing else down. `verify` is that
+ * same check on its own, for a host that keeps compiled programs and wants to
+ * refuse a bad one when it arrives rather than when it is first drawn.
+ *
+ * `capabilitiesFor` and `LANGUAGE_VERSIONS` are this engine's half of the
+ * compatibility statement in 9.1, beside `COMPILED_FORMAT_VERSION` above.
+ */
+export { load } from './engine/index.js';
+export type { BarResult, Engine, LoadOptions, LoadResult, RunResult } from './engine/index.js';
+export type {
+  BarState,
+  EffectRoute,
+  EngineHost,
+  HostBar,
+  Instrument,
+  PendingEffect,
+  RoutedEffect,
+} from './engine/index.js';
+/**
+ * The order boundary: what a strategy sends, what a host reports back, and the
+ * ledger the two fold into (`host-interface.md` 7, `stdlib.md` 17.7).
+ */
+export type {
+  FrameOutcome,
+  Identity,
+  LedgerRow,
+  OrderFrame,
+  OrderIntent,
+  OrderStatus,
+} from './engine/index.js';
+export { DEFAULT_LIMITS } from './engine/index.js';
+export type { EngineLimits } from './engine/index.js';
+export { isAbsent } from './engine/index.js';
+export type { Value } from './engine/index.js';
+export { LANGUAGE_VERSIONS, capabilitiesFor, verify } from './engine/index.js';
+export type { VerifyOptions, VerifyResult } from './engine/index.js';

package/src/core/parse/expressions.ts

@@ -303,7 +303,7 @@ function parsePrimary(cursor: Cursor): Expression {
       // not read, and the next thing the reader is told is that a bracket they
       // plainly closed was never closed.
       if (isMeantAsAName(token.kind)) {
-        const name = takeName(cursor);
+        const name = takeName(cursor, true);
         return makeNode('nameReference', name.span, { name: name.text });
       }
       return expressionExpected(cursor);

package/src/core/parse/names.ts

@@ -76,6 +76,26 @@ function unreservedNear(word: string): string {
   return `${word}Value`;
 }
 
+/**
+ * The library spelling of a reserved word somebody wrote as a call.
+ *
+ * `bool` and `number` name types, and the two conversions to those types have to
+ * be called by a name, which a reserved word is not. For one release the library
+ * published them under the type names anyway: the checker called them functions,
+ * the lexer called the same words reserved, and every spelling a reader could
+ * write was refused with advice to rename a variable they had not declared. The
+ * conversions are `toBool` and `toNumber`, and this is the table that says so to
+ * whoever wrote the natural thing.
+ *
+ * It is two entries because two names collided, not because a rule needs a list:
+ * a library name is never a reserved word, and `tests/unit/library-names.test.ts`
+ * fails the build if one ever is again.
+ */
+const CALLED_INSTEAD: ReadonlyMap<string, string> = new Map([
+  ['bool', 'toBool'],
+  ['number', 'toNumber'],
+]);
+
 /** No word where one was required, which leaves the statement without its subject. */
 function missingWord(cursor: Cursor): Name {
   const hole = cursor.holeSpan();
@@ -91,16 +111,23 @@ function missingWord(cursor: Cursor): Name {
  * The word is taken either way. A script that named something `type` still
  * meant to declare it, and every later diagnostic about that name is more use
  * to the reader than a hole where the declaration should have been.
+ *
+ * `asValue` is set by the one reader that takes a word from where a value
+ * belongs, and it is what lets the fix be true of the program in front of it. A
+ * word with an argument list after it is a call, and a reader who wrote one
+ * wants the name the library really publishes; the same word being declared or
+ * assigned to wants a name of their own, and the library's would collide.
  */
-export function takeName(cursor: Cursor): Name {
+export function takeName(cursor: Cursor, asValue = false): Name {
   const token = cursor.token;
   if (!isWordKind(token.kind)) return missingWord(cursor);
 
   cursor.advance();
   if (token.kind !== 'identifier') {
+    const called = asValue && cursor.kind === '(' ? CALLED_INSTEAD.get(token.text) : undefined;
     cursor.report('OS1019', token.span, {
       word: token.text,
-      suggestion: unreservedNear(token.text),
+      suggestion: called ?? unreservedNear(token.text),
     });
   }
   return makeNode('name', token.span, { text: token.text });

package/src/core/stdlib/averages/exponential.ts

@@ -0,0 +1,119 @@
+/**
+ * The exponential family: `ema`, `rma`, `dema` and `tema`.
+ *
+ * All four share one seeding rule, which `stdlib.md` section 4 states for `ema`
+ * and then refers `rma` to: the average is seeded on bar `len - 1` with the
+ * simple average of those `len` values, and is absent before it. Seeding from
+ * bar 0 instead, which is common and cheaper, draws a line where there should
+ * be a gap and stays materially wrong until the seed decays away. The seeding
+ * itself is `smoothed` in `lookback.ts`, which every seeded average here and in
+ * the studies built on them goes through.
+ *
+ * **Two arrangements, deliberately.** `ema` steps as `value * k + prev * (1 - k)`
+ * and `rma` steps as `(prev * (len - 1) + value) / len`. Those are the same
+ * function in exact arithmetic and two different numbers in binary64, and each
+ * is the arrangement its name has always meant. Writing `rma` as a weight of
+ * `1 / len` in `ema`'s shape would disagree in the last bits with every
+ * implementation of the classic oscillators, which is precisely what this
+ * project treats as a release blocker.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, smoothed, tailOf } from '../values/index.js';
+
+/** `ema(src, len)`: exponential mean, weight `2 / (len + 1)`, from bar `len - 1`. */
+export function emaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  const weight = 2 / (len + 1);
+  const rest = 1 - weight;
+  return smoothed(state, key, len, value, (previous, next) => next * weight + previous * rest);
+}
+
+/** `ema(src, len)` as a tail. */
+export function emaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => emaStep(state, 'e', value, len));
+}
+
+/** `ema(src, len)` over a whole series. */
+export function ema(src: Series, len: number): Value[] {
+  return fold(emaTail(len), src);
+}
+
+/** `rma(src, len)`: the smoothing the classic oscillators use, from bar `len - 1`. */
+export function rmaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  return smoothed(state, key, len, value, (previous, next) => (previous * (len - 1) + next) / len);
+}
+
+/** `rma(src, len)` as a tail. */
+export function rmaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => rmaStep(state, 'r', value, len));
+}
+
+/** `rma(src, len)` over a whole series. */
+export function rma(src: Series, len: number): Value[] {
+  return fold(rmaTail(len), src);
+}
+
+/**
+ * `dema(src, len)`: `2 * ema - ema(ema)`, from bar `2 * len - 2`.
+ *
+ * The second average is fed the first one's output, absences and all, so it
+ * seeds on the first `len` values the first average produced. That is where the
+ * declared warmup comes from rather than being asserted alongside it.
+ */
+export function demaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const once = emaStep(state, `${key}a`, value, len);
+  const twice = emaStep(state, `${key}b`, once, len);
+  if (!isPresent(once) || !isPresent(twice)) return NONE;
+  return result(2 * once - twice);
+}
+
+/** `dema(src, len)` as a tail. */
+export function demaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => demaStep(state, 'e', value, len));
+}
+
+/** `dema(src, len)` over a whole series. */
+export function dema(src: Series, len: number): Value[] {
+  return fold(demaTail(len), src);
+}
+
+/** `tema(src, len)`: `3 * e1 - 3 * e2 + e3`, from bar `3 * len - 3`. */
+export function temaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const once = emaStep(state, `${key}a`, value, len);
+  const twice = emaStep(state, `${key}b`, once, len);
+  const thrice = emaStep(state, `${key}c`, twice, len);
+  if (!isPresent(once) || !isPresent(twice) || !isPresent(thrice)) return NONE;
+  // Left to right, as written: 3 * e1, less 3 * e2, plus e3.
+  return result(3 * once - 3 * twice + thrice);
+}
+
+/** `tema(src, len)` as a tail. */
+export function temaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => temaStep(state, 'e', value, len));
+}
+
+/** `tema(src, len)` over a whole series. */
+export function tema(src: Series, len: number): Value[] {
+  return fold(temaTail(len), src);
+}

package/src/core/stdlib/averages/index.ts

@@ -0,0 +1,45 @@
+export type { Weighted } from './simple.js';
+export {
+  sma,
+  smaStep,
+  smaTail,
+  swma,
+  swmaStep,
+  swmaTail,
+  vwma,
+  vwmaStep,
+  vwmaTail,
+  wma,
+  wmaStep,
+  wmaTail,
+} from './simple.js';
+
+export {
+  dema,
+  demaStep,
+  demaTail,
+  ema,
+  emaStep,
+  emaTail,
+  rma,
+  rmaStep,
+  rmaTail,
+  tema,
+  temaStep,
+  temaTail,
+} from './exponential.js';
+
+export {
+  alma,
+  almaStep,
+  almaTail,
+  hma,
+  hmaStep,
+  hmaTail,
+  linreg,
+  linregStep,
+  linregTail,
+} from './shaped.js';
+
+export type { MaType } from './select.js';
+export { isMaType, ma, maStep, maTail } from './select.js';

package/src/core/stdlib/averages/select.ts

@@ -0,0 +1,71 @@
+/**
+ * `ma(src, len, type)`: one call whose shape a select input can switch.
+ *
+ * The point of it is that a study can offer its user a choice of average
+ * without the script branching six ways, and without the six branches each
+ * owning their own state. One call site, one state region, one line on the
+ * chart.
+ *
+ * The step takes a source paired with its volume because one of the types is
+ * volume weighted. A caller that will never select that type passes absence for
+ * the volume and loses nothing.
+ *
+ * **Each type keeps its own corner of the region.** The key carries the type
+ * name, so a run that switched type halfway would start the new average from
+ * its own warmup rather than from whatever the old one had left in the record.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, tailOf } from '../values/index.js';
+
+import type { Weighted } from './simple.js';
+import { smaStep, vwmaStep, wmaStep } from './simple.js';
+import { emaStep, rmaStep } from './exponential.js';
+import { hmaStep } from './shaped.js';
+
+/** The averages `ma` can be switched to, as `stdlib.md` section 4 lists them. */
+export type MaType = 'sma' | 'ema' | 'wma' | 'rma' | 'hma' | 'vwma';
+
+const TYPES: readonly string[] = ['sma', 'ema', 'wma', 'rma', 'hma', 'vwma'];
+
+/** Whether a string names one of the six averages `ma` accepts. */
+export function isMaType(name: string | null): name is MaType {
+  return name !== null && TYPES.includes(name);
+}
+
+/**
+ * `ma(src, len, type)`, with the warmup of whichever type was named.
+ *
+ * An unrecognised type is absence throughout, not a silent fall back to the
+ * simple mean. A study that quietly drew a different average from the one its
+ * settings say would be wrong in a way nobody could see.
+ */
+export function maStep(
+  state: StateRecord,
+  key: string,
+  input: Weighted,
+  len: number | null,
+  type: MaType | null,
+): Value {
+  if (type === null) return NONE;
+  const mine = `${key}${type}`;
+  if (type === 'vwma') return vwmaStep(state, mine, input, len);
+  if (type === 'sma') return smaStep(state, mine, input.src, len);
+  if (type === 'ema') return emaStep(state, mine, input.src, len);
+  if (type === 'wma') return wmaStep(state, mine, input.src, len);
+  if (type === 'rma') return rmaStep(state, mine, input.src, len);
+  if (type === 'hma') return hmaStep(state, mine, input.src, len);
+  return NONE;
+}
+
+/** `ma(src, len, type)` as a tail. */
+export function maTail(len: number, type: MaType): Tail<Weighted, Value> {
+  return tailOf((state, input: Weighted) => maStep(state, 'q', input, len, type));
+}
+
+/** `ma(src, len, type)` over a whole series. */
+export function ma(src: Series, volume: Series, len: number, type: MaType): Value[] {
+  return fold(
+    maTail(len, type),
+    src.map((value, index) => ({ src: value, volume: volume[index] ?? NONE })),
+  );
+}

package/src/core/stdlib/averages/shaped.ts

@@ -0,0 +1,161 @@
+/**
+ * The averages with a shape to them: `hma`, `alma` and `linreg`.
+ *
+ * Each one is a weighted lookback like `wma`, and each accumulates oldest bar
+ * first, in index order, for the reason `lookback.ts` gives.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import {
+  NONE,
+  fold,
+  isLength,
+  isPresent,
+  result,
+  ring,
+  tailOf,
+} from '../values/index.js';
+import { roundHalfAway } from '../maths/index.js';
+
+import { wmaStep } from './simple.js';
+
+/**
+ * `hma(src, len)`: from bar `len + round(sqrt(len)) - 2`.
+ *
+ * `wma` of twice the half length average less the full length one, smoothed
+ * again over the square root of the length.
+ *
+ * **The half length is not stated.** `stdlib.md` section 4 fixes the outer
+ * length as `round(sqrt(len))`, which the declared warmup confirms, and says
+ * nothing about the inner one. `floor(len / 2)` is used here, held at a minimum
+ * of 1 so a length of 1 or 2 still has a lookback, and the declared warmup holds
+ * for any inner length at or below `len`, so nothing in the warmup column
+ * settles it. This is recorded as a gap rather than presented as a reading.
+ */
+export function hmaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  const half = Math.max(1, Math.floor(len / 2));
+  const outer = Math.max(1, roundHalfAway(Math.sqrt(len)));
+  const near = wmaStep(state, `${key}f`, value, half);
+  const far = wmaStep(state, `${key}s`, value, len);
+  const raw = isPresent(near) && isPresent(far) ? result(2 * near - far) : NONE;
+  return wmaStep(state, `${key}o`, raw, outer);
+}
+
+/** `hma(src, len)` as a tail. */
+export function hmaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => hmaStep(state, '', value, len));
+}
+
+/** `hma(src, len)` over a whole series. */
+export function hma(src: Series, len: number): Value[] {
+  return fold(hmaTail(len), src);
+}
+
+/**
+ * `alma(src, len, offset, sigma)`: the Gaussian weighted mean, from bar `len - 1`.
+ *
+ * `offset` slides the kernel's peak between lag and smoothness and `sigma` sets
+ * how sharply it falls away.
+ *
+ * The kernel depends only on the position in the lookback, so it could be built
+ * once; it is rebuilt each bar instead, because the region 2.11 requires holds
+ * numbers and queues and not a cached array of weights, and a step that reads
+ * its own arguments every bar is the only form an engine can drive. The
+ * accumulation is over the lookback in index order either way, so the number is
+ * the same one.
+ */
+export function almaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  offset: number | null,
+  sigma: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || offset === null || sigma === null) return NONE;
+  if (!lookback.complete()) return NONE;
+  if (!(sigma > 0) || !isLength(len)) return NONE;
+  const peak = offset * (len - 1);
+  const spread = len / sigma;
+  const weights: number[] = [];
+  let norm = 0;
+  // Index order: position 0 is the oldest bar in the lookback.
+  for (let position = 0; position < len; position += 1) {
+    const gap = position - peak;
+    const weight = Math.exp(-(gap * gap) / (2 * spread * spread));
+    weights.push(weight);
+    norm += weight;
+  }
+  if (norm === 0) return NONE;
+  let total = 0;
+  for (let position = 0; position < len; position += 1) {
+    total += (lookback.at(len - 1 - position) as number) * (weights[position] as number);
+  }
+  return result(total / norm);
+}
+
+/** `alma(src, len, offset, sigma)` as a tail. */
+export function almaTail(len: number, offset = 0.85, sigma = 6): Tail<Value, Value> {
+  return tailOf((state, value: Value) => almaStep(state, 'q', value, len, offset, sigma));
+}
+
+/** `alma(src, len, offset, sigma)` over a whole series. */
+export function alma(src: Series, len: number, offset = 0.85, sigma = 6): Value[] {
+  return fold(almaTail(len, offset, sigma), src);
+}
+
+/**
+ * `linreg(src, len, offset)`: the least squares line through the last `len`
+ * points, read `offset` bars back along it, from bar `len - 1`.
+ *
+ * `x` runs 0 at the oldest bar of the lookback to `len - 1` at the current one,
+ * so the value at the current bar is `intercept + slope * (len - 1)` and a
+ * positive `offset` steps back down the line without refitting it.
+ *
+ * A length of 1 has no line through it: the normal equations are singular, and
+ * the answer is absence rather than the single point, because a line fitted to
+ * one point is not a fit.
+ */
+export function linregStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  offset: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || offset === null || !lookback.complete()) return NONE;
+  // The x values are the same lookback every bar, so their sums are constants.
+  const sumX = ((len - 1) * len) / 2;
+  const sumXSquared = ((len - 1) * len * (2 * len - 1)) / 6;
+  const divisor = len * sumXSquared - sumX * sumX;
+  if (divisor === 0) return NONE;
+  let sumY = 0;
+  let sumXY = 0;
+  for (let position = 0; position < len; position += 1) {
+    const y = lookback.at(len - 1 - position) as number;
+    sumY += y;
+    sumXY += y * position;
+  }
+  const slope = (len * sumXY - sumX * sumY) / divisor;
+  const intercept = (sumY - slope * sumX) / len;
+  return result(intercept + slope * (len - 1 - offset));
+}
+
+/** `linreg(src, len, offset)` as a tail. */
+export function linregTail(len: number, offset = 0): Tail<Value, Value> {
+  return tailOf((state, value: Value) => linregStep(state, 'q', value, len, offset));
+}
+
+/** `linreg(src, len, offset)` over a whole series. */
+export function linreg(src: Series, len: number, offset = 0): Value[] {
+  return fold(linregTail(len, offset), src);
+}