# packages/core/src/features/viz/lib/utc-scale.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/viz/lib/utc-scale.ts#L118). [Back to reference](/reference/functions/utc-domains/)
1 import type { UTCScale } from "./utc-scale-component.js";
2 import type { LinearDomain, ResolvedUtcScale, ScaleRange } from "./types.js";
3 import { resolveLinearScale } from "./linear-scale.js";
4 const LIMIT = 8_640_000_000_000_000;
5 const DAY = 86_400_000;
6 
7 function timestamp(value: number, integer = false): number {
8   if (typeof value !== "number" || !Number.isFinite(value) || Math.abs(value) > LIMIT || (integer && !Number.isSafeInteger(value)))
9     throw new RangeError("UTC timestamps must be finite milliseconds within Date range; domain endpoints must be safe integers.");
10   return value;
11 }
12 function validateDomain(domain: LinearDomain): void {
13   if (!Array.isArray(domain) || domain.length !== 2)
14     throw new RangeError("UTC domain requires two endpoints.");
15   timestamp(domain[0], true);
16   timestamp(domain[1], true);
17 }
18 interface Cadence {
19   first: number;
20   last: number;
21   at(index: number): number;
22 }
23 function monthAt(ordinal: number): number {
24   const date = new Date(0);
25   date.setUTCFullYear(Math.floor(ordinal / 12), ((ordinal % 12) + 12) % 12, 1);
26   return date.getTime();
27 }
28 const fixedSteps = [1, 2, 5, 10, 20, 50, 100, 200, 500,
29   ...[1, 2, 5, 10, 15, 30].map(n => n * 1000),
30   ...[1, 2, 5, 10, 15, 30].map(n => n * 60_000),
31   ...[1, 2, 3, 6, 12].map(n => n * 3_600_000), DAY, 2 * DAY];
32 function selectCadence(lo: number, hi: number, count: number): Cadence {
33   for (const step of [...fixedSteps, 7 * DAY]) {
34     const offset = step === 7 * DAY ? -3 * DAY : 0;
35     const first = Math.floor((lo - offset) / step) + 1;
36     const last = Math.ceil((hi - offset) / step) - 1;
37     if (Math.max(0, last - first + 1) <= count - 2)
38       return { first, last, at: index => index * step + offset };
39   }
40   // Two Date objects for endpoint ordinals; candidate counting is arithmetic.
41   const start = new Date(lo), stop = new Date(hi);
42   const lowMonth = start.getUTCFullYear() * 12 + start.getUTCMonth();
43   const highMonth = stop.getUTCFullYear() * 12 + stop.getUTCMonth();
44   const highBoundary = stop.getUTCDate() === 1 && stop.getUTCHours() === 0 &&
45     stop.getUTCMinutes() === 0 && stop.getUTCSeconds() === 0 && stop.getUTCMilliseconds() === 0;
46   const steps = [1, 2, 3, 6,
47     ...Array.from({ length: 7 }, (_, exponent) => [1, 2, 5].map(n => 12 * n * 10 ** exponent)).flat()];
48   for (const step of steps) {
49     const first = Math.floor(lowMonth / step) + 1;
50     const last = Math.floor(highMonth / step) - (highBoundary && highMonth % step === 0 ? 1 : 0);
51     if (Math.max(0, last - first + 1) <= count - 2)
52       return { first, last, at: index => monthAt(index * step) };
53   }
54   // Every epoch-aligned cadence crosses year zero for a straddling domain.
55   // Two-tick output is endpoints-only; keep already integral millisecond bounds
56   // rather than overflow Date trying ever coarser calendar boundaries.
57   if (count === 2) return { first: lo + 1, last: hi - 1, at: index => index };
58   throw new RangeError("UTC could not select a bounded cadence.");
59 }
60 function tickCount(count: number): void {
61   if (!Number.isInteger(count) || count < 2 || count > 100)
62     throw new RangeError("UTC ticks count must be an integer from 2 to 100.");
63 }
64 function utcTicks(domain: LinearDomain, count: number): readonly number[] {
65   tickCount(count);
66   if (count === 2) return Object.freeze([...domain]);
67   const lo = Math.min(...domain), hi = Math.max(...domain);
68   const cadence = selectCadence(lo, hi, count);
69   const ticks = [lo];
70   for (let i = cadence.first; i <= cadence.last; i++) {
71     const value = cadence.at(i);
72     if (value > lo && value < hi) ticks.push(timestamp(value, true));
73   }
74   ticks.push(hi);
75   return Object.freeze(domain[0] > domain[1] ? ticks.reverse() : ticks);
76 }
77 export function resolveUtcScale(domain: LinearDomain, range: ScaleRange, reverse: boolean, width: number, height: number): ResolvedUtcScale {
78   validateDomain(domain);
79   const linear = resolveLinearScale(domain, range, reverse, width, height);
80   return Object.freeze({
81     ...linear,
82     type: "utc",
83     map: (value: number) => linear.map(timestamp(value)),
84     ticks: (count = 5) => utcTicks(linear.domain, count),
85     formatTick: (value: number) => new Date(timestamp(value)).toISOString(),
86   });
87 }
88 
89 /**
90  * Expands a numeric timestamp domain to enclosing UTC calendar boundaries.
91  * @param domain - Safe integer epoch-millisecond endpoints, possibly equal or descending.
92  * @param options - Optional bounded target tick count (default 5).
93  * @returns A frozen outward-rounded domain preserving its direction. See {@link LinearDomain}.
94  * @see {@link UTCScale}
95  */
96 export function niceUTCDomain(domain: LinearDomain, options: { readonly count?: number } = {}): LinearDomain {
97   validateDomain(domain);
98   const count = options.count ?? 5;
99   tickCount(count);
100   if (domain[0] === domain[1]) {
101     const lo = Math.max(-LIMIT, Math.min(LIMIT - 2, domain[0] - 1));
102     return Object.freeze([lo, lo + 2]);
103   }
104   const lo = Math.min(...domain), hi = Math.max(...domain);
105   const cadence = selectCadence(lo, hi, count);
106   const start = timestamp(cadence.at(cadence.first - 1), true);
107   const stop = timestamp(cadence.at(cadence.last + 1), true);
108   return Object.freeze(domain[0] > domain[1] ? [stop, start] : [start, stop]);
109 }
110 
111 /**
112  * Computes a finite numeric extent in source order, skipping only null and undefined.
113  * @param data - Source rows, which are never sorted or mutated.
114  * @param value - Accessor called once per row with its index and original array.
115  * @returns A frozen minimum/maximum pair, or undefined when every row is missing.
116  * @see {@link niceUTCDomain}
117  */
118 export function extent<D>(data: readonly D[], value: (datum: D, index: number, data: readonly D[]) => number | null | undefined): LinearDomain | undefined {
119   if (!Array.isArray(data) || typeof value !== "function") throw new TypeError("extent requires an array and accessor.");
120   let min = Infinity, max = -Infinity;
121   for (let i = 0; i < data.length; i++) {
122     const v = value(data[i], i, data);
123     if (v === null || v === undefined) continue;
124     if (typeof v !== "number" || !Number.isFinite(v)) throw new TypeError("extent values must be finite numbers or missing.");
125     min = Math.min(min, v); max = Math.max(max, v);
126   }
127   return min === Infinity ? undefined : Object.freeze([min, max]);
128 }
129
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.