openalgo-script 0.2.0 → 0.4.0

package/dist/core/accounting/shapes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The atoms the money is folded from: a fill, a contract and a bar's close.
+ *
+ * **Everything in this module is portable data.** No class, no function, no
+ * object reference, no absent field, no map and no date: a shape here is what
+ * `JSON.parse` gives back, so a report can be computed here, stored by a
+ * platform, sent to another process and recomputed there without this
+ * implementation being present. That is not a convenience. A run record is the
+ * conformance case a second engine is handed, and a case that can only be read
+ * by the engine that wrote it proves nothing about either.
+ *
+ * **A fill is the only thing money is folded from.** Not a position, not a
+ * ledger row, not a running total the engine happened to be holding: the fills
+ * the engine settled, in the order it settled them, each naming the position
+ * reference it moved and the size of that reference either side of the
+ * settlement. Every figure in a report is a function of that list and of the
+ * bars it is marked against, which is what makes a report reproducible from a
+ * record with no engine in the room.
+ */
+/**
+ * Money, in the contract's own currency.
+ *
+ * A number rather than a type of its own, because a type of its own would be a
+ * class and a class does not survive `JSON.parse`. The rounding is stated once,
+ * on the contract, and applied once per fill total.
+ */
+export type Money = number;
+/**
+ * The instrument facts a run was carried out under, as the host stated them.
+ *
+ * A snapshot rather than a reference. An instrument's lot size and tick size
+ * change, and a report recomputed months later under today's facts would be a
+ * different study wearing the same name, so the facts travel with the run.
+ */
+export interface Contract {
+    readonly symbol: string | null;
+    readonly exchange: string | null;
+    readonly currency: string;
+    readonly tickSize: number | null;
+    readonly lotSize: number | null;
+    /** Money per 1.0 of price per unit; 1 when the host states none. */
+    readonly pointValue: number;
+    /** Money rounding digits, half to even, once per fill total. */
+    readonly digits: number;
+}
+/** One settled fill. Every money figure is folded from these and nothing else. */
+export interface RecordedFill {
+    readonly seq: number;
+    readonly intentId: number;
+    readonly orderRef: string;
+    readonly tag: string;
+    readonly positionRef: number;
+    readonly side: 'buy' | 'sell';
+    /** Positive, this fill's own quantity. */
+    readonly units: number;
+    readonly price: number;
+    readonly barIndex: number;
+    readonly barTime: number | null;
+    readonly refSizeBefore: number;
+    readonly refSizeAfter: number;
+}
+/** One bar as the report marks against it. Close only: 17.4 marks to the close. */
+export interface BarMark {
+    readonly barIndex: number;
+    readonly time: number | null;
+    readonly close: number | null;
+    /** False for a warmup bar. */
+    readonly inReport: boolean;
+}
+//# sourceMappingURL=shapes.d.ts.map

package/dist/core/accounting/shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.d.ts","sourceRoot":"","sources":["../../../src/core/accounting/shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B"}

package/dist/core/accounting/shapes.js

@@ -0,0 +1,21 @@
+/**
+ * The atoms the money is folded from: a fill, a contract and a bar's close.
+ *
+ * **Everything in this module is portable data.** No class, no function, no
+ * object reference, no absent field, no map and no date: a shape here is what
+ * `JSON.parse` gives back, so a report can be computed here, stored by a
+ * platform, sent to another process and recomputed there without this
+ * implementation being present. That is not a convenience. A run record is the
+ * conformance case a second engine is handed, and a case that can only be read
+ * by the engine that wrote it proves nothing about either.
+ *
+ * **A fill is the only thing money is folded from.** Not a position, not a
+ * ledger row, not a running total the engine happened to be holding: the fills
+ * the engine settled, in the order it settled them, each naming the position
+ * reference it moved and the size of that reference either side of the
+ * settlement. Every figure in a report is a function of that list and of the
+ * bars it is marked against, which is what makes a report reproducible from a
+ * record with no engine in the room.
+ */
+export {};
+//# sourceMappingURL=shapes.js.map

package/dist/core/accounting/shapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.js","sourceRoot":"","sources":["../../../src/core/accounting/shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/core/accounting/statistics.d.ts

@@ -0,0 +1,75 @@
+import type { EquityPoint } from './equity.js';
+import type { Contract, Money } from './shapes.js';
+import type { Trade } from './trades.js';
+/** What the whole run came to. */
+export interface Summary {
+    readonly capital: Money;
+    readonly currency: string;
+    readonly netProfit: Money;
+    /** Sum of winning trades, before charges. */
+    readonly grossProfit: Money;
+    /**
+     * The losing trades' gross, as a magnitude, and it can come out at or below
+     * zero.
+     *
+     * A trade wins or loses on its net after charges and contributes its gross
+     * here, so a trade whose gross was positive and whose charges took it under
+     * lands in the losses carrying a positive gross, which lowers this figure and
+     * with few enough trades beside it takes it to zero or past it. `tallyOf`
+     * says why that is preferred to counting one trade as a loser in one figure
+     * and a winner in another. It is written here because it was documented as a
+     * positive magnitude and is not one, and a reader dividing by it was handed a
+     * negative profit factor with nothing saying that could happen.
+     */
+    readonly grossLoss: Money;
+    readonly charges: Money;
+    /** `netProfit / capital`, a fraction and not a figure times a hundred. */
+    readonly returnPercent: number;
+    /** Closed only. */
+    readonly tradeCount: number;
+    readonly openTradeCount: number;
+    readonly wins: number;
+    readonly losses: number;
+    /** Exactly zero net. */
+    readonly scratches: number;
+    /** wins / (wins + losses), null when none closed. */
+    readonly winRate: number | null;
+    readonly averageWin: Money;
+    /** Positive magnitude. */
+    readonly averageLoss: Money;
+    /** Money per closed trade. */
+    readonly expectancy: Money;
+    readonly expectancyStandardError: Money;
+    /**
+     * Gross profit over gross loss, or null where there is no ratio to take.
+     *
+     * Null when the gross loss is not above zero: a run with no losing trade has
+     * nothing to divide by, and one whose losses cost less in gross than their
+     * charges has a denominator at or below zero. A profit factor is a
+     * non-negative ratio everywhere it is used, so a negative one is not a
+     * surprising value, it is a number nobody can act on. It used to be
+     * reported: two trades, one charged into a loss on a positive gross, gave a
+     * profit factor of -0.5.
+     */
+    readonly profitFactor: number | null;
+    /** Zero or negative, the same sign the curve states it with. */
+    readonly maxDrawdown: Money;
+    /** The deepest point's own fraction, not the worst fraction of any point. */
+    readonly maxDrawdownPercent: number;
+    /** A bar time, never an index. */
+    readonly maxDrawdownAt: number | null;
+    readonly longestDrawdownBars: number;
+    readonly averageBarsHeld: number | null;
+    readonly barsInMarket: number;
+    readonly barCount: number;
+}
+/**
+ * The whole run in one shape, folded from its trades and its own curve.
+ *
+ * The curve is passed in rather than recomputed, because a summary that folded
+ * its own would be a second equity curve with a second set of rounding, and the
+ * first disagreement between them would be a drawdown figure that no point in
+ * the reported curve ever reached.
+ */
+export declare function summaryOf(trades: readonly Trade[], equity: readonly EquityPoint[], contract: Contract, capital: Money): Summary;
+//# sourceMappingURL=statistics.d.ts.map

package/dist/core/accounting/statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../src/core/accounting/statistics.ts"],"names":[],"mappings":"AA6DA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,kCAAkC;AAClC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mBAAmB;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,uBAAuB,EAAE,KAAK,CAAC;IACxC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,kCAAkC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA2BD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,KAAK,GACb,OAAO,CAuCT"}

package/dist/core/accounting/statistics.js

@@ -0,0 +1,246 @@
+/**
+ * The summary, and the two figures in it that decide whether a run means
+ * anything.
+ *
+ * **Win rate is over closed trades, on net profit after charges**, and a trade
+ * whose net is exactly zero is a scratch counted in neither half. It is null
+ * where nothing closed rather than zero, because zero is a number a reader
+ * compares against and "nothing has closed yet" is not a losing run.
+ *
+ * **Expectancy is money per closed trade**, and it has two spellings that must
+ * agree: the win rate against the average win and the average loss, and the net
+ * profit over the trade count. Two spellings of one figure that disagree is how
+ * a report loses its reader, so one of them is the computation and the other is
+ * a test, and the test says which sequence of roundings it allows for.
+ *
+ * **And its standard error is what answers the question a comparison asks.**
+ * The sample standard deviation of per-trade net over the square root of the
+ * trade count is what turns "this run made more" into "this run made more than
+ * the noise", and without it a difference of two percent over eleven trades
+ * reads like a result.
+ *
+ * Bar times rather than bar indices, wherever a figure addresses a bar: loading
+ * more history shifts every index, so a report that addresses a bar by index
+ * changes when the warmup changes.
+ *
+ * ## Which trades a figure is counted over, which is three different answers
+ *
+ * A summary folds a list holding closed trades and open ones together, and
+ * almost every defect this file can have is a figure counted over the wrong
+ * half of it.
+ *
+ * - **Net profit, and everything derived from it**, is over closed trades. An
+ *   open trade's net is its charges so far with no gross against them, so
+ *   counting it would report a run holding a winner as having lost money.
+ * - **Charges are over every trade**, open ones included, because the money
+ *   left the account whether or not the position came back. This is the figure
+ *   the equity curve's last point carries, and the two are asserted equal.
+ * - **The drawdown figures are over the curve** and not over the trades at all.
+ *   A drawdown is a thing equity did between two trades as often as during one.
+ *
+ * ## The cases where a statistic is not a number
+ *
+ * Every one of them is a division, and every one of them is answered here
+ * rather than left to arrive as a value JSON turns into `null`:
+ *
+ * - **Nothing closed.** The win rate is null, which is a different claim from
+ *   zero. Expectancy and its error are zero, because the type is money and
+ *   money is not nullable, and `tradeCount` beside them is the field that says
+ *   whether they mean anything.
+ * - **One closed trade.** A sample of one has no spread, so the standard error
+ *   is zero. Zero here means not measurable, never measured: anything dividing
+ *   by it checks the trade count first.
+ * - **Every closed trade a scratch.** There is no denominator for a win rate,
+ *   so it is null for the same reason as nothing closed.
+ * - **Nothing lost.** The profit factor is null rather than an infinity, which
+ *   is the same decision `spec/conformance.md` takes about absence: a value
+ *   that does not survive being written down is not a value a report may hold.
+ * - **Everything lost.** The profit factor is zero, expectancy is negative, the
+ *   average win is zero, and none of the four is a division by zero.
+ */
+import { barsInMarketOver, ratioOf } from './equity.js';
+/**
+ * The whole run in one shape, folded from its trades and its own curve.
+ *
+ * The curve is passed in rather than recomputed, because a summary that folded
+ * its own would be a second equity curve with a second set of rounding, and the
+ * first disagreement between them would be a drawdown figure that no point in
+ * the reported curve ever reached.
+ */
+export function summaryOf(trades, equity, contract, capital) {
+    const tally = tallyOf(trades);
+    const depth = depthOf(equity);
+    const decided = tally.wins + tally.losses;
+    // Net over the closed count, and nothing else, because this is the figure the
+    // other spelling is checked against. The win rate spelling divides by the
+    // decided trades instead, so the two are the same number exactly when no
+    // trade scratched, and `tests/accounting/statistics.test.ts` asserts both the
+    // agreement and the one case that parts them.
+    const expectancy = tally.tradeCount === 0 ? 0 : tally.netProfit / tally.tradeCount;
+    return {
+        capital,
+        currency: contract.currency,
+        netProfit: tally.netProfit,
+        grossProfit: tally.grossProfit,
+        grossLoss: tally.grossLoss,
+        charges: tally.charges,
+        returnPercent: ratioOf(tally.netProfit, capital),
+        tradeCount: tally.tradeCount,
+        openTradeCount: tally.openTradeCount,
+        wins: tally.wins,
+        losses: tally.losses,
+        scratches: tally.scratches,
+        winRate: decided === 0 ? null : tally.wins / decided,
+        averageWin: tally.wins === 0 ? 0 : tally.winTotal / tally.wins,
+        averageLoss: tally.losses === 0 ? 0 : -tally.lossTotal / tally.losses,
+        expectancy,
+        expectancyStandardError: standardErrorOf(trades, expectancy, tally.tradeCount),
+        profitFactor: tally.grossLoss > 0 ? tally.grossProfit / tally.grossLoss : null,
+        maxDrawdown: depth.maxDrawdown,
+        maxDrawdownPercent: depth.maxDrawdownPercent,
+        maxDrawdownAt: depth.maxDrawdownAt,
+        longestDrawdownBars: depth.longestDrawdownBars,
+        averageBarsHeld: tally.heldCount === 0 ? null : tally.heldTotal / tally.heldCount,
+        barsInMarket: barsInMarketOver(trades, equity),
+        barCount: equity.length,
+    };
+}
+/**
+ * One pass over the trades, in the order they are given.
+ *
+ * A trade wins or loses on its net after charges, and its gross is what it
+ * contributes to the gross figures: "the sum of the winning trades, before
+ * charges" is two statements and this is where they meet. The one arrangement
+ * that reads oddly is a trade whose gross was positive and whose charges took
+ * it under, which lands in the losses and takes its positive gross with it,
+ * lowering the gross loss. That is on purpose. The alternative is a trade
+ * counted as a loser in one figure and a winner in another, and a profit factor
+ * whose two halves are counted over different sets is worse than one whose
+ * magnitude is odd on a trade that barely moved.
+ *
+ * What is not on purpose, and is why `profitFactor` is null rather than a ratio
+ * whenever this figure is not above zero: enough of those trades and the gross
+ * loss reaches zero or goes under, and dividing by it reported a profit factor
+ * of minus a half. A statistic being odd is a thing a reader can weigh. A
+ * statistic being negative where every use of it is a non-negative ratio is a
+ * number nobody can act on.
+ */
+function tallyOf(trades) {
+    let netProfit = 0;
+    let grossProfit = 0;
+    let grossLoss = 0;
+    let charges = 0;
+    let tradeCount = 0;
+    let openTradeCount = 0;
+    let wins = 0;
+    let losses = 0;
+    let scratches = 0;
+    let winTotal = 0;
+    let lossTotal = 0;
+    let heldTotal = 0;
+    let heldCount = 0;
+    for (const trade of trades) {
+        charges += trade.charges;
+        if (trade.isOpen) {
+            openTradeCount += 1;
+            continue;
+        }
+        tradeCount += 1;
+        netProfit += trade.netProfit;
+        if (trade.barsHeld !== null) {
+            heldTotal += trade.barsHeld;
+            heldCount += 1;
+        }
+        if (trade.netProfit > 0) {
+            wins += 1;
+            winTotal += trade.netProfit;
+            grossProfit += trade.grossProfit;
+        }
+        else if (trade.netProfit < 0) {
+            losses += 1;
+            lossTotal += trade.netProfit;
+            grossLoss -= trade.grossProfit;
+        }
+        else {
+            scratches += 1;
+        }
+    }
+    return {
+        netProfit,
+        grossProfit,
+        grossLoss,
+        charges,
+        tradeCount,
+        openTradeCount,
+        wins,
+        losses,
+        scratches,
+        winTotal,
+        lossTotal,
+        heldTotal,
+        heldCount,
+    };
+}
+/**
+ * The deepest the curve went, named as one point rather than as three figures.
+ *
+ * The money, the fraction and the time all come from the same point, and the
+ * point is the deepest in money with the earliest one winning a tie. Taking the
+ * worst fraction from one bar and the worst money from another would describe a
+ * moment the run never had, and a reader comparing the two figures would find
+ * them inconsistent with every point in the curve they were drawn from.
+ *
+ * `longestDrawdownBars` is the longest run of consecutive bars under a peak: it
+ * starts at the first bar below one and ends at the bar before the recovery, so
+ * a run still under water at the last bar counts to the end. It is often the
+ * figure that actually stops a trader, and it is not the total number of bars
+ * spent under water, which is a different and much larger number.
+ */
+function depthOf(equity) {
+    let maxDrawdown = 0;
+    let maxDrawdownPercent = 0;
+    let maxDrawdownAt = null;
+    let longestDrawdownBars = 0;
+    let under = 0;
+    for (const point of equity) {
+        if (point.drawdown < maxDrawdown) {
+            maxDrawdown = point.drawdown;
+            maxDrawdownPercent = point.drawdownPercent;
+            maxDrawdownAt = point.time;
+        }
+        if (point.drawdown < 0) {
+            under += 1;
+            if (under > longestDrawdownBars)
+                longestDrawdownBars = under;
+        }
+        else {
+            under = 0;
+        }
+    }
+    return { maxDrawdown, maxDrawdownPercent, maxDrawdownAt, longestDrawdownBars };
+}
+/**
+ * The standard error of the expectancy: the sample deviation over the root of
+ * the count.
+ *
+ * The sample deviation, with the count less one under it, and not the
+ * population one. The trades a run took are a sample of the trades the strategy
+ * would take, which is the whole reason this figure is here, and the population
+ * spelling understates the spread by exactly the amount that matters on the
+ * short runs where the question is asked.
+ *
+ * Fewer than two closed trades has no spread to measure and gives zero.
+ */
+function standardErrorOf(trades, expectancy, tradeCount) {
+    if (tradeCount < 2)
+        return 0;
+    let squares = 0;
+    for (const trade of trades) {
+        if (trade.isOpen)
+            continue;
+        const away = trade.netProfit - expectancy;
+        squares += away * away;
+    }
+    return Math.sqrt(squares / (tradeCount - 1) / tradeCount);
+}
+//# sourceMappingURL=statistics.js.map

package/dist/core/accounting/statistics.js.map

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

package/dist/core/accounting/trades.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What a trade is, which is the definition every statistic is counted over.
+ *
+ * **A trade is one position reference, from the fill that first takes it away
+ * from zero to the fill that returns it to zero.** Nothing else is invented,
+ * because the engine already mints a reference per position, no order crosses
+ * zero, and every fill names the reference it settled however late it arrives.
+ *
+ * Everything awkward falls out of that rather than needing a rule of its own. A
+ * pyramided entry is more entry fills on one trade. A partial close is an exit
+ * fill that does not close the trade. A flip is two references and therefore
+ * two trades, which is what a reversing order already sends. A reference still
+ * holding something at the last bar is an open trade: it is in the list with
+ * `isOpen` true, it is counted in equity, and it is counted in no win rate.
+ *
+ * The definition is written in the specification before it is written here,
+ * because a rule decided in code is a rule two engines decide differently.
+ *
+ * ## What the fold reads, and what it refuses to work out for itself
+ *
+ * A fill carries the signed size of its reference either side of the
+ * settlement, so the fold reads what the position book did rather than
+ * recomputing it from quantities and sides. That is the whole of how a partial
+ * close, a pyramided entry and a reversal tell themselves apart: the move from
+ * one size to the other says how much of the fill closed what was held and how
+ * much of it opened something, and nothing else has to be inferred.
+ *
+ * It also settles the one case the definition does not cover on its face. A
+ * destination that fills more than the order asked takes a reference through
+ * zero rather than to it, and the position book reads the remainder as a
+ * position in the other direction opened at that fill's price. So the fold does
+ * the same: the fill closes the trade that was held and opens a second one on
+ * the same reference, at its own price and on its own bar. A trade that ran
+ * from a size to the other side of zero would report a quantity nothing was
+ * ever entered at.
+ *
+ * **Reducing a position does not move its average**, which is the position
+ * book's rule read here rather than a second one: a reducing fill adds to the
+ * exits and touches neither the entry quantity nor the entry cost. Every figure
+ * measured from the entry, the entry price a reader compares against and the
+ * excursion at each bar close, is measured from the price the units were
+ * actually bought at.
+ *
+ * **A charge lands whole on one trade and is never split.** It was rounded once
+ * for the fill that incurred it, and splitting it between the trade a crossing
+ * fill closed and the trade it opened would round it again and put a residue
+ * somewhere. So it is attributed to the trade the fill closed where it closed
+ * one, and to the trade it opened otherwise, which makes the charges of the
+ * trades add up to the charges of the fills exactly rather than nearly.
+ *
+ * **Gross profit is over the units that have left.** For a closed trade that is
+ * every unit it entered, which is the formula the report is specified with. For
+ * one still open it is what its exits have realised so far, which is a figure
+ * that is true rather than a zero standing in for money the run has already
+ * made.
+ */
+import type { BarMark, Contract, Money, RecordedFill } from './shapes.js';
+/** One round trip on one position reference. */
+export interface Trade {
+    /** 1-based, in the order the trade opened. */
+    readonly index: number;
+    readonly positionRef: number;
+    readonly side: 'long' | 'short';
+    readonly openedOnBar: number;
+    readonly openedAt: number | null;
+    readonly closedOnBar: number | null;
+    readonly closedAt: number | null;
+    readonly barsHeld: number | null;
+    /** Total units entered. */
+    readonly units: number;
+    /** Quantity weighted over the entry fills. */
+    readonly entryPrice: number;
+    /** Quantity weighted over the exit fills. */
+    readonly exitPrice: number | null;
+    readonly entries: number;
+    readonly exits: number;
+    readonly grossProfit: Money;
+    readonly charges: Money;
+    readonly netProfit: Money;
+    /**
+     * Excursion at bar closes while open. Favourable is zero or better, adverse
+     * zero or worse, and both are zero for a trade no bar closed on.
+     */
+    readonly maxFavourable: Money;
+    readonly maxAdverse: Money;
+    readonly isOpen: boolean;
+}
+/**
+ * The round trips a run's fills make up, in the order they opened.
+ *
+ * `charges[index]` is the money `fills[index]` was charged, rounded once by
+ * whoever computed it, so the two travel as one thing and nothing here rounds
+ * anything a second time. A caller with no cost model supplies no charges at
+ * all and every trade's charges are zero.
+ *
+ * The fills are read in `seq` order whatever order they are handed in, because
+ * `seq` is the order the engine folded them and a report that depended on the
+ * order a caller happened to be holding them in would not be reproducible. The
+ * marks are read in bar order for the same reason, and a bar is marked after
+ * every fill up to it has been folded, because a fill happens during its bar
+ * and the close comes after.
+ */
+export declare function tradesOf(fills: readonly RecordedFill[], charges: readonly Money[], marks: readonly BarMark[], contract: Contract): readonly Trade[];
+/**
+ * How much of a move from one size to another closed what was held.
+ *
+ * Exported to the module and not through its door: `markers.ts` asks the same
+ * question of the same fills, and the rule for what a move closed and what it
+ * opened is one rule. Two folds may read a fill differently and produce a
+ * marker for an entry the trade list calls an exit, so they read it here.
+ *
+ * A move to the other side of zero closed all of it, which is the case a
+ * destination that overfilled produces and the one this has to get right.
+ */
+export declare function closedBy(before: number, after: number): number;
+/** And how much of it opened something, which is the rest of the same move. */
+export declare function openedBy(before: number, after: number): number;
+//# sourceMappingURL=trades.d.ts.map

package/dist/core/accounting/trades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trades.d.ts","sourceRoot":"","sources":["../../../src/core/accounting/trades.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1E,gDAAgD;AAChD,MAAM,WAAW,KAAK;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,OAAO,EAAE,SAAS,KAAK,EAAE,EACzB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,QAAQ,EAAE,QAAQ,GACjB,SAAS,KAAK,EAAE,CAuBlB;AA0CD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9D"}