dsh-token-usage-ledger 0.0.0-stage → 0.0.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1081 -0
- package/LICENSE +21 -0
- package/README.md +247 -2
- package/cordis.patch.yml +30 -0
- package/docs/token-usage-image01.png +0 -0
- package/docs/token-usage-image02.png +0 -0
- package/lib/client.js +4469 -0
- package/lib/host/aggregate.d.ts +132 -0
- package/lib/host/aggregate.js +840 -0
- package/lib/host/api.d.ts +118 -0
- package/lib/host/api.js +346 -0
- package/lib/host/backfill.d.ts +54 -0
- package/lib/host/backfill.js +265 -0
- package/lib/host/collector.d.ts +139 -0
- package/lib/host/collector.js +441 -0
- package/lib/host/ledger-io.d.ts +125 -0
- package/lib/host/ledger-io.js +211 -0
- package/lib/host/operation-error.d.ts +22 -0
- package/lib/host/operation-error.js +28 -0
- package/lib/host/paths.d.ts +35 -0
- package/lib/host/paths.js +63 -0
- package/lib/host/pricing-module.d.ts +112 -0
- package/lib/host/pricing-module.js +63 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.d.ts +31 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.js +67 -0
- package/lib/host/pricing-modules/index.d.ts +27 -0
- package/lib/host/pricing-modules/index.js +30 -0
- package/lib/host/pricing.d.ts +192 -0
- package/lib/host/pricing.js +287 -0
- package/lib/host/records.d.ts +47 -0
- package/lib/host/records.js +116 -0
- package/lib/host/runtime-marker.d.ts +67 -0
- package/lib/host/runtime-marker.js +71 -0
- package/lib/host/schema.d.ts +77 -0
- package/lib/host/schema.js +158 -0
- package/lib/host/store.d.ts +171 -0
- package/lib/host/store.js +337 -0
- package/lib/host/workspace-titles.d.ts +38 -0
- package/lib/host/workspace-titles.js +136 -0
- package/lib/host/zstd.d.ts +41 -0
- package/lib/host/zstd.js +134 -0
- package/lib/index.d.ts +82 -0
- package/lib/index.js +512 -0
- package/lib/shared/format.d.ts +415 -0
- package/lib/shared/format.js +714 -0
- package/lib/shared/protocol.d.ts +646 -0
- package/lib/shared/protocol.js +129 -0
- package/package.json +87 -4
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure display/aggregation helpers for the dashboard.
|
|
3
|
+
*
|
|
4
|
+
* No React, no DOM, no clock: everything here is a function of its arguments so
|
|
5
|
+
* the unit tests can pin the unit scaling and the day/week/month bucketing that
|
|
6
|
+
* the charts depend on.
|
|
7
|
+
*
|
|
8
|
+
* @module dsh-token-usage-ledger/client/format
|
|
9
|
+
*/
|
|
10
|
+
import { type Currency, type DailyPoint, type TokenBuckets } from './protocol.js';
|
|
11
|
+
/** Granularity the bar charts can be grouped at. */
|
|
12
|
+
export type Granularity = 'day' | 'week' | 'month';
|
|
13
|
+
/** One aggregated bar. */
|
|
14
|
+
export interface BucketPoint {
|
|
15
|
+
/** Stable key (first day of the bucket). */
|
|
16
|
+
key: string;
|
|
17
|
+
/** Short axis label. */
|
|
18
|
+
label: string;
|
|
19
|
+
/** Long label used in tooltips and the table. */
|
|
20
|
+
longLabel: string;
|
|
21
|
+
/** First day covered, inclusive. */
|
|
22
|
+
startDay: string;
|
|
23
|
+
/** Last day covered, inclusive. */
|
|
24
|
+
endDay: string;
|
|
25
|
+
/** Turns in the bucket. */
|
|
26
|
+
turns: number;
|
|
27
|
+
/** Prompt + output tokens in the bucket. */
|
|
28
|
+
tokens: number;
|
|
29
|
+
/** Per-bucket token composition (cache hit/miss/write/output/reasoning). */
|
|
30
|
+
tokenBuckets: TokenBuckets;
|
|
31
|
+
/** Priced cost in the bucket. */
|
|
32
|
+
cost: number;
|
|
33
|
+
/** True when any contributing day carried an estimated price. */
|
|
34
|
+
estimated: boolean;
|
|
35
|
+
/** Why, when every contributing day agrees; `undefined` otherwise. */
|
|
36
|
+
estimatedReason?: string;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Compact token count for axes and cards: `1234` → `1.23K`.
|
|
40
|
+
*
|
|
41
|
+
* Decimal rather than binary steps, because a context window and a price are
|
|
42
|
+
* quoted in decimal tokens; showing "1.21Ki" for 1234 tokens would be both
|
|
43
|
+
* unfamiliar and slightly wrong.
|
|
44
|
+
*
|
|
45
|
+
* @param value - token count.
|
|
46
|
+
* @returns a short display string.
|
|
47
|
+
*/
|
|
48
|
+
export declare function formatTokens(value: number): string;
|
|
49
|
+
/**
|
|
50
|
+
* Exact token count with thousands separators, for tooltips and tables.
|
|
51
|
+
* @param value - token count.
|
|
52
|
+
* @returns the grouped decimal string.
|
|
53
|
+
*/
|
|
54
|
+
export declare function formatTokensExact(value: number): string;
|
|
55
|
+
/**
|
|
56
|
+
* Human-readable duration for turn statistics.
|
|
57
|
+
*
|
|
58
|
+
* Deliberately coarse: these numbers describe agent turns (tool loops included),
|
|
59
|
+
* so sub-second precision would imply a latency measurement the ledger does not
|
|
60
|
+
* contain.
|
|
61
|
+
*
|
|
62
|
+
* @param milliseconds - duration in milliseconds.
|
|
63
|
+
* @returns a short display string (`—` for unusable input).
|
|
64
|
+
*/
|
|
65
|
+
export declare function formatDuration(milliseconds: number): string;
|
|
66
|
+
/** One adaptive cache-hit-rate axis. */
|
|
67
|
+
export interface CacheRateAxis {
|
|
68
|
+
/** Lower bound (0..1). */
|
|
69
|
+
min: number;
|
|
70
|
+
/** Upper bound (always 1 for rates). */
|
|
71
|
+
max: number;
|
|
72
|
+
/** Tick marks, descending for a top-to-bottom y-axis. */
|
|
73
|
+
ticks: number[];
|
|
74
|
+
/** Number of rare points below {@link min}; they are pinned to the bottom. */
|
|
75
|
+
clippedBelow: number;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Choose a cache-hit-rate y-axis that keeps tiny differences visible.
|
|
79
|
+
*
|
|
80
|
+
* Cache hit rates are usually 97–100%; a fixed 0–100% axis turns that into a
|
|
81
|
+
* straight line. A single anomalous bucket (a partial day, a prompt that missed
|
|
82
|
+
* the cache entirely) must not flatten the whole chart either, so when at most
|
|
83
|
+
* 10% of buckets fall below 95% they are pinned to the axis floor and counted in
|
|
84
|
+
* `clippedBelow` for an explicit note. A larger low-rate population expands the
|
|
85
|
+
* axis instead of hiding it.
|
|
86
|
+
*
|
|
87
|
+
* @param rates - observed rates in 0..1.
|
|
88
|
+
* @returns the axis bounds, three descending ticks, and the clip count.
|
|
89
|
+
*/
|
|
90
|
+
export declare function cacheRateAxis(rates: readonly number[]): CacheRateAxis;
|
|
91
|
+
/**
|
|
92
|
+
* Money with a currency symbol and enough precision for micro-amounts.
|
|
93
|
+
*
|
|
94
|
+
* Cached prompt tokens cost a fraction of a cent, so collapsing a non-zero
|
|
95
|
+
* amount to `¥0.00` would make the cost chart look empty when it is not.
|
|
96
|
+
*
|
|
97
|
+
* @param amount - amount in `currency`.
|
|
98
|
+
* @param currency - currency the amount is expressed in.
|
|
99
|
+
* @returns a short display string.
|
|
100
|
+
*/
|
|
101
|
+
export declare function formatMoney(amount: number, currency: Currency): string;
|
|
102
|
+
/**
|
|
103
|
+
* Parse a `YYYY-MM-DD` day key into its parts.
|
|
104
|
+
* @param key - day key.
|
|
105
|
+
* @returns year, month (1-based), and day.
|
|
106
|
+
*/
|
|
107
|
+
export declare function parseDay(key: string): {
|
|
108
|
+
year: number;
|
|
109
|
+
month: number;
|
|
110
|
+
day: number;
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* Monday-based weekday index of a day key (0 = Monday … 6 = Sunday).
|
|
114
|
+
*
|
|
115
|
+
* Chinese calendars start the week on Monday, and the heatmap must place
|
|
116
|
+
* 2026-08-10 (a Monday) at the top of its first column.
|
|
117
|
+
*
|
|
118
|
+
* @param key - day key.
|
|
119
|
+
* @returns the weekday index.
|
|
120
|
+
*/
|
|
121
|
+
export declare function mondayIndex(key: string): number;
|
|
122
|
+
/**
|
|
123
|
+
* Shift a day key by whole days.
|
|
124
|
+
* @param key - source day key.
|
|
125
|
+
* @param delta - days to add.
|
|
126
|
+
* @returns the shifted day key.
|
|
127
|
+
*/
|
|
128
|
+
export declare function shiftDay(key: string, delta: number): string;
|
|
129
|
+
/**
|
|
130
|
+
* Render a `Date` as a local day key.
|
|
131
|
+
* @param date - date to render.
|
|
132
|
+
* @returns `YYYY-MM-DD`.
|
|
133
|
+
*/
|
|
134
|
+
export declare function dayKeyOf(date: Date): string;
|
|
135
|
+
/** Time zone used when the browser cannot report one: Beijing, UTC+8. */
|
|
136
|
+
export declare const FALLBACK_BACKUP_TIME_ZONE = "Asia/Shanghai";
|
|
137
|
+
/**
|
|
138
|
+
* Resolve the browser's current IANA time zone.
|
|
139
|
+
*
|
|
140
|
+
* `Intl` is available in every browser this plugin supports; the try/catch and
|
|
141
|
+
* empty-string check exist so a broken/locked-down environment falls back
|
|
142
|
+
* deterministically instead of throwing during a download.
|
|
143
|
+
*
|
|
144
|
+
* @returns an IANA time zone name, or {@link FALLBACK_BACKUP_TIME_ZONE}.
|
|
145
|
+
*/
|
|
146
|
+
export declare function resolveBackupTimeZone(): string;
|
|
147
|
+
/**
|
|
148
|
+
* Format a backup filename timestamp as `yyyyMMddHHmmss` in the browser's
|
|
149
|
+
* current time zone, falling back to Beijing time when the zone is unknown.
|
|
150
|
+
*
|
|
151
|
+
* The backup payload keeps `exportedAt` as epoch milliseconds; this helper is
|
|
152
|
+
* only the human-readable filename component, so no zone suffix is appended.
|
|
153
|
+
*
|
|
154
|
+
* @param now - instant to render (defaults to the current time).
|
|
155
|
+
* @param timeZone - explicit IANA zone for tests; omitted means the browser zone.
|
|
156
|
+
* @returns the 14-digit timestamp.
|
|
157
|
+
*/
|
|
158
|
+
export declare function formatBackupTimestamp(now?: Date, timeZone?: string): string;
|
|
159
|
+
/**
|
|
160
|
+
* Monday of the week containing a day.
|
|
161
|
+
* @param key - day key.
|
|
162
|
+
* @returns the Monday's day key.
|
|
163
|
+
*/
|
|
164
|
+
export declare function mondayOf(key: string): string;
|
|
165
|
+
/**
|
|
166
|
+
* Short axis label for a day key (`08-13`).
|
|
167
|
+
* @param key - day key.
|
|
168
|
+
* @returns the label.
|
|
169
|
+
*/
|
|
170
|
+
export declare function shortDayLabel(key: string): string;
|
|
171
|
+
/**
|
|
172
|
+
* Group a daily series into chart buckets.
|
|
173
|
+
*
|
|
174
|
+
* `week` buckets are Monday-based and `month` buckets are calendar months, both
|
|
175
|
+
* clipped to the days actually present, so an empty leading or trailing period
|
|
176
|
+
* never inflates a bucket. Days with no traffic are already zero-filled by the
|
|
177
|
+
* Host, so a bucket's token total is a real sum over the period.
|
|
178
|
+
*
|
|
179
|
+
* @param points - daily series, oldest first.
|
|
180
|
+
* @param granularity - requested grouping.
|
|
181
|
+
* @returns bucket points, oldest first.
|
|
182
|
+
*/
|
|
183
|
+
export declare function bucketDaily(points: readonly DailyPoint[], granularity: Granularity): BucketPoint[];
|
|
184
|
+
/**
|
|
185
|
+
* Keep only the points inside an inclusive day-key range.
|
|
186
|
+
* @param points - daily series.
|
|
187
|
+
* @param from - inclusive start key, or `''` for no lower bound.
|
|
188
|
+
* @param to - inclusive end key, or `''` for no upper bound.
|
|
189
|
+
* @returns the filtered series.
|
|
190
|
+
*/
|
|
191
|
+
export declare function filterRange(points: readonly DailyPoint[], from: string, to: string): DailyPoint[];
|
|
192
|
+
/**
|
|
193
|
+
* A "nice" upper bound and tick list for a value axis.
|
|
194
|
+
*
|
|
195
|
+
* Ticks land on 1/2/2.5/5 × 10ⁿ so the axis reads as round numbers whatever the
|
|
196
|
+
* magnitude — necessary here because a day's token total can be anywhere from a
|
|
197
|
+
* few thousand to hundreds of millions.
|
|
198
|
+
*
|
|
199
|
+
* @param max - largest value the axis must contain.
|
|
200
|
+
* @param tickCount - desired number of intervals.
|
|
201
|
+
* @returns the bound and the tick values, ascending.
|
|
202
|
+
*/
|
|
203
|
+
export declare function niceAxis(max: number, tickCount?: number): {
|
|
204
|
+
bound: number;
|
|
205
|
+
ticks: number[];
|
|
206
|
+
};
|
|
207
|
+
/** Consecutive-day count ending at the newest day with traffic. */
|
|
208
|
+
export interface StreakInfo {
|
|
209
|
+
/** Length of the current streak in days. */
|
|
210
|
+
current: number;
|
|
211
|
+
/** Longest streak in the series. */
|
|
212
|
+
longest: number;
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* Compute current and longest consecutive-day streaks over a daily series.
|
|
216
|
+
* @param points - daily series, oldest first.
|
|
217
|
+
* @returns streak lengths.
|
|
218
|
+
*/
|
|
219
|
+
export declare function streaks(points: readonly DailyPoint[]): StreakInfo;
|
|
220
|
+
/** Number of days the calendar always shows, ending on its anchor day. */
|
|
221
|
+
export declare const HEATMAP_SPAN_DAYS = 365;
|
|
222
|
+
/**
|
|
223
|
+
* Days to REQUEST for one calendar page.
|
|
224
|
+
*
|
|
225
|
+
* A week more than the page draws: the page's start is snapped back to a Monday
|
|
226
|
+
* so every column is whole, which can reach up to six days earlier than the
|
|
227
|
+
* requested window. Without the headroom those six cells were never fetched and
|
|
228
|
+
* would have to be hidden, leaving a visibly clipped first column.
|
|
229
|
+
*/
|
|
230
|
+
export declare const HEATMAP_FETCH_DAYS: number;
|
|
231
|
+
/** The day range one calendar page covers, plus what paging is possible. */
|
|
232
|
+
export interface HeatmapRange {
|
|
233
|
+
/** First day drawn (a Monday, so every column is whole). */
|
|
234
|
+
start: string;
|
|
235
|
+
/** Last day drawn: the page's anchor day. */
|
|
236
|
+
end: string;
|
|
237
|
+
/** The exact `spanDays`-day window the page is meant to cover. */
|
|
238
|
+
requestedStart: string;
|
|
239
|
+
/**
|
|
240
|
+
* Earliest day the PAYLOAD holds, `''` for an empty payload.
|
|
241
|
+
*
|
|
242
|
+
* Cells before this were never fetched, so they must render as "not shown"
|
|
243
|
+
* rather than as "no usage" — the two look identical otherwise, and only one
|
|
244
|
+
* of them is true.
|
|
245
|
+
*/
|
|
246
|
+
coverageStart: string;
|
|
247
|
+
/**
|
|
248
|
+
* Newest day the PAYLOAD holds, `''` for an empty payload.
|
|
249
|
+
*
|
|
250
|
+
* The same argument applies on the right edge: after midnight the client's
|
|
251
|
+
* "today" can be one day newer than the last response, and a not-yet-fetched
|
|
252
|
+
* day must not be painted as a day with no usage.
|
|
253
|
+
*/
|
|
254
|
+
coverageEnd: string;
|
|
255
|
+
/**
|
|
256
|
+
* First day drawn that is a real observation: `start` unless the payload
|
|
257
|
+
* begins later. `''` when the page has nothing covered at all.
|
|
258
|
+
*/
|
|
259
|
+
drawnStart: string;
|
|
260
|
+
/** Last day drawn that is a real observation, `''` when nothing is covered. */
|
|
261
|
+
drawnEnd: string;
|
|
262
|
+
/** Days drawn between {@link drawnStart} and {@link drawnEnd}, 0 when none. */
|
|
263
|
+
drawnDays: number;
|
|
264
|
+
/** True when the payload covers the whole drawn page, both edges included. */
|
|
265
|
+
covered: boolean;
|
|
266
|
+
/**
|
|
267
|
+
* True when paging back would land on days the ledger actually has.
|
|
268
|
+
*
|
|
269
|
+
* Deliberately NOT "the payload holds an older day": the payload always ends
|
|
270
|
+
* at today and starts a fixed number of days earlier, so that weaker test is
|
|
271
|
+
* true even when the previous page would be almost entirely un-fetched — the
|
|
272
|
+
* button then draws a year of hidden cells, which is worse than a disabled
|
|
273
|
+
* button. The rule is "the previous page's last day is at or after the first
|
|
274
|
+
* day the LEDGER has" (`ledgerFirstDay` when known, else what the payload
|
|
275
|
+
* holds).
|
|
276
|
+
*/
|
|
277
|
+
canPageBack: boolean;
|
|
278
|
+
/** True when this page is not the newest one. */
|
|
279
|
+
canPageForward: boolean;
|
|
280
|
+
/** Number of days drawn, inclusive of both ends. */
|
|
281
|
+
days: number;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Resolve the day range one calendar page covers.
|
|
285
|
+
*
|
|
286
|
+
* The calendar is a FIXED-LENGTH rolling window — {@link HEATMAP_SPAN_DAYS}
|
|
287
|
+
* days ending on the anchor day, which defaults to today. A fixed span keeps the
|
|
288
|
+
* cell size constant no matter how long the ledger gets (the earlier
|
|
289
|
+
* grow-to-the-right design would have reached several metres wide within a few
|
|
290
|
+
* years), and paging is what lets older periods stay legible at that size.
|
|
291
|
+
*
|
|
292
|
+
* The start is snapped back to a Monday so every column is a whole week; the few
|
|
293
|
+
* days between the Monday and the requested start render as `outside` cells.
|
|
294
|
+
*
|
|
295
|
+
* Coverage is reported for BOTH edges and the caller must respect all of it: a
|
|
296
|
+
* day the payload never held must never look like a day with no usage, and the
|
|
297
|
+
* caption must not claim a range the grid had to hide.
|
|
298
|
+
*
|
|
299
|
+
* @param points - daily series the Host returned, oldest first, zero-filled.
|
|
300
|
+
* @param anchorDay - last day of the page (usually today).
|
|
301
|
+
* @param spanDays - page length in days.
|
|
302
|
+
* @param ledgerFirstDay - earliest day the LEDGER has (a facet), `''` if unknown;
|
|
303
|
+
* only used to decide whether paging back can reach real data.
|
|
304
|
+
* @returns the range to draw plus the coverage and paging bounds.
|
|
305
|
+
*/
|
|
306
|
+
export declare function heatmapWindow(points: readonly DailyPoint[], anchorDay?: string, spanDays?: number, ledgerFirstDay?: string): HeatmapRange;
|
|
307
|
+
/**
|
|
308
|
+
* Whole days from one day key to another (negative when `to` is earlier).
|
|
309
|
+
*
|
|
310
|
+
* Local-calendar arithmetic with rounding, so a DST shift of an hour cannot turn
|
|
311
|
+
* a 20-day span into 19 or 21.
|
|
312
|
+
*
|
|
313
|
+
* @param from - earlier day key.
|
|
314
|
+
* @param to - later day key.
|
|
315
|
+
* @returns the signed day count.
|
|
316
|
+
*/
|
|
317
|
+
export declare function daysBetween(from: string, to: string): number;
|
|
318
|
+
/**
|
|
319
|
+
* Format a per-million-token price for a table.
|
|
320
|
+
*
|
|
321
|
+
* Published prices span three orders of magnitude in one table (0.006 vs 27), so
|
|
322
|
+
* a fixed precision either invents digits for the big numbers or rounds the small
|
|
323
|
+
* ones to zero. Decimals are therefore chosen from the magnitude, and trailing
|
|
324
|
+
* zeros are trimmed so `2` does not print as `2.0000`.
|
|
325
|
+
*
|
|
326
|
+
* @param value - price in the table's currency per {@link PRICE_UNIT}.
|
|
327
|
+
* @returns the formatted number, without a currency symbol.
|
|
328
|
+
*/
|
|
329
|
+
export declare function formatUnitPrice(value: number): string;
|
|
330
|
+
/**
|
|
331
|
+
* Say WHY an amount is an estimate.
|
|
332
|
+
*
|
|
333
|
+
* Naming one specific cause was wrong as soon as a second cause existed: an
|
|
334
|
+
* attempt before the earliest published row is estimated too, and calling that
|
|
335
|
+
* "unknown model" misattributes it. The reason travels with the data
|
|
336
|
+
* (`estimatedReason`), so the sentence follows it — and when reasons disagree
|
|
337
|
+
* inside one bucket the fallback is a caveat that is true for all of them.
|
|
338
|
+
*
|
|
339
|
+
* @param reason - aggregated `estimatedReason`, or undefined when absent/mixed.
|
|
340
|
+
* @returns the sentence to show.
|
|
341
|
+
*/
|
|
342
|
+
export declare function describeEstimate(reason: string | undefined): string;
|
|
343
|
+
/** Tokens one published price unit buys (prices are quoted per million). */
|
|
344
|
+
export declare const PRICE_UNIT = 1000000;
|
|
345
|
+
/**
|
|
346
|
+
* Report whether a string looks like a `YYYY-MM-DD` day key.
|
|
347
|
+
*
|
|
348
|
+
* Facets come from the Host, but the client uses them to build ranges and to
|
|
349
|
+
* format the calendar, so a value that only looks like a day would silently
|
|
350
|
+
* produce `NaN-NaN-NaN` dates and empty charts. Cheap to check, so it is checked.
|
|
351
|
+
*
|
|
352
|
+
* @param value - candidate string.
|
|
353
|
+
* @returns true when it parses as a real calendar day.
|
|
354
|
+
*/
|
|
355
|
+
export declare function isDayKey(value: string): boolean;
|
|
356
|
+
/** Date-range presets offered by the dashboard. */
|
|
357
|
+
export type RangePreset = '7d' | '30d' | '90d' | 'month' | 'all' | 'custom';
|
|
358
|
+
/**
|
|
359
|
+
* Resolve a preset (or a custom pair) into a CLOSED day-key range.
|
|
360
|
+
*
|
|
361
|
+
* Both bounds are INCLUSIVE (`from <= day <= to`): picking 09-01 as the start and
|
|
362
|
+
* 09-01 as the end is a one-day range, and 09-01..09-07 is seven days — the same
|
|
363
|
+
* convention as the presets (近 7 天 = today-6..today). Every consumer
|
|
364
|
+
* ({@link filterRange}, {@link bucketDaily}) filters with `>=` / `<=`, so this is
|
|
365
|
+
* the one place the convention has to be stated.
|
|
366
|
+
*
|
|
367
|
+
* An INVERTED pair is normalised by swapping: the two dates a user picked are a
|
|
368
|
+
* closed interval regardless of the order they were typed in, and an inverted
|
|
369
|
+
* range would otherwise filter everything out and show an empty panel with no
|
|
370
|
+
* error. (`customFrom` empty means "from the beginning", `customTo` empty means
|
|
371
|
+
* "up to the newest day".)
|
|
372
|
+
*
|
|
373
|
+
* Lives here rather than in the panel component so it can be unit tested: these
|
|
374
|
+
* two functions ARE the requirements' "按天/周/月/日期范围筛选" semantics, and in
|
|
375
|
+
* the delivered bundle a `.tsx` module is unreachable from `node --test`.
|
|
376
|
+
*
|
|
377
|
+
* @param preset - active preset.
|
|
378
|
+
* @param end - newest day to include.
|
|
379
|
+
* @param customFrom - custom start, `''` for unbounded.
|
|
380
|
+
* @param customTo - custom end, `''` for unbounded.
|
|
381
|
+
* @returns the inclusive range; either bound may be `''` meaning unbounded.
|
|
382
|
+
*/
|
|
383
|
+
export declare function resolveRange(preset: RangePreset, end: string, customFrom: string, customTo: string): {
|
|
384
|
+
from: string;
|
|
385
|
+
to: string;
|
|
386
|
+
};
|
|
387
|
+
/**
|
|
388
|
+
* Days of history the dashboard must request to draw a complete calendar.
|
|
389
|
+
*
|
|
390
|
+
* The floor is a whole year, not the API's default window: the calendar always
|
|
391
|
+
* shows {@link HEATMAP_SPAN_DAYS} days, so a shorter window would leave most of
|
|
392
|
+
* it un-fetched — cells that must then be hidden, which reads as a broken
|
|
393
|
+
* calendar even though it is telling the truth. Fetching the year makes every
|
|
394
|
+
* drawn day a real observation, and the ceiling stays the API's bound so a
|
|
395
|
+
* corrupt `firstDay` cannot ask for an unbounded payload.
|
|
396
|
+
*
|
|
397
|
+
* @param firstDay - earliest day in the ledger, `''` when empty.
|
|
398
|
+
* @param today - current local day key.
|
|
399
|
+
* @returns the requested window width in days.
|
|
400
|
+
*/
|
|
401
|
+
export declare function neededSpanDays(firstDay: string, today?: string): number;
|
|
402
|
+
/**
|
|
403
|
+
* Days to REQUEST so that a page ending on `anchorDay` is fully covered.
|
|
404
|
+
*
|
|
405
|
+
* Paging back one page asks for a window twice as tall; without this the page
|
|
406
|
+
* would be drawn over days the payload never held, and hiding them reads as a
|
|
407
|
+
* broken calendar (measured on the project's own isolated ledger: the previous
|
|
408
|
+
* year page had 33 drawn days and 338 hidden ones). Clamped to the API's ceiling,
|
|
409
|
+
* where the coverage banner takes over from silence.
|
|
410
|
+
*
|
|
411
|
+
* @param anchorDay - last day of the page being drawn.
|
|
412
|
+
* @param today - current local day key.
|
|
413
|
+
* @returns the requested window width in days.
|
|
414
|
+
*/
|
|
415
|
+
export declare function pageSpanDays(anchorDay: string, today?: string): number;
|