@tradecanvas/commons 1.4.0 → 1.10.0

package/dist/utils/marketStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marketStatus.d.ts","sourceRoot":"","sources":["../../src/utils/marketStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAOD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CA4C3F"}

package/dist/utils/precision.d.ts

@@ -1,4 +1,5 @@
 import { PriceScaleMode } from '../types/rendering.js';
+import { PriceFormatter, PriceFraction } from '../types/chart.js';
 export declare function formatPrice(value: number, precision?: number, locale?: string): string;
 /**
  * Decimals the price axis uses for a visible price range: one more than its
@@ -17,6 +18,23 @@ export declare function autoPricePrecision(min: number, max: number): number;
  * Falls back to a plain price when a baseline is required but missing/zero.
  */
 export declare function formatPriceScaleLabel(price: number, mode: PriceScaleMode, baseline: number | undefined, precision?: number, locale?: string): string;
+/**
+ * `value` in fractions of a point: whole points, an apostrophe, then the
+ * fraction's numerator padded to the denominator's digits (`101'16` for
+ * 101.5 in 32nds). A `subDenominator` of 2 or 4 adds the half or quarter of
+ * that fraction as one more digit, as futures quote it (`101'165`, `110'162`,
+ * `110'167`). Rounds to the nearest step. A denominator that isn't a whole
+ * number above 1 gives plain digits.
+ */
+export declare function formatFraction(value: number, denominator: number, subDenominator?: number): string;
+/**
+ * The smallest step a fraction format prints (a 32nd; a quarter of one with
+ * `subDenominator` 4), or null for a denominator it can't print (it falls
+ * back to plain digits then).
+ */
+export declare function fractionTick(fraction: PriceFraction): number | null;
+/** The formatter a `priceFormat` option stands for: its function, its fraction's, or null for decimals. */
+export declare function priceFormatterFor(format: PriceFormatter | PriceFraction | null | undefined): PriceFormatter | null;
 export declare function formatVolume(value: number): string;
 export declare function detectPrecision(values: number[]): number;
 //# sourceMappingURL=precision.d.ts.map

package/dist/utils/precision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../src/utils/precision.ts"],"names":[],"mappings":"AAwBA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,MAAM,SAAU,GAAG,MAAM,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,SAAI,EACb,MAAM,SAAU,GACf,MAAM,CAWR;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAUxD"}
+{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../src/utils/precision.ts"],"names":[],"mappings":"AAwBA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,MAAM,SAAU,GAAG,MAAM,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,SAAI,EACb,MAAM,SAAU,GACf,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,SAAI,GAAG,MAAM,CAY7F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAInE;AAED,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAMlH;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAUxD"}

package/dist/utils/priceSource.d.ts

@@ -0,0 +1,15 @@
+import { OHLCBar } from '../types/ohlc.js';
+/** The price an indicator can be computed from. */
+export declare const PRICE_SOURCES: readonly ["close", "open", "high", "low", "hl2", "hlc3", "ohlc4", "hlcc4"];
+export type PriceSource = (typeof PRICE_SOURCES)[number];
+export declare function isPriceSource(value: unknown): value is PriceSource;
+/** A bar's price by source: `hl2` = (high + low) / 2, `hlc3`, `ohlc4`, `hlcc4` = (h + l + 2c) / 4. */
+export declare function sourcePrice(bar: OHLCBar, source: PriceSource): number;
+/** A source that is another indicator's line: `ind:<instanceId>:<key>`. */
+export declare function indicatorSource(instanceId: string, key: string): string;
+/** The indicator line a source refers to, or null for a price source or anything else. */
+export declare function parseIndicatorSource(value: unknown): {
+    instanceId: string;
+    key: string;
+} | null;
+//# sourceMappingURL=priceSource.d.ts.map

package/dist/utils/priceSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priceSource.d.ts","sourceRoot":"","sources":["../../src/utils/priceSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,mDAAmD;AACnD,eAAO,MAAM,aAAa,4EAA6E,CAAC;AAExG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAWrE;AAID,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI/F"}

package/dist/utils/resample.d.ts

@@ -0,0 +1,13 @@
+import { OHLCBar, TimeFrame } from '../types/ohlc.js';
+/**
+ * Aggregate bars (ascending, times in ms) into a coarser timeframe: per
+ * bucket (see `timeframeBucketStart`) the first open, the extremes, the last
+ * close and the summed volume. The input bars are not changed.
+ */
+export declare function resampleBars(bars: readonly OHLCBar[], target: TimeFrame, weekStartsOn?: 0 | 1): OHLCBar[];
+/**
+ * The coarsest of `supported` that builds `target` from whole bars (e.g. 7m
+ * from 1m, 90m from 30m, a quarter from months), or null when none does.
+ */
+export declare function pickBaseTimeframe(target: TimeFrame, supported: readonly TimeFrame[]): TimeFrame | null;
+//# sourceMappingURL=resample.d.ts.map

package/dist/utils/resample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resample.d.ts","sourceRoot":"","sources":["../../src/utils/resample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AAK1E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAE,CAAC,GAAG,CAAK,GAAG,OAAO,EAAE,CAgB5G;AAqBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAYtG"}

package/dist/utils/symbols.d.ts

@@ -0,0 +1,13 @@
+import { SymbolInfo } from '../types/symbol.js';
+/**
+ * Symbols matching `query`, best first: an exact ticker, then tickers that
+ * start with it, then names that contain it. `boost` adds to a match's score
+ * (say, for the quote currencies most traded). An empty query keeps the order
+ * given. At most `limit` results.
+ */
+export declare function rankSymbols(symbols: readonly SymbolInfo[], query: string, limit?: number, boost?: (info: SymbolInfo) => number): SymbolInfo[];
+/** Decimals in a price step: `'0.01000000'` → 2, `'1'` → 0, `1e-8` → 8. */
+export declare function stepDecimals(step: number | string): number;
+/** `'09:30'` → 570 (`'24:00'`, a day's end, → 1440), or null for anything that isn't a time of day. */
+export declare function sessionMinute(time: string): number | null;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/utils/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../../src/utils/symbols.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAWrD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,KAAK,EAAE,MAAM,EACb,KAAK,SAAK,EACV,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,GACnC,UAAU,EAAE,CAad;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAQ1D;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD"}

package/dist/utils/time.d.ts

@@ -1,4 +1,14 @@
-import { TimeFrame } from '../types/ohlc.js';
+import { TimeFrame, TimeFrameUnit } from '../types/ohlc.js';
+import { TimeZoneSetting } from './timezone.js';
+/** A timeframe's count and unit, or null when `value` isn't one (`'7m'` → 7 minutes). */
+export declare function parseTimeframe(value: string): {
+    count: number;
+    unit: TimeFrameUnit;
+} | null;
+/** The trades per bar of a tick timeframe (`'100T'` → 100), or null for any other. */
+export declare function tickBarCount(timeframe: string): number | null;
+export declare function isTimeFrame(value: string): value is TimeFrame;
+/** Length of a timeframe in milliseconds (approximate for months); NaN for a non-timeframe. */
 export declare function timeframeToMs(tf: TimeFrame): number;
 export declare function formatTimestamp(timestamp: number, tf: TimeFrame): string;
 export declare function alignToTimeframe(timestamp: number, tf: TimeFrame): number;
@@ -10,21 +20,32 @@ export interface TimeParts {
     minutes: number;
 }
 /**
- * Calendar parts of a timestamp in either the browser-local timezone
- * (`tzOffsetMinutes === null`) or a fixed UTC offset (e.g. -300 for EST).
+ * Calendar parts of a timestamp in a display timezone: an IANA zone
+ * (`'America/New_York'`, daylight saving time included), a fixed UTC offset in
+ * minutes (e.g. -300 for EST) or the browser's zone (`null`).
  */
-export declare function timeParts(timeMs: number, tzOffsetMinutes: number | null): TimeParts;
+export declare function timeParts(timeMs: number, tz: TimeZoneSetting): TimeParts;
 /**
  * A bar with no time-of-day component (a daily, weekly, monthly or yearly candle — always anchored
  * to a calendar-day boundary, so hours/minutes read 00:00) needs the YEAR in its label instead: a
  * bare `month/day` is ambiguous across years, and `00:00` tells a trader nothing. Detected from the
  * parts themselves rather than a separate timeframe parameter, so every caller that formats a bar's
- * time gets the same rule for free. The one false positive this accepts — a genuine intraday bar
- * landing exactly on midnight — is acceptable: real trade-driven timestamps essentially never do.
+ * time gets the same rule for free. It can't tell an hourly bar at midnight from a daily one:
+ * callers that have the series ask `barsAreDaily` first and fall back to this.
  */
 export declare function isDateOnly(parts: Pick<TimeParts, 'hours' | 'minutes'>): boolean;
-/** A short timezone label like `UTC-5` or `UTC+5:30` (browser-local when null). */
-export declare function tzLabel(tzOffsetMinutes: number | null): string;
+/**
+ * Whether bars are a day apart or more (daily, weekly, monthly): their labels
+ * then carry a date and no time of day, while an hourly bar at midnight keeps
+ * its time. Read from the smallest gap among the first bars, so a weekend or
+ * a missing session doesn't make an intraday series look daily. Undefined for
+ * fewer than two bars.
+ */
+export declare function barsAreDaily(data: ArrayLike<{
+    time: number;
+}>): boolean | undefined;
+/** A short label like `UTC-5` or `UTC+5:30` for the offset in force at `atMs` (default: now). */
+export declare function tzLabel(tz: TimeZoneSetting, atMs?: number): string;
 /**
  * Start of the bucket a timestamp falls into for a given timeframe.
  *

package/dist/utils/time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AA+BlD,wBAAgB,aAAa,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAEnD;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAUxE;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAGzE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAmBnF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAE/E;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAO9D;AAWD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,SAAS,EACb,YAAY,GAAE,CAAC,GAAG,CAAK,GACtB,MAAM,CAyBR"}
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AA2C/D,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAK3F;AAKD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAKnD;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAUxE;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAGzE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,SAAS,CAmBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAE/E;AAKD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,OAAO,GAAG,SAAS,CAUnF;AAED,iGAAiG;AACjG,wBAAgB,OAAO,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,GAAE,MAAmB,GAAG,MAAM,CAO9E;AAKD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,SAAS,EACb,YAAY,GAAE,CAAC,GAAG,CAAK,GACtB,MAAM,CAyBR"}

package/dist/utils/timezone.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The display timezone: an IANA name (`'America/New_York'`, `'UTC'`), a fixed
+ * offset in minutes east of UTC (`-300`), or null for the browser's own zone.
+ */
+export type TimeZoneSetting = string | number | null;
+/** Whether `zone` is a time zone this browser knows (an IANA name such as `'Europe/London'`). */
+export declare function isValidTimeZone(zone: string): boolean;
+/**
+ * The zone's offset from UTC, in minutes east, at `timeMs` — daylight saving
+ * time included. Throws a RangeError for a zone the browser doesn't know.
+ */
+export declare function zoneOffsetMinutes(zone: string, timeMs: number): number;
+/** Minutes east of UTC at `timeMs` for any display timezone. */
+export declare function offsetAt(tz: TimeZoneSetting, timeMs: number): number;
+/**
+ * The instant whose wall clock in `tz` reads `wallMs` (a wall-clock time
+ * written as if it were UTC, e.g. `Date.UTC(2026, 0, 15, 9, 30)`). A time
+ * that occurs twice (clocks going back) is its first occurrence; a time a
+ * spring-forward skips moves forward by the jump (02:30 → 03:30).
+ */
+export declare function wallToUtc(wallMs: number, tz: TimeZoneSetting): number;
+/**
+ * `Intl.DateTimeFormat#format` for dates in a display timezone, cached per
+ * locale, options and zone (building a format costs ~40µs). A fixed offset
+ * is applied by shifting the instant and formatting it as UTC.
+ */
+export declare function zonedDateFormatter(locale: string, options: Intl.DateTimeFormatOptions, tz: TimeZoneSetting): (ms: number) => string;
+//# sourceMappingURL=timezone.d.ts.map

package/dist/utils/timezone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/utils/timezone.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AA6CrD,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAetE;AA4CD,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,EAAE,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,MAAM,CAQrE;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,CAAC,qBAAqB,EACnC,EAAE,EAAE,eAAe,GAClB,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAgBxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tradecanvas/commons",
-  "version": "1.4.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "Shared types and utilities for @tradecanvas/chart",
   "license": "MIT",