@adaptic/utils 0.0.1030 → 0.0.1032

package/dist/types/performance-metrics.d.ts

@@ -78,10 +78,22 @@ export declare function alignReturnsByDate(portfolioHistory: PortfolioHistory, b
     alignedBenchmarkReturns: number[];
 };
 /**
- * Calculates the beta of the portfolio compared to a benchmark.
- * @param portfolioReturns - Array of portfolio returns.
- * @param benchmarkReturns - Array of benchmark returns.
- * @returns An object containing beta and intermediate calculations.
+ * Beta of a portfolio against a benchmark, from paired period returns.
+ *
+ * The two series are index-aligned pairs by contract: every mean, covariance
+ * and variance below is taken over the SAME row set. A length mismatch is
+ * therefore reported as invalid input rather than absorbed, because dividing
+ * one series' sum by the other series' length produces a mean of a population
+ * that does not exist — a number with no cohort, which is the failure this
+ * return type exists to make impossible.
+ *
+ * An uncomputable beta is returned as the unavailable branch, never as `0`.
+ * Zero beta is a claim of no market exposure, and downstream alpha attributes
+ * the entire benchmark move to the strategy when it believes that claim.
+ *
+ * @param portfolioReturns - Portfolio period returns.
+ * @param benchmarkReturns - Benchmark period returns, index-aligned to the portfolio.
+ * @returns The beta components with their cohort, or a typed unavailable result.
  */
 export declare function calculateBetaFromReturns(portfolioReturns: number[], benchmarkReturns: number[]): CalculateBetaResult;
 /**

package/dist/types/performance-metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"performance-metrics.d.ts","sourceRoot":"","sources":["../../src/performance-metrics.ts"],"names":[],"mappings":"AASA,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EAEnB,uBAAuB,EACvB,UAAU,EAEX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC7B,MAAM,uBAAuB,CAAC;AAgD/B;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,MAAM,EACN,aAAa,GACd,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiF3C;AAwBD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAqMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAiOD;AAkCD,UAAU,cAAc;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,cAAc,CAuHhB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,YAAY,EAAE,GAC5B;IAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAAC,uBAAuB,EAAE,MAAM,EAAE,CAAA;CAAE,CAiF1E;AAkFD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CAoErB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAmHjB;AA+BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;CAChD,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsB1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,MAAM,EACN,MAAM,EACN,SAAS,EACT,aAAa,GACd,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0J5D"}
+{"version":3,"file":"performance-metrics.d.ts","sourceRoot":"","sources":["../../src/performance-metrics.ts"],"names":[],"mappings":"AASA,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EAEnB,uBAAuB,EACvB,UAAU,EAEX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC7B,MAAM,uBAAuB,CAAC;AAqD/B;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,MAAM,EACN,aAAa,GACd,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiF3C;AAwBD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAqMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CA+OD;AAkCD,UAAU,cAAc;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,cAAc,CAuHhB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,YAAY,EAAE,GAC5B;IAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAAC,uBAAuB,EAAE,MAAM,EAAE,CAAA;CAAE,CAiF1E;AAkFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CA2ErB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAmHjB;AA+BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;CAChD,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsB1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,MAAM,EACN,MAAM,EACN,SAAS,EACT,aAAa,GACd,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0J5D"}

package/dist/types/sample-statistic.d.ts

@@ -0,0 +1,123 @@
+/**
+ * A measured statistic and the cohort it was measured on, carried as one
+ * inseparable value.
+ *
+ * A ratio is meaningless without the population it was taken over: the same
+ * `0.42` is a strong result on 2,000 trades and noise on five, and a `0.0`
+ * returned because nothing could be computed is indistinguishable from a `0.0`
+ * that was genuinely measured. Both confusions are the same error — a number
+ * read apart from its unit and its cohort — and both have produced wrong
+ * conclusions from correct arithmetic.
+ *
+ * This type removes the option. Every statistic shaped by a population carries
+ * `sampleCount` (how many observations actually entered the computation) and
+ * `coverage` (what fraction of the observations the caller offered were usable),
+ * on BOTH branches: an unavailable statistic still reports how much data it
+ * saw, because "we had nothing" and "we had 900 rows and still could not
+ * compute it" are different facts with different responses.
+ *
+ * Absence is a branch of the union rather than a sentinel value. There is no
+ * number a caller can read without first proving the statistic exists, which is
+ * what keeps an unknown from silently becoming a zero on its way to a decision.
+ *
+ * @module sample-statistic
+ */
+/**
+ * Why a statistic could not be computed from the observations offered.
+ *
+ * The distinctions are the point: a caller that cannot tell "too few rows" from
+ * "the rows were unusable" from "the population is degenerate" cannot tell a
+ * warm-up from a data outage from a genuinely constant series, and will treat
+ * all three the same way.
+ */
+export type StatisticUnavailableReason = 
+/** Fewer usable observations than the computation requires. */
+"insufficient_samples"
+/** Observations were offered but none survived validation (non-finite, unpaired). */
+ | "no_usable_samples"
+/** Enough usable observations, but the population cannot support the statistic
+ *  (a zero-variance denominator, an undefined ratio). */
+ | "degenerate_population"
+/** The request itself is malformed — mismatched series lengths, a non-positive window. */
+ | "invalid_input";
+/**
+ * How many observations a statistic was actually computed from, against how
+ * many the caller offered.
+ *
+ * `coverage` is the ratio that makes silent row-dropping visible: a function
+ * that filters non-finite rows and reports only the surviving statistic hides
+ * the size of what it discarded, and a statistic computed on 12% of the
+ * requested window is a different claim from the same number computed on all
+ * of it.
+ */
+export interface SampleCohort {
+    /** Observations that entered the computation. Never negative. */
+    readonly sampleCount: number;
+    /** Observations the caller offered, or the window width the caller asked for. */
+    readonly requestedCount: number;
+    /** `sampleCount / requestedCount`, clamped to [0, 1]; `0` when nothing was requested. */
+    readonly coverage: number;
+}
+/** A statistic that was computed, carrying the cohort it was computed on. */
+export interface AvailableStatistic<T> extends SampleCohort {
+    readonly available: true;
+    /** The measured value. */
+    readonly value: T;
+}
+/** A statistic that could not be computed, still carrying what data was seen. */
+export interface UnavailableStatistic extends SampleCohort {
+    readonly available: false;
+    /** Which class of failure prevented the computation. */
+    readonly reason: StatisticUnavailableReason;
+    /** Human-readable specifics, for logs and error messages. Never parsed. */
+    readonly detail: string;
+}
+/**
+ * A statistic that either exists with its cohort, or does not exist and says
+ * why — never a number standing in for an unknown.
+ */
+export type SampleStatistic<T> = AvailableStatistic<T> | UnavailableStatistic;
+/**
+ * Build the cohort descriptor for a computation.
+ *
+ * `coverage` is derived here rather than supplied, so it cannot drift from the
+ * counts it claims to summarise. A zero request yields zero coverage: no
+ * observations were asked for, so none were covered, and the alternative (`1`)
+ * would report a vacuous computation as fully covered.
+ *
+ * @param requestedCount - Observations offered, or the window width requested.
+ * @param sampleCount - Observations that entered the computation.
+ * @returns The cohort descriptor with `coverage` derived from the two counts.
+ * @throws When either count is negative or non-finite, which is a programming
+ *         error rather than a data condition.
+ */
+export declare function sampleCohort(requestedCount: number, sampleCount: number): SampleCohort;
+/**
+ * Wrap a computed value with its cohort.
+ *
+ * @param value - The measured statistic.
+ * @param cohort - The cohort it was measured on.
+ * @returns The available branch of {@link SampleStatistic}.
+ */
+export declare function availableStatistic<T>(value: T, cohort: SampleCohort): AvailableStatistic<T>;
+/**
+ * Record that a statistic could not be computed, and what was seen instead.
+ *
+ * @param reason - Which class of failure prevented the computation.
+ * @param detail - Specifics for logs; never machine-parsed.
+ * @param cohort - What data was available when the attempt was abandoned.
+ * @returns The unavailable branch of {@link SampleStatistic}.
+ */
+export declare function unavailableStatistic(reason: StatisticUnavailableReason, detail: string, cohort: SampleCohort): UnavailableStatistic;
+/**
+ * Narrow a statistic to its available branch.
+ *
+ * Exists so consumers in other packages can discriminate without restating the
+ * predicate, and so the discriminant stays a single named concept if the shape
+ * ever grows a third branch.
+ *
+ * @param statistic - The statistic to test.
+ * @returns Whether the statistic carries a value.
+ */
+export declare function isAvailable<T>(statistic: SampleStatistic<T>): statistic is AvailableStatistic<T>;
+//# sourceMappingURL=sample-statistic.d.ts.map

package/dist/types/sample-statistic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-statistic.d.ts","sourceRoot":"","sources":["../../src/sample-statistic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B;AACpC,+DAA+D;AAC7D,sBAAsB;AACxB,qFAAqF;GACnF,mBAAmB;AACrB;yDACyD;GACvD,uBAAuB;AACzB,0FAA0F;GACxF,eAAe,CAAC;AAEpB;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,YAAY;IACzD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,YAAY,CAkBd;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,YAAY,GACnB,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,0BAA0B,EAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,GAC5B,SAAS,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAEpC"}

package/dist/types/schemas/alpaca-schemas.d.ts

@@ -141,8 +141,8 @@ export declare const AlpacaPositionSchema: z.ZodObject<{
     asset_class: string;
     side: "short" | "long";
     qty: string;
-    asset_id: string;
     exchange: string;
+    asset_id: string;
     asset_marginable: boolean;
     qty_available: string;
     avg_entry_price: string;
@@ -160,8 +160,8 @@ export declare const AlpacaPositionSchema: z.ZodObject<{
     asset_class: string;
     side: "short" | "long";
     qty: string;
-    asset_id: string;
     exchange: string;
+    asset_id: string;
     asset_marginable: boolean;
     qty_available: string;
     avg_entry_price: string;
@@ -200,8 +200,8 @@ export declare const AlpacaPositionsArraySchema: z.ZodArray<z.ZodObject<{
     asset_class: string;
     side: "short" | "long";
     qty: string;
-    asset_id: string;
     exchange: string;
+    asset_id: string;
     asset_marginable: boolean;
     qty_available: string;
     avg_entry_price: string;
@@ -219,8 +219,8 @@ export declare const AlpacaPositionsArraySchema: z.ZodArray<z.ZodObject<{
     asset_class: string;
     side: "short" | "long";
     qty: string;
-    asset_id: string;
     exchange: string;
+    asset_id: string;
     asset_marginable: boolean;
     qty_available: string;
     avg_entry_price: string;