@tradecanvas/commons 1.51.0 → 1.53.0

package/dist/utils/resample.d.ts

@@ -1,13 +1,22 @@
 import { OHLCBar, TimeFrame } from '../types/ohlc.js';
+import { BucketOptions } from './time.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.
+ *
+ * With a `timeZone`, days, weeks, months and the hour frames that divide a
+ * day start at its midnight. Daily-or-longer bars stamped at 00:00 UTC are
+ * read as the dates they name (unless `dates` says otherwise), so a Monday
+ * stays in its own week west of UTC, and the weeks keep 00:00 UTC stamps.
  */
-export declare function resampleBars(bars: readonly OHLCBar[], target: TimeFrame, weekStartsOn?: 0 | 1): OHLCBar[];
+export declare function resampleBars(bars: readonly OHLCBar[], target: TimeFrame, options?: 0 | 1 | BucketOptions): 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.
+ * With a `timeZone`, a target whose buckets start at its midnight (days,
+ * weeks, months, 2h to 12h) takes only bars that line up with it: 1h for
+ * Ho Chi Minh City's days, not 4h.
  */
-export declare function pickBaseTimeframe(target: TimeFrame, supported: readonly TimeFrame[]): TimeFrame | null;
+export declare function pickBaseTimeframe(target: TimeFrame, supported: readonly TimeFrame[], options?: Pick<BucketOptions, 'timeZone'>): TimeFrame | null;
 //# sourceMappingURL=resample.d.ts.map

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

@@ -1 +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"}
+{"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;AAC1E,OAAO,EAA2F,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAMxI;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,CAAC,GAAG,CAAC,GAAG,aAAiB,GAAG,OAAO,EAAE,CAiBvH;AAwCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,SAAS,SAAS,EAAE,EAC/B,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAM,GAC5C,SAAS,GAAG,IAAI,CAelB"}

package/dist/utils/time.d.ts

@@ -47,13 +47,49 @@ export declare function barsAreDaily(data: ArrayLike<{
 }>): 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;
+/** Where the buckets of `timeframeBucketStart` (and `resampleBars`) start. */
+export interface BucketOptions {
+    /** The day weeks start on: 0 Sunday, 1 Monday (the default). */
+    weekStartsOn?: 0 | 1;
+    /**
+     * The zone whose midnight days start at: an IANA name such as
+     * `'Asia/Ho_Chi_Minh'` (daylight saving time included), or minutes east of
+     * UTC. Days, weeks, months and the hour frames that divide a day (2h, 3h,
+     * 4h, 6h, 8h, 12h) follow it; 1h and shorter frames keep their epoch floor,
+     * so the hour a fall-back night repeats stays two bars. Left out, UTC's.
+     */
+    timeZone?: string | number;
+    /**
+     * The times are bars a day long or more: one stamped at 00:00 UTC is the
+     * date it names, and keeps that date's UTC bucket and stamp. Other times
+     * are instants in `timeZone`.
+     */
+    dates?: boolean;
+}
+/** Whether `timeframeBucketStart` starts the buckets of `tf` at a zone's midnight when given one. */
+export declare function timeframeFollowsDays(tf: TimeFrame): boolean;
+/** Whether bars of `tf` are a day long or more (days, weeks, months), which feeds often stamp by date. */
+export declare function timeframeSpansDays(tf: TimeFrame): boolean;
 /**
  * Start of the bucket a timestamp falls into for a given timeframe.
  *
- * Intraday and daily frames are anchored to the Unix epoch (UTC) via fixed-ms
- * flooring. Weekly frames are anchored to Monday (or `weekStartsOn`), monthly
- * and yearly frames use calendar boundaries (1st of month, Jan for years) so
- * 3M aligns to quarters and 12M to calendar years.
+ * Minutes and hours floor to multiples of the frame since the Unix epoch.
+ * Days, weeks (from Monday, or `weekStartsOn`), months, quarters and years
+ * start at midnight, and the hour frames that divide a day (2h to 12h) count
+ * from it: UTC's, or `timeZone`'s when given (a day the clocks change is 23
+ * or 25 hours long, its 4h bucket 3 or 5). A 3M frame starts on quarters, a
+ * 12M one on 1 January. The third argument may also be the day weeks start
+ * on alone. Throws a RangeError for a zone the browser doesn't know.
+ */
+export declare function timeframeBucketStart(timestamp: number, tf: TimeFrame, options?: 0 | 1 | BucketOptions): number;
+/**
+ * The zone a bar a day long or more is dated in, whatever zone the chart
+ * shows (`tz`): UTC for one stamped at 00:00 UTC, the date it names; its
+ * exchange's zone (`exchangeZone`) for one stamped at the exchange's
+ * midnight, as the days a chart builds are; else `tz`, so a bar stamped at
+ * the browser's midnight still reads its own date there.
  */
-export declare function timeframeBucketStart(timestamp: number, tf: TimeFrame, weekStartsOn?: 0 | 1): number;
+export declare function barDateZone(timeMs: number, tz: TimeZoneSetting, exchangeZone?: string | null): TimeZoneSetting;
+/** The calendar parts a bar a day long or more is labelled with: its date, in the zone `barDateZone` gives. */
+export declare function barDateParts(timeMs: number, tz: TimeZoneSetting, exchangeZone?: string | null): TimeParts;
 //# sourceMappingURL=time.d.ts.map

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,EAAkB,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AA4C/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,eAAe;IACf,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"}
+{"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,EAAsC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AA4CzF,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,eAAe;IACf,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;AAQD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA8BD,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAE3D;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAEzD;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,SAAS,EACb,OAAO,GAAE,CAAC,GAAG,CAAC,GAAG,aAAiB,GACjC,MAAM,CAYR;AA2BD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,CAI9G;AAED,+GAA+G;AAC/G,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAEzG"}

package/dist/utils/timezone.d.ts

@@ -10,6 +10,8 @@ export declare function isValidTimeZone(zone: string): boolean;
  * time included. Throws a RangeError for a zone the browser doesn't know.
  */
 export declare function zoneOffsetMinutes(zone: string, timeMs: number): number;
+/** Whether `tz` keeps UTC's clock all year: a name of UTC itself, or an offset of 0. */
+export declare function isUtcTimeZone(tz: TimeZoneSetting): boolean;
 /** Minutes east of UTC at `timeMs` for any display timezone. */
 export declare function offsetAt(tz: TimeZoneSetting, timeMs: number): number;
 /**

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

@@ -1 +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"}
+{"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,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAE1D;AAED,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.51.0",
+  "version": "1.53.0",
   "type": "module",
   "description": "Shared types and utilities for @tradecanvas/chart",
   "license": "MIT",