openalgo-script 0.1.0-alpha.0 → 0.2.0

package/dist/core/stdlib/values/region.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What a stateful function remembers between bars, and why it is a record
+ * rather than a closure.
+ *
+ * A closure is the obvious way to hold a running average and it is the wrong
+ * way here. `compiled-program.md` 2.11 requires a state region to be
+ * **snapshottable by a mechanical copy**: an engine copies and restores one
+ * without knowing which function owns it, because the rollback and replay rules
+ * of section 6 apply to every region at once. Nothing can copy a closure
+ * without knowing what is inside it, and rebuilding one by replaying its inputs
+ * is what 6.2 refuses in as many words: an engine does not re-seed an average
+ * from history, it puts back the record it copied.
+ *
+ * So a region is a flat record of numbers, booleans, strings and fixed length
+ * queues, and `copyState` is the mechanical copy. Every function in this
+ * library is written against one, and the tail form in `tail.ts` is the same
+ * step over a region nobody else can reach. That is what lets the one
+ * implementation serve both a library call folded over a series and an engine
+ * advancing a chart one bar at a time.
+ *
+ * Several functions share one region by taking different key prefixes, which is
+ * how a study built from three others keeps one flat record rather than a tree
+ * of them.
+ */
+/** One field of a state region. A queue is the one compound form 2.11 allows. */
+export type StateField = number | boolean | string | null;
+/** What a single key holds. */
+export type StateSlot = StateField | StateField[];
+/** A state region: a flat record, copyable without knowing what owns it. */
+export type StateRecord = Record<string, StateSlot | undefined>;
+/** A region with nothing in it yet, which is what bar 0 finds. */
+export declare function newState(): StateRecord;
+/** The mechanical copy 2.11 asks for: one level, with queues cloned. */
+export declare function copyState(record: StateRecord): StateRecord;
+/** A number held in a region, with a default for the bar it is first read on. */
+export declare function slot(record: StateRecord, key: string, fallback: number): number;
+/** A condition held in a region, false until something sets it. */
+export declare function flag(record: StateRecord, key: string): boolean;
+/**
+ * A queue held in a region, created on the bar it is first read on.
+ *
+ * The caller keeps it bounded. A queue that grew with the dataset would not be
+ * copyable in the sense 2.11 requires.
+ */
+export declare function queue(record: StateRecord, key: string): StateField[];
+/**
+ * A number held in a region that may honestly have none yet.
+ *
+ * `slot` answers with a fallback, which is what a running total wants. A study
+ * that remembers the previous bar's high wants the other answer: absence until
+ * a present value has been put there, so the bar after a hole is treated as the
+ * bar after a hole rather than as one following a zero.
+ */
+export declare function held(record: StateRecord, key: string): number | null;
+//# sourceMappingURL=region.d.ts.map

package/dist/core/stdlib/values/region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.d.ts","sourceRoot":"","sources":["../../../../src/core/stdlib/values/region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AAE1D,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,EAAE,CAAC;AAElD,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEhE,kEAAkE;AAClE,wBAAgB,QAAQ,IAAI,WAAW,CAEtC;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAO1D;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED,mEAAmE;AACnE,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAMpE;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpE"}

package/dist/core/stdlib/values/region.js

@@ -0,0 +1,73 @@
+/**
+ * What a stateful function remembers between bars, and why it is a record
+ * rather than a closure.
+ *
+ * A closure is the obvious way to hold a running average and it is the wrong
+ * way here. `compiled-program.md` 2.11 requires a state region to be
+ * **snapshottable by a mechanical copy**: an engine copies and restores one
+ * without knowing which function owns it, because the rollback and replay rules
+ * of section 6 apply to every region at once. Nothing can copy a closure
+ * without knowing what is inside it, and rebuilding one by replaying its inputs
+ * is what 6.2 refuses in as many words: an engine does not re-seed an average
+ * from history, it puts back the record it copied.
+ *
+ * So a region is a flat record of numbers, booleans, strings and fixed length
+ * queues, and `copyState` is the mechanical copy. Every function in this
+ * library is written against one, and the tail form in `tail.ts` is the same
+ * step over a region nobody else can reach. That is what lets the one
+ * implementation serve both a library call folded over a series and an engine
+ * advancing a chart one bar at a time.
+ *
+ * Several functions share one region by taking different key prefixes, which is
+ * how a study built from three others keeps one flat record rather than a tree
+ * of them.
+ */
+/** A region with nothing in it yet, which is what bar 0 finds. */
+export function newState() {
+    return {};
+}
+/** The mechanical copy 2.11 asks for: one level, with queues cloned. */
+export function copyState(record) {
+    const out = {};
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        out[key] = Array.isArray(value) ? [...value] : value;
+    }
+    return out;
+}
+/** A number held in a region, with a default for the bar it is first read on. */
+export function slot(record, key, fallback) {
+    const value = record[key];
+    return typeof value === 'number' ? value : fallback;
+}
+/** A condition held in a region, false until something sets it. */
+export function flag(record, key) {
+    return record[key] === true;
+}
+/**
+ * A queue held in a region, created on the bar it is first read on.
+ *
+ * The caller keeps it bounded. A queue that grew with the dataset would not be
+ * copyable in the sense 2.11 requires.
+ */
+export function queue(record, key) {
+    const held = record[key];
+    if (Array.isArray(held))
+        return held;
+    const made = [];
+    record[key] = made;
+    return made;
+}
+/**
+ * A number held in a region that may honestly have none yet.
+ *
+ * `slot` answers with a fallback, which is what a running total wants. A study
+ * that remembers the previous bar's high wants the other answer: absence until
+ * a present value has been put there, so the bar after a hole is treated as the
+ * bar after a hole rather than as one following a zero.
+ */
+export function held(record, key) {
+    const value = record[key];
+    return typeof value === 'number' ? value : null;
+}
+//# sourceMappingURL=region.js.map

package/dist/core/stdlib/values/region.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.js","sourceRoot":"","sources":["../../../../src/core/stdlib/values/region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,kEAAkE;AAClE,MAAM,UAAU,QAAQ;IACtB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,MAAmB;IAC3C,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,IAAI,CAAC,MAAmB,EAAE,GAAW,EAAE,QAAgB;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,IAAI,CAAC,MAAmB,EAAE,GAAW;IACnD,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,MAAmB,EAAE,GAAW;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,MAAmB,EAAE,GAAW;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC"}

package/dist/core/stdlib/values/tail.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The tail path, and why the whole-series form is defined in terms of it.
+ *
+ * A live chart recomputes on every tick. A study that rescans its whole history
+ * to produce one more bar makes a terminal slow in proportion to how much
+ * history the trader has loaded, and nobody notices until the day somebody
+ * scrolls back five years.
+ *
+ * So every function here is written once, as a tail: a small piece of state
+ * plus a step that takes this bar's input and returns this bar's output. The
+ * whole-series form is that step folded over the series and nothing else.
+ *
+ * That is not a convenience. `compiled-program.md` section 8.3 requires the two
+ * to agree to the last bit, and the only way to be sure of that is to have one
+ * implementation rather than two that are meant to match. A second batch
+ * implementation, however carefully written, is a second accumulation order
+ * waiting to drift.
+ *
+ * The state lives in a region (`region.ts`) rather than in the closure's own
+ * variables, so the same step an engine advances over a live chart is the step
+ * this folds over a series. `tailOf` is the whole of the tail form: a region
+ * nobody else can reach, and the step applied to it.
+ */
+import type { StateRecord } from './region.js';
+/**
+ * One bar in, one bar out, with everything the function remembers held inside.
+ *
+ * A tail is stateful and single use: it is fed bars in order, from bar 0, and
+ * each call advances it by one bar.
+ */
+export interface Tail<In, Out> {
+    /** Advance by one bar and return that bar's output. */
+    next(input: In): Out;
+}
+/** A tail's step applied to a whole series, oldest bar first. */
+export declare function fold<In, Out>(tail: Tail<In, Out>, inputs: readonly In[]): Out[];
+/**
+ * A tail from a step: a private region, advanced one bar per call.
+ *
+ * The region is the same shape an engine hands a stateful call, so the function
+ * underneath does not know which of the two is driving it.
+ */
+export declare function tailOf<In, Out>(step: (state: StateRecord, input: In) => Out): Tail<In, Out>;
+//# sourceMappingURL=tail.d.ts.map

package/dist/core/stdlib/values/tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail.d.ts","sourceRoot":"","sources":["../../../../src/core/stdlib/values/tail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;GAKG;AACH,MAAM,WAAW,IAAI,CAAC,EAAE,EAAE,GAAG;IAC3B,uDAAuD;IACvD,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,GAAG,CAAC;CACtB;AAED,iEAAiE;AACjE,wBAAgB,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,GAAG,EAAE,CAI/E;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,KAAK,GAAG,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAO3F"}

package/dist/core/stdlib/values/tail.js

@@ -0,0 +1,23 @@
+import { newState } from './region.js';
+/** A tail's step applied to a whole series, oldest bar first. */
+export function fold(tail, inputs) {
+    const out = [];
+    for (const input of inputs)
+        out.push(tail.next(input));
+    return out;
+}
+/**
+ * A tail from a step: a private region, advanced one bar per call.
+ *
+ * The region is the same shape an engine hands a stateful call, so the function
+ * underneath does not know which of the two is driving it.
+ */
+export function tailOf(step) {
+    const state = newState();
+    return {
+        next(input) {
+            return step(state, input);
+        },
+    };
+}
+//# sourceMappingURL=tail.js.map

package/dist/core/stdlib/values/tail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail.js","sourceRoot":"","sources":["../../../../src/core/stdlib/values/tail.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAavC,iEAAiE;AACjE,MAAM,UAAU,IAAI,CAAU,IAAmB,EAAE,MAAqB;IACtE,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAU,IAA4C;IAC1E,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO;QACL,IAAI,CAAC,KAAS;YACZ,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/stdlib/values/value.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The absent value, and the two rules every result in this library obeys.
+ *
+ * Absence is a value of its own and is never a number. A warmup bar is absent,
+ * and anything computed from an absent value is absent. Returning zero instead
+ * would draw a line along the axis that looks exactly like data, and a reader
+ * has no way to tell the two apart.
+ *
+ * Not-a-number is not used as the sentinel, for the reason `compiled-program.md`
+ * section 3.4 gives: it would propagate through arithmetic by accident, which
+ * is the right answer for some operators and the wrong one for others, and it
+ * would turn an absence test into a floating point comparison.
+ */
+/** A number, or absence. */
+export type Value = number | null;
+/** A series is one value per bar, oldest first. */
+export type Series = readonly Value[];
+/**
+ * A condition, one per bar: true, false, or absent.
+ *
+ * Absence is its own answer here too. A comparison against a warmup bar is
+ * absent rather than false, and the functions that consume a condition say
+ * which of the two they treat it as.
+ */
+export type Flag = boolean | null;
+/** A series of conditions, one per bar, oldest first. */
+export type Flags = readonly Flag[];
+/** Absence, written `none` in a script. */
+export declare const NONE: Value;
+/** True when the value is present, narrowing it to a number. */
+export declare function isPresent(value: Value): value is number;
+/**
+ * A computed number, made safe to return.
+ *
+ * Two rules from `compiled-program.md` section 3.1, applied at every value this
+ * library hands back:
+ *
+ * - A result with no finite real value is absent, not an infinity and not a
+ *   not-a-number. `log(0)` and a division by zero inside a ratio study are the
+ *   everyday cases.
+ * - Negative zero is normalised to positive zero, so nothing downstream can
+ *   observe the sign of a zero and two engines cannot differ over it.
+ */
+export declare function result(x: number): Value;
+/**
+ * Element `index` of a series, or absence when the index falls off either end.
+ *
+ * Reading before the start of the dataset is absent rather than an error, which
+ * is what makes `history` and every lookback function fall out of one rule
+ * instead of a special case each.
+ */
+export declare function at(values: Series, index: number): Value;
+/**
+ * Whether a length argument is inside its contract: a whole number of one or
+ * more, per `stdlib.md` section 2.5.
+ *
+ * This library raises nothing. A length outside the contract is OS3004 at
+ * compile time when it is a literal and OS4003 at run time when it is computed,
+ * and both are raised before a call reaches here. The functions below use this
+ * only as a backstop, and a backstop returns absence rather than a guess: a
+ * wrong number drawn on a chart is worse than a gap.
+ */
+export declare function isLength(length: number): boolean;
+//# sourceMappingURL=value.d.ts.map

package/dist/core/stdlib/values/value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../../../src/core/stdlib/values/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4BAA4B;AAC5B,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAElC,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,SAAS,KAAK,EAAE,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;AAElC,yDAAyD;AACzD,MAAM,MAAM,KAAK,GAAG,SAAS,IAAI,EAAE,CAAC;AAEpC,2CAA2C;AAC3C,eAAO,MAAM,IAAI,EAAE,KAAY,CAAC;AAEhC,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,MAAM,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,CAGvC;AAED;;;;;;GAMG;AACH,wBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAGvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/core/stdlib/values/value.js

@@ -0,0 +1,61 @@
+/**
+ * The absent value, and the two rules every result in this library obeys.
+ *
+ * Absence is a value of its own and is never a number. A warmup bar is absent,
+ * and anything computed from an absent value is absent. Returning zero instead
+ * would draw a line along the axis that looks exactly like data, and a reader
+ * has no way to tell the two apart.
+ *
+ * Not-a-number is not used as the sentinel, for the reason `compiled-program.md`
+ * section 3.4 gives: it would propagate through arithmetic by accident, which
+ * is the right answer for some operators and the wrong one for others, and it
+ * would turn an absence test into a floating point comparison.
+ */
+/** Absence, written `none` in a script. */
+export const NONE = null;
+/** True when the value is present, narrowing it to a number. */
+export function isPresent(value) {
+    return value !== null;
+}
+/**
+ * A computed number, made safe to return.
+ *
+ * Two rules from `compiled-program.md` section 3.1, applied at every value this
+ * library hands back:
+ *
+ * - A result with no finite real value is absent, not an infinity and not a
+ *   not-a-number. `log(0)` and a division by zero inside a ratio study are the
+ *   everyday cases.
+ * - Negative zero is normalised to positive zero, so nothing downstream can
+ *   observe the sign of a zero and two engines cannot differ over it.
+ */
+export function result(x) {
+    if (!Number.isFinite(x))
+        return NONE;
+    return x === 0 ? 0 : x;
+}
+/**
+ * Element `index` of a series, or absence when the index falls off either end.
+ *
+ * Reading before the start of the dataset is absent rather than an error, which
+ * is what makes `history` and every lookback function fall out of one rule
+ * instead of a special case each.
+ */
+export function at(values, index) {
+    const value = values[index];
+    return value === undefined ? NONE : value;
+}
+/**
+ * Whether a length argument is inside its contract: a whole number of one or
+ * more, per `stdlib.md` section 2.5.
+ *
+ * This library raises nothing. A length outside the contract is OS3004 at
+ * compile time when it is a literal and OS4003 at run time when it is computed,
+ * and both are raised before a call reaches here. The functions below use this
+ * only as a backstop, and a backstop returns absence rather than a guess: a
+ * wrong number drawn on a chart is worse than a gap.
+ */
+export function isLength(length) {
+    return Number.isInteger(length) && length >= 1;
+}
+//# sourceMappingURL=value.js.map

package/dist/core/stdlib/values/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../../../src/core/stdlib/values/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,IAAI,GAAU,IAAI,CAAC;AAEhC,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,OAAO,KAAK,KAAK,IAAI,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,EAAE,CAAC,MAAc,EAAE,KAAa;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/dist/core/stdlib/volatility/bands.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The channel studies: `bollinger`, its two readings, `keltner` and `donchian`.
+ *
+ * Each returns an array holding this bar's outputs, in the order its entry in
+ * `stdlib.md` documents. **The array itself is never absent and never changes
+ * length**, per section 2.3: each element carries its own warmup and is absent
+ * until it is reached. An array that grew as warmup completed would make an
+ * index an out-of-range error at the left edge of a chart and nowhere else.
+ */
+import type { Bar, Series, StateRecord, Tail, Value } from '../values/index.js';
+import type { MaType } from '../averages/index.js';
+import type { Gap } from './range.js';
+/** `bollinger(src, len, mult)`: `[basis, upper, lower]`, all from bar `len - 1`. */
+export declare function bollingerStep(state: StateRecord, key: string, value: Value, len: number | null, mult: number | null): Value[];
+/** `bollinger(src, len, mult)` as a tail. */
+export declare function bollingerTail(len?: number, mult?: number): Tail<Value, Value[]>;
+/** `bollinger(src, len, mult)` over a whole series. */
+export declare function bollinger(src: Series, len?: number, mult?: number): Value[][];
+/** `bbWidth(src, len, mult)`: band width over the basis, from bar `len - 1`. */
+export declare function bbWidthStep(state: StateRecord, key: string, value: Value, len: number | null, mult: number | null): Value;
+/** `bbWidth(src, len, mult)` as a tail. */
+export declare function bbWidthTail(len?: number, mult?: number): Tail<Value, Value>;
+/** `bbWidth(src, len, mult)` over a whole series. */
+export declare function bbWidth(src: Series, len?: number, mult?: number): Value[];
+/** `bbPercent(src, len, mult)`: where price sits between the bands, from bar `len - 1`. */
+export declare function bbPercentStep(state: StateRecord, key: string, value: Value, len: number | null, mult: number | null): Value;
+/** `bbPercent(src, len, mult)` as a tail. */
+export declare function bbPercentTail(len?: number, mult?: number): Tail<Value, Value>;
+/** `bbPercent(src, len, mult)` over a whole series. */
+export declare function bbPercent(src: Series, len?: number, mult?: number): Value[];
+/**
+ * `keltner(len, mult, atrLen, maType)`: `[basis, upper, lower]`, all from bar
+ * `max(len, atrLen) - 1`.
+ *
+ * The same picture as `bollinger` built from average true range instead of
+ * deviation, so the rails widen on how far the instrument travels rather than
+ * on how dispersed its closes were.
+ */
+export declare function keltnerStep(state: StateRecord, key: string, gap: Gap, close: Value, volume: Value, len: number | null, mult: number | null, atrLen: number | null, maType: MaType | null): Value[];
+/** `keltner(len, mult, atrLen, maType)` as a tail. */
+export declare function keltnerTail(len?: number, mult?: number, atrLen?: number, maType?: MaType): Tail<Bar, Value[]>;
+/** `keltner(len, mult, atrLen, maType)` over a run of bars. */
+export declare function keltner(bars: readonly Bar[], len?: number, mult?: number, atrLen?: number, maType?: MaType): Value[][];
+/** `donchian(len)`: `[upper, basis, lower]`, all from bar `len - 1`. */
+export declare function donchianStep(state: StateRecord, key: string, high: Value, low: Value, len: number | null): Value[];
+/** `donchian(len)` as a tail. */
+export declare function donchianTail(len?: number): Tail<Bar, Value[]>;
+/** `donchian(len)` over a run of bars. */
+export declare function donchian(bars: readonly Bar[], len?: number): Value[][];
+//# sourceMappingURL=bands.d.ts.map

package/dist/core/stdlib/volatility/bands.d.ts.map

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

package/dist/core/stdlib/volatility/bands.js

@@ -0,0 +1,101 @@
+import { NONE, at, fold, isPresent, result, tailOf } from '../values/index.js';
+import { maStep, smaStep } from '../averages/index.js';
+import { extremeStep } from '../series/index.js';
+import { stdevStep } from './deviation.js';
+import { atrStep, gapOf } from './range.js';
+/** `bollinger(src, len, mult)`: `[basis, upper, lower]`, all from bar `len - 1`. */
+export function bollingerStep(state, key, value, len, mult) {
+    const middle = smaStep(state, `${key}q`, value, len);
+    const deviation = stdevStep(state, `${key}d`, value, len, false);
+    if (!isPresent(middle) || !isPresent(deviation) || mult === null)
+        return [middle, NONE, NONE];
+    return [middle, result(middle + mult * deviation), result(middle - mult * deviation)];
+}
+/** `bollinger(src, len, mult)` as a tail. */
+export function bollingerTail(len = 20, mult = 2) {
+    return tailOf((state, value) => bollingerStep(state, '', value, len, mult));
+}
+/** `bollinger(src, len, mult)` over a whole series. */
+export function bollinger(src, len = 20, mult = 2) {
+    return fold(bollingerTail(len, mult), src);
+}
+/** `bbWidth(src, len, mult)`: band width over the basis, from bar `len - 1`. */
+export function bbWidthStep(state, key, value, len, mult) {
+    const trio = bollingerStep(state, key, value, len, mult);
+    const basis = at(trio, 0);
+    const upper = at(trio, 1);
+    const lower = at(trio, 2);
+    if (!isPresent(basis) || !isPresent(upper) || !isPresent(lower))
+        return NONE;
+    if (basis === 0)
+        return NONE;
+    return result((upper - lower) / basis);
+}
+/** `bbWidth(src, len, mult)` as a tail. */
+export function bbWidthTail(len = 20, mult = 2) {
+    return tailOf((state, value) => bbWidthStep(state, '', value, len, mult));
+}
+/** `bbWidth(src, len, mult)` over a whole series. */
+export function bbWidth(src, len = 20, mult = 2) {
+    return fold(bbWidthTail(len, mult), src);
+}
+/** `bbPercent(src, len, mult)`: where price sits between the bands, from bar `len - 1`. */
+export function bbPercentStep(state, key, value, len, mult) {
+    const trio = bollingerStep(state, key, value, len, mult);
+    const upper = at(trio, 1);
+    const lower = at(trio, 2);
+    if (!isPresent(value) || !isPresent(upper) || !isPresent(lower))
+        return NONE;
+    const span = upper - lower;
+    if (span === 0)
+        return NONE;
+    return result((value - lower) / span);
+}
+/** `bbPercent(src, len, mult)` as a tail. */
+export function bbPercentTail(len = 20, mult = 2) {
+    return tailOf((state, value) => bbPercentStep(state, '', value, len, mult));
+}
+/** `bbPercent(src, len, mult)` over a whole series. */
+export function bbPercent(src, len = 20, mult = 2) {
+    return fold(bbPercentTail(len, mult), src);
+}
+/**
+ * `keltner(len, mult, atrLen, maType)`: `[basis, upper, lower]`, all from bar
+ * `max(len, atrLen) - 1`.
+ *
+ * The same picture as `bollinger` built from average true range instead of
+ * deviation, so the rails widen on how far the instrument travels rather than
+ * on how dispersed its closes were.
+ */
+export function keltnerStep(state, key, gap, close, volume, len, mult, atrLen, maType) {
+    const middle = maStep(state, `${key}m`, { src: close, volume }, len, maType);
+    const width = atrStep(state, `${key}r`, gap, atrLen);
+    if (!isPresent(middle) || !isPresent(width) || mult === null)
+        return [middle, NONE, NONE];
+    return [middle, result(middle + mult * width), result(middle - mult * width)];
+}
+/** `keltner(len, mult, atrLen, maType)` as a tail. */
+export function keltnerTail(len = 20, mult = 2, atrLen = 10, maType = 'ema') {
+    return tailOf((state, bar) => keltnerStep(state, '', gapOf(state, 'g', bar), bar.close, bar.volume, len, mult, atrLen, maType));
+}
+/** `keltner(len, mult, atrLen, maType)` over a run of bars. */
+export function keltner(bars, len = 20, mult = 2, atrLen = 10, maType = 'ema') {
+    return fold(keltnerTail(len, mult, atrLen, maType), bars);
+}
+/** `donchian(len)`: `[upper, basis, lower]`, all from bar `len - 1`. */
+export function donchianStep(state, key, high, low, len) {
+    const upper = extremeStep(state, `${key}h`, high, len, true, false);
+    const lower = extremeStep(state, `${key}l`, low, len, false, false);
+    if (!isPresent(upper) || !isPresent(lower))
+        return [upper, NONE, lower];
+    return [upper, result((upper + lower) / 2), lower];
+}
+/** `donchian(len)` as a tail. */
+export function donchianTail(len = 20) {
+    return tailOf((state, bar) => donchianStep(state, '', bar.high, bar.low, len));
+}
+/** `donchian(len)` over a run of bars. */
+export function donchian(bars, len = 20) {
+    return fold(donchianTail(len), bars);
+}
+//# sourceMappingURL=bands.js.map

package/dist/core/stdlib/volatility/bands.js.map

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

package/dist/core/stdlib/volatility/deviation.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `variance` and `stdev`.
+ *
+ * **Population by default, the `len` divisor.** `stdlib.md` section 6 fixes it
+ * and gives the reason: that is what the band studies a chart has to reproduce
+ * use. `sample = true` switches to the `len - 1` divisor, so neither camp has
+ * to write the correction by hand and neither has to guess which one a chart
+ * drew.
+ *
+ * Two passes: the mean of the lookback first, then the deviations from it. The
+ * one pass arrangement that subtracts the square of the mean from the mean of
+ * the squares loses most of its significant digits on a price series, where the
+ * values are large and their spread is small, and can even produce a negative
+ * variance that then has to be floored at zero. A study whose implementation
+ * needs a floor to stay real is a study computing the wrong quantity.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+/** `variance(src, len, sample)`: the squared deviation over the lookback, from bar `len - 1`. */
+export declare function varianceStep(state: StateRecord, key: string, value: Value, len: number | null, sample: boolean): Value;
+/** `variance(src, len, sample)` as a tail. */
+export declare function varianceTail(len: number, sample?: boolean): Tail<Value, Value>;
+/** `variance(src, len, sample)` over a whole series. */
+export declare function variance(src: Series, len: number, sample?: boolean): Value[];
+/** `stdev(src, len, sample)`: the square root of the same, from bar `len - 1`. */
+export declare function stdevStep(state: StateRecord, key: string, value: Value, len: number | null, sample: boolean): Value;
+/** `stdev(src, len, sample)` as a tail. */
+export declare function stdevTail(len: number, sample?: boolean): Tail<Value, Value>;
+/** `stdev(src, len, sample)` over a whole series. */
+export declare function stdev(src: Series, len: number, sample?: boolean): Value[];
+/**
+ * The mean absolute deviation from the lookback's mean.
+ *
+ * Not a call of its own in `stdlib.md`, and here because `cci` is defined
+ * against it rather than against `stdev`: the 0.015 constant in that study is
+ * calibrated for this quantity, and substituting a standard deviation changes
+ * every reading.
+ */
+export declare function meanDeviationStep(state: StateRecord, key: string, value: Value, len: number | null): Value;
+/** The mean absolute deviation as a tail. */
+export declare function meanDeviationTail(len: number): Tail<Value, Value>;
+/** The mean absolute deviation over a whole series. */
+export declare function meanDeviation(src: Series, len: number): Value[];
+//# sourceMappingURL=deviation.d.ts.map

package/dist/core/stdlib/volatility/deviation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviation.d.ts","sourceRoot":"","sources":["../../../../src/core/stdlib/volatility/deviation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3E,iGAAiG;AACjG,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,MAAM,EAAE,OAAO,GACd,KAAK,CAeP;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAE5E;AAED,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,KAAK,EAAE,CAE1E;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,MAAM,EAAE,OAAO,GACd,KAAK,CAIP;AAED,2CAA2C;AAC3C,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAEzE;AAED,qDAAqD;AACrD,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,KAAK,EAAE,CAEvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,KAAK,CAWP;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAEjE;AAED,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,EAAE,CAE/D"}

package/dist/core/stdlib/volatility/deviation.js

@@ -0,0 +1,75 @@
+import { NONE, fold, isPresent, result, ring, tailOf } from '../values/index.js';
+/** `variance(src, len, sample)`: the squared deviation over the lookback, from bar `len - 1`. */
+export function varianceStep(state, key, value, len, sample) {
+    const lookback = ring(state, key, len);
+    lookback.push(value);
+    if (len === null)
+        return NONE;
+    const divisor = sample ? len - 1 : len;
+    if (!lookback.complete() || divisor <= 0)
+        return NONE;
+    const mean = lookback.mean();
+    if (!isPresent(mean))
+        return NONE;
+    let squares = 0;
+    // Oldest bar first, the order of `lookback.ts`.
+    for (let back = len - 1; back >= 0; back -= 1) {
+        const deviation = lookback.at(back) - mean;
+        squares += deviation * deviation;
+    }
+    return result(squares / divisor);
+}
+/** `variance(src, len, sample)` as a tail. */
+export function varianceTail(len, sample = false) {
+    return tailOf((state, value) => varianceStep(state, 'q', value, len, sample));
+}
+/** `variance(src, len, sample)` over a whole series. */
+export function variance(src, len, sample = false) {
+    return fold(varianceTail(len, sample), src);
+}
+/** `stdev(src, len, sample)`: the square root of the same, from bar `len - 1`. */
+export function stdevStep(state, key, value, len, sample) {
+    const squared = varianceStep(state, key, value, len, sample);
+    if (!isPresent(squared) || squared < 0)
+        return NONE;
+    return result(Math.sqrt(squared));
+}
+/** `stdev(src, len, sample)` as a tail. */
+export function stdevTail(len, sample = false) {
+    return tailOf((state, value) => stdevStep(state, 'q', value, len, sample));
+}
+/** `stdev(src, len, sample)` over a whole series. */
+export function stdev(src, len, sample = false) {
+    return fold(stdevTail(len, sample), src);
+}
+/**
+ * The mean absolute deviation from the lookback's mean.
+ *
+ * Not a call of its own in `stdlib.md`, and here because `cci` is defined
+ * against it rather than against `stdev`: the 0.015 constant in that study is
+ * calibrated for this quantity, and substituting a standard deviation changes
+ * every reading.
+ */
+export function meanDeviationStep(state, key, value, len) {
+    const lookback = ring(state, key, len);
+    lookback.push(value);
+    if (len === null || !lookback.complete())
+        return NONE;
+    const mean = lookback.mean();
+    if (!isPresent(mean))
+        return NONE;
+    let total = 0;
+    for (let back = len - 1; back >= 0; back -= 1) {
+        total += Math.abs(lookback.at(back) - mean);
+    }
+    return result(total / len);
+}
+/** The mean absolute deviation as a tail. */
+export function meanDeviationTail(len) {
+    return tailOf((state, value) => meanDeviationStep(state, 'q', value, len));
+}
+/** The mean absolute deviation over a whole series. */
+export function meanDeviation(src, len) {
+    return fold(meanDeviationTail(len), src);
+}
+//# sourceMappingURL=deviation.js.map