openalgo-script 0.2.0 → 0.5.0

package/dist/core/accounting/charges.js

@@ -0,0 +1,362 @@
+/**
+ * What a fill costs, as an ordered list of lines the platform brings.
+ *
+ * **The language has three commission spellings and a slippage in ticks, and a
+ * real cost stack is not shaped like that.** It is a flat fee, a percentage, a
+ * charge levied on a charge, and a tax that applies to one side of the trade
+ * only. Teaching the language one market's stack would be teaching it a market;
+ * so the platform passes a schedule instead, and the language keeps the three
+ * spellings it has, which turn into a schedule of one line.
+ *
+ * **Order is part of the result.** The lines are applied in the order they are
+ * declared, a line charged on other lines may only name lines declared before
+ * it, and that is what makes a schedule evaluable in exactly one order. Two
+ * engines that disagree about the order disagree about the money, and a
+ * disagreement in the last bit is still a failed conformance comparison
+ * (`conformance.md` 6).
+ *
+ * **Where it is applied is not here.** `stdlib.md` 17.1 puts slippage and
+ * commission on the destination: the engine folds the price it is told and
+ * never adjusts one, so a cost model inside the ledger would be the engine
+ * moving a price, which is the one thing the invariant forbids. This module
+ * says what a charge is and works out what one fill came to; the destination is
+ * what charges it, and the slippage a schedule carries is measured and applied
+ * there, against the tick size this module only refuses the absence of.
+ *
+ * **What is charged to a fill, and only to a fill.** Every line is measured
+ * against this fill and nothing else, so a tier that changes with the month's
+ * cumulative volume, a cap counted per day rather than per application, and
+ * margin and its interest are outside this model rather than approximated
+ * inside it. A cost model that quietly approximates is a report that is wrong
+ * in the strategy's favour and says nothing about it.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+/**
+ * The most digits money is rounded to, and why there is a ceiling at all.
+ *
+ * A rounding scale is a power of ten and a binary64 holds about fifteen
+ * significant decimal digits, so past this the scale itself is approximate and
+ * the rounding stops being arithmetic and becomes noise. A currency with more
+ * than fifteen decimal places is not a currency this module is refusing to
+ * support; it is a digit count nobody stated on purpose.
+ */
+const MAX_DIGITS = 15;
+/** A percentage, as the declaration states one, over the fraction a rate is. */
+const PERCENT = 100;
+/** What a refusal calls the setting it is about, `errors.md` OS6021. */
+const SETTING = 'The charge schedule';
+/**
+ * Where a refusal about a setting points.
+ *
+ * Nowhere in the script, because a schedule is not something anybody wrote in
+ * one: it is what the host stated before the first bar, and a caret drawn under
+ * a line of the strategy would blame the one party who did not choose it. The
+ * engine gives a load-time failure the same position for the same reason, and
+ * the number is written here rather than imported from it because this module
+ * imports no engine, which is what lets a stored record be reported again with
+ * no engine present.
+ */
+const NO_POSITION = { offset: 0, length: 0, line: 0, column: 0 };
+/**
+ * What one fill cost, line by line and in total.
+ *
+ * **The lines are the arithmetic and the total is the money.** Each line's
+ * amount is computed in binary64 and left unrounded, and the per-fill total is
+ * rounded once, half to even, to the contract's digits. Rounding each line
+ * would round once per line, and two engines rounding in two places disagree in
+ * the last bit, which is a failed conformance comparison months later on
+ * somebody else's engine. So a reader adding the lines up by hand may land a
+ * fraction of the last digit away from the total, and that is the honest way
+ * round: the total is the figure the report accumulates.
+ *
+ * **Half to even, and not the language's own rounding.** `round()` in the
+ * language is halves away from zero, because a price a trader reads should
+ * agree with what they would write down (`stdlib.md` 8.1). Money folded over
+ * thousands of fills is a different question: away from zero biases every exact
+ * half upward, and half a unit of the last digit per fill is a bias that grows
+ * with the length of the backtest. Two rules, two reasons, both written down.
+ *
+ * **A line that does not apply to this side is not in the breakdown at all.** A
+ * name beside a zero reads as a charge that was levied and came to nothing,
+ * which is not what happened, and a later line levied on that name is levied on
+ * nothing, which is exactly what a tax on one side of the trade does.
+ */
+export function chargeFor(schedule, fill, contract) {
+    const turnover = fill.units * fill.price * contract.pointValue;
+    const applied = [];
+    for (const line of schedule.lines) {
+        if (line.side !== 'both' && line.side !== fill.side)
+            continue;
+        const base = baseOf(line, turnover, fill.units, applied);
+        applied.push({ name: line.name, amount: bounded(line.rate * base, line) });
+    }
+    let exact = 0;
+    for (const one of applied)
+        exact += one.amount;
+    return { lines: applied, total: roundMoney(exact, contract.digits) };
+}
+/**
+ * What a line's rate is measured against, for this fill.
+ *
+ * The earlier lines are searched rather than indexed. An index would be a map,
+ * and this module has promised to depend on no map's iteration order; a
+ * schedule is a handful of lines, so the search costs nothing and the promise
+ * costs one less thing to be careful about.
+ */
+function baseOf(line, turnover, units, applied) {
+    if (line.base === 'turnover')
+        return turnover;
+    if (line.base === 'units')
+        return units;
+    if (line.base === 'order')
+        return 1;
+    // 'charges': the sum of the named earlier lines, as they were charged on this
+    // fill. A name whose line did not apply to this side is absent and adds
+    // nothing, which is a charge levied on a charge that was never taken.
+    let sum = 0;
+    for (const named of line.of) {
+        for (const one of applied) {
+            if (one.name === named)
+                sum += one.amount;
+        }
+    }
+    return sum;
+}
+/**
+ * The floor and the cap, per application.
+ *
+ * Both together is the common brokerage plan: a fraction of turnover, never
+ * less than one amount and never more than another. Which is applied first does
+ * not decide the answer, because a floor above a cap is refused before the
+ * first bar rather than resolved here by whichever comparison runs first.
+ */
+function bounded(raw, line) {
+    let amount = raw;
+    if (line.min !== null && amount < line.min)
+        amount = line.min;
+    if (line.max !== null && amount > line.max)
+        amount = line.max;
+    return amount;
+}
+/**
+ * One money figure, rounded once, halves to even.
+ *
+ * A digit count this cannot round by is one `scheduleProblem` refuses before
+ * the first bar. If one arrives anyway the amount is returned as it stands,
+ * because a scale of ten to the power of something impossible turns money into
+ * a number JSON carries as null, and an unrounded figure is worth more.
+ */
+function roundMoney(amount, digits) {
+    if (!Number.isFinite(amount))
+        return amount;
+    if (!Number.isInteger(digits) || digits < 0 || digits > MAX_DIGITS)
+        return amount;
+    const scale = 10 ** digits;
+    const scaled = amount * scale;
+    const below = Math.floor(scaled);
+    const fraction = scaled - below;
+    let whole = below;
+    if (fraction > 0.5)
+        whole = below + 1;
+    else if (fraction === 0.5 && below % 2 !== 0)
+        whole = below + 1;
+    const money = whole / scale;
+    // A negative zero is the same money as a zero and a different set of bytes.
+    return money === 0 ? 0 : money;
+}
+/**
+ * The declaration's own cost model, as the one schedule this module evaluates.
+ *
+ * **The declaration is not a second cost engine.** Its three commission
+ * spellings are a schedule of one line: a flat fee is a line charged per fill,
+ * a per unit fee is a line charged per unit, and a percentage is a line charged
+ * on turnover. A second evaluator for the declaration would be the same money
+ * computed two ways, and the day the two disagreed the report and the
+ * platform's own cost panel would both be defensible.
+ *
+ * **A commission of zero is no line at all**, rather than a line charging
+ * nothing. A zero line would put a name in every breakdown, and it would make a
+ * declaration that states no commission indistinguishable from one that states
+ * a commission, which is the distinction a run has to make before it accepts a
+ * schedule from the host as well.
+ *
+ * **A flat fee is charged per fill**, which is the one place `language.md` 13.3
+ * lets a reasonable person read the words two ways: per order, or per completed
+ * round trip. A charge is attributed to the fill that incurred it everywhere in
+ * this module, because that is what attributes it to a trade, so a round trip of
+ * two fills is charged twice.
+ *
+ * The currency and the digit count are parameters because neither is the
+ * declaration's to state: the declaration's currency is a label and is often
+ * left blank, and money rounding is a fact about the contract. A default here
+ * would be this module inventing a rounding rule for somebody else's market.
+ *
+ * `commissionType`'s value set is declared once, in `check/declaration.ts`, and
+ * is not restated here: what is below is a mapping from each spelling to the
+ * line it means. A program reaching this has been checked, so a fourth spelling
+ * cannot arrive, and the spelling that falls through is the declaration's own
+ * default rather than a shape this module made up.
+ */
+export function scheduleFromDeclaration(commission, commissionType, slippage, currency, digits) {
+    return {
+        currency,
+        digits,
+        slippageTicks: slippage,
+        lines: commission === 0 ? [] : [commissionLine(commission, commissionType)],
+        source: 'declaration',
+    };
+}
+/** The one line a declared commission is, in the base its spelling names. */
+function commissionLine(commission, commissionType) {
+    if (commissionType === 'perUnit')
+        return only('units', commission);
+    if (commissionType === 'percent')
+        return only('turnover', commission / PERCENT);
+    return only('order', commission);
+}
+/** A line with no bounds, on both sides, levied on nothing: the declaration's shape. */
+function only(base, rate) {
+    return { name: 'commission', base, side: 'both', rate, min: null, max: null, of: [] };
+}
+/**
+ * Why this schedule cannot be carried out, or null.
+ *
+ * **Asked before the first bar, and answered once.** Everything here is a fact
+ * about the schedule rather than about any fill, so a run that would produce a
+ * number nobody can explain is refused while nothing has been computed and the
+ * cost of correcting it is one run. The contract is optional because a schedule
+ * is checkable on its own: what it adds is the three questions that need both,
+ * which are the currency the money is in, the digits it is rounded to, and the
+ * tick a slippage in ticks is measured in.
+ *
+ * The first problem found is the one reported. A list of everything wrong with
+ * a schedule reads as a worse schedule than it is, and it is corrected one line
+ * at a time regardless.
+ */
+export function scheduleProblem(schedule, contract = null) {
+    const problem = moneyProblem(schedule, contract) ??
+        slippageProblem(schedule, contract) ??
+        linesProblem(schedule.lines);
+    if (problem === null)
+        return null;
+    return diagnosticFor('OS6021', NO_POSITION, { setting: SETTING, problem });
+}
+/**
+ * The currency the money is in and the digits it is rounded to.
+ *
+ * A schedule states both and so does the contract, and the two are compared
+ * here rather than one of them being quietly preferred. A schedule in another
+ * currency charges a fill in money the contract is not priced in, and a total
+ * nobody can add to the profit is worse than no total. A schedule rounding to
+ * other digits is the same fact stated twice and left to disagree.
+ */
+function moneyProblem(schedule, contract) {
+    const digits = schedule.digits;
+    if (!Number.isInteger(digits) || digits < 0 || digits > MAX_DIGITS) {
+        return `it rounds money to ${digits} digits, and a digit count is a whole number from 0 to ${MAX_DIGITS}`;
+    }
+    if (schedule.currency.trim() === '') {
+        return 'it names no currency, so what it charges is a number with no unit on it';
+    }
+    if (contract === null)
+        return null;
+    if (schedule.currency !== contract.currency) {
+        return `it charges in ${schedule.currency} and the contract is priced in ${contract.currency}`;
+    }
+    if (digits !== contract.digits) {
+        return `it rounds money to ${digits} digits and the contract rounds to ${contract.digits}`;
+    }
+    return null;
+}
+/**
+ * The slippage, which this module refuses and does not apply.
+ *
+ * A slippage in ticks with no tick size to measure a tick in would charge
+ * nothing at all, and a backtest that silently charges nothing is one that lies
+ * in the strategy's favour. It is refused here, where the schedule is checked,
+ * rather than at the fill, where a zero looks like a cost model that ran.
+ */
+function slippageProblem(schedule, contract) {
+    const ticks = schedule.slippageTicks;
+    if (!Number.isFinite(ticks) || ticks < 0) {
+        return `it states ${ticks} ticks of slippage, and slippage is adverse, so it is never negative`;
+    }
+    if (ticks === 0 || contract === null)
+        return null;
+    const tick = contract.tickSize;
+    if (tick === null || !(tick > 0)) {
+        return `it states ${ticks} ticks of slippage and the contract has no tick size to measure a tick in`;
+    }
+    return null;
+}
+/** Every line, in the order the schedule declares them, against the ones before it. */
+function linesProblem(lines) {
+    const declared = [];
+    for (const line of lines) {
+        const problem = lineProblem(line, declared);
+        if (problem !== null)
+            return problem;
+        declared.push(line.name);
+    }
+    return null;
+}
+/** One line, against the names declared before it. */
+function lineProblem(line, declared) {
+    const name = line.name;
+    if (name.trim() === '') {
+        return 'a line carries no name, and a line levied on charges names the lines it is levied on';
+    }
+    if (declared.includes(name)) {
+        return `two lines are named "${name}", so a line levied on that name is levied on two answers`;
+    }
+    if (!Number.isFinite(line.rate) || line.rate < 0) {
+        return `the line "${name}" charges a rate of ${line.rate}, and a charge is money taken, never given`;
+    }
+    return boundProblem(line) ?? levyProblem(line, declared);
+}
+/** The floor and the cap: money, not negative, and the floor no higher than the cap. */
+function boundProblem(line) {
+    const { max, min, name } = line;
+    if (min !== null && (!Number.isFinite(min) || min < 0)) {
+        return `the line "${name}" has a floor of ${min}, and a bound on a charge is money`;
+    }
+    if (max !== null && (!Number.isFinite(max) || max < 0)) {
+        return `the line "${name}" has a cap of ${max}, and a bound on a charge is money`;
+    }
+    if (min !== null && max !== null && min > max) {
+        return `the line "${name}" has a floor of ${min} above its cap of ${max}`;
+    }
+    return null;
+}
+/**
+ * What a line is levied on, which is the rule the whole ordering exists for.
+ *
+ * A line levied on lines not declared before it has no single evaluation order,
+ * so two engines would charge two different amounts and both would be
+ * defensible. Naming itself, naming a line declared after it and naming a line
+ * that is not in the schedule at all are one problem in three spellings, and
+ * they are reported as one: none of the three is declared before this line.
+ */
+function levyProblem(line, declared) {
+    const name = line.name;
+    if (line.base !== 'charges') {
+        if (line.of.length === 0)
+            return null;
+        return `the line "${name}" names ${line.of.length} lines to be levied on and its base is ${line.base}, so the names are read by nothing`;
+    }
+    if (line.of.length === 0) {
+        return `the line "${name}" is levied on charges and names none, so it is levied on nothing`;
+    }
+    const seen = [];
+    for (const named of line.of) {
+        if (!declared.includes(named)) {
+            return `the line "${name}" is levied on "${named}", which is not declared before it`;
+        }
+        if (seen.includes(named)) {
+            return `the line "${name}" is levied on "${named}" twice, so that line is charged on twice over`;
+        }
+        seen.push(named);
+    }
+    return null;
+}
+//# sourceMappingURL=charges.js.map

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

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

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

@@ -0,0 +1,191 @@
+/**
+ * The equity curve: one point per bar in the report window.
+ *
+ * **Marked to the close and to nothing else.** An intrabar extreme is a price
+ * the strategy could not have acted on, so it is not a profit it had, and a
+ * curve drawn through the extremes flatters every run that ever held a losing
+ * position. Where a bar's close is absent the previous mark carries and the
+ * point says so, rather than a zero a reader would compare against.
+ *
+ * **Drawdown is stated on equity including open profit**, and the basis is
+ * carried on every point rather than left to the reader: `drawdown` is the
+ * distance below the running peak, zero or negative, and `drawdownPercent` is
+ * that distance against the peak. A report whose drawdown basis is not written
+ * down is a report whose worst figure means a different thing to each reader.
+ *
+ * ## What the curve is folded from, and when each figure lands
+ *
+ * A trade list and a list of bar closes, and nothing else. A trade carries its
+ * own gross, its own charges and the two bars it lived between, so the fold is
+ * a sweep: bars in the order they arrived, trades in the order they opened.
+ *
+ * - **A trade's charges land on the bar it opened.** The trade list does not
+ *   carry the timing of the individual fills underneath it, so the cost has to
+ *   land somewhere, and the open is the one place that is never later than the
+ *   truth: an entry charge is paid the moment the trade is taken on, and an
+ *   exit charge cannot be paid before it. The alternative, landing the whole
+ *   cost at the close, shows a run carrying a position for two hundred bars as
+ *   having paid nothing for it, and leaves a trade that never closed paying
+ *   nothing at all.
+ * - **A trade's gross lands on the bar it closed**, because that is the bar it
+ *   stopped being an opinion and became a number. While it is open it is in
+ *   `openProfit` instead, marked to the close, and the two never overlap.
+ *
+ * So the last point of a full run carries every charge the run paid, open
+ * trades included, and every gross it realised, which is an identity the
+ * summary is asserted against rather than assumed to share.
+ *
+ * ## What a trade list cannot say, said here rather than discovered later
+ *
+ * A trade holds one entry price weighted over its entry fills and one exit
+ * price weighted over its exit fills, so a trade whose size changed while it
+ * was open is not visible in it: the size a trade held between its open and its
+ * close is the size it ended up entering, at the average price it ended up
+ * entering at. Both directions are wrong and they are wrong differently.
+ *
+ * - **A partial close** is marked at the full size from the bar the reduction
+ *   settled on, so the open profit of the part already closed is counted twice
+ *   over, once here and once in the realised total.
+ * - **A scale-in is the worse of the two**, because it is wrong from the
+ *   beginning rather than from the middle. A trade that buys a hundred at ten
+ *   and another hundred at twenty is marked, from the bar it first opened, as
+ *   two hundred units bought at fifteen. On the bars before the second entry it
+ *   is therefore marked five points under water on units it did not hold, and
+ *   the curve reports a drawdown the account never had. The summary's
+ *   `maxDrawdown` and `maxDrawdownPercent` are folded from this curve, so a
+ *   pyramiding strategy is reported as having risked more than it did.
+ *
+ * Neither reaches the realised total, which is folded from the fills: what is
+ * affected is `openProfit`, `exposure`, `equity` and every drawdown figure
+ * taken off the curve, on the bars a trade's size was not what it ended as.
+ *
+ * A curve folded from the fills rather than from the trades would have neither,
+ * and that is what fixes it: it needs each entry, exit and charge to land on
+ * the bar it settled on, which is a different fold from this one rather than a
+ * correction to it. It is written here because a limitation nobody wrote down
+ * is a limitation somebody finds inside a report they had already believed.
+ *
+ * ## Two preconditions, both of them the caller's
+ *
+ * The trades arrive in the order they opened, which is the order `Trade.index`
+ * states, and the bars arrive in the order they were loaded. Both are swept
+ * with a pointer rather than searched, because a report over fifty thousand
+ * bars that rescans its trade list on every one of them is a report nobody
+ * waits for.
+ *
+ * ## And a percentage here is a fraction of its basis
+ *
+ * `drawdownPercent` is `drawdown / runningPeak`, which is a fraction: a
+ * hundredth of a percent down is written `-0.0001` and not `-0.01`. One
+ * convention for every figure in this module that divides, because two figures
+ * spelled the same way in two units is a number a reader gets wrong once and
+ * never trusts again. The multiplication by a hundred belongs to whatever
+ * prints it.
+ */
+import type { BarMark, Contract, Money } from './shapes.js';
+import type { Trade } from './trades.js';
+/** One report bar's standing, folded from the fills settled up to it. */
+export interface EquityPoint {
+    readonly barIndex: number;
+    readonly time: number | null;
+    /** Cumulative gross of closed trades. */
+    readonly realised: Money;
+    /** Cumulative. */
+    readonly charges: Money;
+    /** Marked to this bar's close. */
+    readonly openProfit: Money;
+    /** capital + realised - charges. */
+    readonly cash: Money;
+    /** cash + openProfit. */
+    readonly equity: Money;
+    /** The open position's magnitude at this close. */
+    readonly exposure: Money;
+    /** equity - runningPeak, zero or negative. */
+    readonly drawdown: Money;
+    /** `drawdown / runningPeak`, a fraction and not a figure times a hundred. */
+    readonly drawdownPercent: number;
+    /**
+     * The distance above the running trough, zero or positive.
+     *
+     * Drawdown's mirror, and carried for the same reason drawdown is: it is the
+     * run's best stretch measured the same way its worst one is, so the two can
+     * be read against each other. A reader handed only the depth learns how bad
+     * it got and nothing about whether the run ever climbed far enough for that
+     * depth to be a giving back rather than a steady bleed.
+     */
+    readonly runUp: Money;
+    /**
+     * `runUp / runningTrough`, a fraction and not a figure times a hundred, and
+     * zero where the trough is not above zero.
+     *
+     * Not the same guard drawdown gets, because the two bases are not the same
+     * kind of number. The running peak starts at the capital and only ever rises,
+     * so a run with capital above zero has a peak above zero at every point. The
+     * running trough starts there and only ever falls, so an account that lost
+     * everything has a trough at or below zero, and from that bar on this figure
+     * is zero rather than a fraction. Zero is the wrong answer for a run that
+     * recovered, and it is reported anyway, because the alternative is a
+     * percentage against a negative basis: a positive climb reported as a
+     * negative fraction, which is the shape that once gave a profit factor of
+     * minus a half. `runUp` itself is unaffected and stays the figure to read on
+     * such a run.
+     */
+    readonly runUpPercent: number;
+}
+/**
+ * Whether this trade was still held at the close of this bar.
+ *
+ * The boundaries are the whole of the rule and both are decisions. A trade is
+ * held from the close of the bar it opened on, because an entry that settled
+ * during a bar is a position that bar ended holding. It is not held at the
+ * close of the bar it closed on, because that bar ended flat. So a trade
+ * opened and closed inside one bar is held at no close at all, which is what a
+ * run that was flat at every mark should report.
+ *
+ * Every figure in this module that asks which trades are open asks it here, so
+ * the curve, the exposure and the count of bars in the market cannot come to
+ * three different answers about one bar.
+ */
+export declare function openOnBar(trade: Trade, barIndex: number): boolean;
+/**
+ * A ratio against a basis that may not be there to divide by.
+ *
+ * Capital of zero and a peak of zero are both reachable, and both turn an
+ * honest division into a value JSON cannot carry: a report whose worst figure
+ * comes back `null` from a round trip is worse than one that says zero. A basis
+ * that is not positive has no ratio to state, so the figure beside it, which is
+ * money and is always true, is the one a reader is left with.
+ */
+export declare function ratioOf(value: number, basis: number): number;
+/**
+ * The curve, one point per report bar, in the order the bars arrived.
+ *
+ * Warmup bars are swept and not reported: their orders were real, so a trade
+ * opened during the warmup is already in the fold at the first point, with its
+ * charges already paid and its position already marked. A curve that began its
+ * fold at the first report bar would lose both, and would lose them silently.
+ *
+ * The running peak starts at the capital rather than at the first point, so a
+ * run that is down from its first bar is in drawdown at its first bar. Starting
+ * it at the first point would report every run as having begun at its high.
+ *
+ * The running trough starts at the capital for the same reason and not for a
+ * symmetrical one: a run that is up from its first bar has run up from the
+ * money it was given, which is the figure a reader is measuring against. Anchor
+ * it at the first point instead and a run that gapped up on bar zero reports
+ * that gain as having come from nowhere.
+ */
+export declare function equityOver(trades: readonly Trade[], marks: readonly BarMark[], contract: Contract, capital: Money): readonly EquityPoint[];
+/**
+ * How many of these bars ended with something held.
+ *
+ * Swept rather than searched: a sorted list of the bars trades opened on, a
+ * sorted list of the bars they closed on, and the running difference between
+ * how many of each have gone by. That is the boundary rule `openOnBar` states,
+ * arrived at from the other side, and the two are asserted to agree over a
+ * generated corpus rather than trusted to. A count that disagrees with the
+ * curve beside it about which bars were in the market is exactly the kind of
+ * defect a reader finds by adding two of the printed figures up.
+ */
+export declare function barsInMarketOver(trades: readonly Trade[], equity: readonly EquityPoint[]): number;
+//# sourceMappingURL=equity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"equity.d.ts","sourceRoot":"","sources":["../../../src/core/accounting/equity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,kBAAkB;IAClB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,KAAK,GACb,SAAS,WAAW,EAAE,CAyExB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,MAAM,CAuBR"}