@xiangyixie/dsh-superagent 0.12.1 → 0.14.0
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 +171 -8
- package/LICENSE +21 -21
- package/README.md +522 -40
- package/bin/doctor.js +1 -1
- package/cordis.patch.yml +9 -9
- package/lib/audit.js +8 -1
- package/lib/browser.js +795 -0
- package/lib/console.js +763 -0
- package/lib/cost.js +71 -11
- package/lib/cron.js +387 -0
- package/lib/desktop.js +507 -0
- package/lib/doctor.js +1 -0
- package/lib/goal.js +649 -0
- package/lib/guard.js +15 -0
- package/lib/index.js +1296 -42
- package/lib/ledger.js +26 -12
- package/lib/orchestrator.js +1765 -136
- package/lib/report.js +59 -29
- package/lib/runtime-control.js +1151 -0
- package/lib/schedule.js +1030 -0
- package/lib/store.js +6 -2
- package/lib/user-memory.js +587 -0
- package/lib/watch.js +25 -17
- package/lib/workbench.js +7 -7
- package/lib/workspace.js +88 -27
- package/package.json +101 -92
- package/public/console.html +1618 -0
package/lib/cost.js
CHANGED
|
@@ -14,6 +14,11 @@
|
|
|
14
14
|
* silently priced at zero, because "we do not know" and "it was free" are
|
|
15
15
|
* different answers.
|
|
16
16
|
*
|
|
17
|
+
* Currencies never add. A run that used a USD route and a CNY route has one
|
|
18
|
+
* subtotal per currency; a cross-currency "total" would be a number whose unit
|
|
19
|
+
* is undefined. Single-currency runs keep the flat `currency` / `totalMicros` /
|
|
20
|
+
* `total` fields callers already read.
|
|
21
|
+
*
|
|
17
22
|
* @module dsh-superagent/cost
|
|
18
23
|
*/
|
|
19
24
|
|
|
@@ -36,6 +41,52 @@ export function currencySymbol(code) {
|
|
|
36
41
|
return `${code ?? ''} `
|
|
37
42
|
}
|
|
38
43
|
|
|
44
|
+
/**
|
|
45
|
+
* Add one amount to a currency-keyed tally of integer micro-units.
|
|
46
|
+
* @param {Record<string, number>} tally - currency code -> micro-units.
|
|
47
|
+
* @param {string | null | undefined} currency - ISO currency code.
|
|
48
|
+
* @param {number} micros - integer micro-units in that currency.
|
|
49
|
+
* @returns {Record<string, number>} the same tally.
|
|
50
|
+
*/
|
|
51
|
+
export function addCurrencyMicros(tally, currency, micros) {
|
|
52
|
+
if (!Number.isFinite(micros)) return tally
|
|
53
|
+
const code = currency || 'USD'
|
|
54
|
+
tally[code] = (tally[code] ?? 0) + micros
|
|
55
|
+
return tally
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Reduce a currency tally to the flat fields callers already use.
|
|
60
|
+
*
|
|
61
|
+
* One currency keeps `currency` / `totalMicros` / `total` exactly as before.
|
|
62
|
+
* More than one yields null for the scalar fields: there is no meaningful sum
|
|
63
|
+
* of ¥ and $, so callers must render `byCurrency` instead of adding.
|
|
64
|
+
*
|
|
65
|
+
* @param {Record<string, number>} tally - currency code -> micro-units.
|
|
66
|
+
* @returns {{ currency: string | null, totalMicros: number | null, total: number | null, mixedCurrency: boolean }}
|
|
67
|
+
*/
|
|
68
|
+
export function currencyTotals(tally) {
|
|
69
|
+
const codes = Object.keys(tally ?? {})
|
|
70
|
+
if (codes.length === 0) return { currency: 'USD', totalMicros: 0, total: 0, mixedCurrency: false }
|
|
71
|
+
if (codes.length === 1) {
|
|
72
|
+
const totalMicros = tally[codes[0]]
|
|
73
|
+
return { currency: codes[0], totalMicros, total: totalMicros / MICRO, mixedCurrency: false }
|
|
74
|
+
}
|
|
75
|
+
return { currency: null, totalMicros: null, total: null, mixedCurrency: true }
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Render a currency tally. One currency reads exactly like `formatMoney`;
|
|
80
|
+
* several are joined with `+`, each under its own symbol.
|
|
81
|
+
* @param {Record<string, number>} tally - currency code -> integer micro-units.
|
|
82
|
+
* @returns {string} e.g. `¥0.0952 + $0.0248`.
|
|
83
|
+
*/
|
|
84
|
+
export function formatCurrencyTally(tally) {
|
|
85
|
+
const codes = Object.keys(tally ?? {}).sort()
|
|
86
|
+
if (codes.length === 0) return '—'
|
|
87
|
+
return codes.map(code => moneyOfMicros(tally[code], code)).join(' + ')
|
|
88
|
+
}
|
|
89
|
+
|
|
39
90
|
/**
|
|
40
91
|
* Convert one configured price to integer micro-units per million tokens.
|
|
41
92
|
* @param {unknown} rate - price quoted per 1M tokens.
|
|
@@ -129,9 +180,11 @@ function amountMicros(tokens, priceMicros) {
|
|
|
129
180
|
* @param {object | null} usage - summed usage for one run (or subtask).
|
|
130
181
|
* @param {Record<string, object> | undefined} pricing - configured price table.
|
|
131
182
|
* @returns {{
|
|
132
|
-
* currency: string,
|
|
133
|
-
* totalMicros: number,
|
|
134
|
-
* total: number,
|
|
183
|
+
* currency: string | null,
|
|
184
|
+
* totalMicros: number | null,
|
|
185
|
+
* total: number | null,
|
|
186
|
+
* mixedCurrency: boolean,
|
|
187
|
+
* byCurrency: Record<string, number>,
|
|
135
188
|
* byModel: Record<string, number>,
|
|
136
189
|
* byModelMicros: Record<string, number>,
|
|
137
190
|
* records: object[],
|
|
@@ -144,10 +197,9 @@ export function computeCost(usage, pricing) {
|
|
|
144
197
|
const table = pricing && typeof pricing === 'object' ? pricing : {}
|
|
145
198
|
const byModel = {}
|
|
146
199
|
const byModelMicros = {}
|
|
200
|
+
const byCurrency = {}
|
|
147
201
|
const records = []
|
|
148
202
|
const unpriced = []
|
|
149
|
-
let totalMicros = 0
|
|
150
|
-
let currency = null
|
|
151
203
|
|
|
152
204
|
for (const [model, entry] of Object.entries(usage.models ?? {})) {
|
|
153
205
|
const record = {
|
|
@@ -177,15 +229,17 @@ export function computeCost(usage, pricing) {
|
|
|
177
229
|
record.amountMicros = amount
|
|
178
230
|
byModelMicros[model] = amount
|
|
179
231
|
byModel[model] = amount / MICRO
|
|
180
|
-
|
|
232
|
+
addCurrencyMicros(byCurrency, price.currency, amount)
|
|
181
233
|
records.push(record)
|
|
182
|
-
currency = currency ?? price.currency
|
|
183
234
|
}
|
|
184
235
|
|
|
236
|
+
const totals = currencyTotals(byCurrency)
|
|
185
237
|
return {
|
|
186
|
-
currency: currency
|
|
187
|
-
totalMicros,
|
|
188
|
-
total:
|
|
238
|
+
currency: totals.currency,
|
|
239
|
+
totalMicros: totals.totalMicros,
|
|
240
|
+
total: totals.total,
|
|
241
|
+
mixedCurrency: totals.mixedCurrency,
|
|
242
|
+
byCurrency,
|
|
189
243
|
byModel,
|
|
190
244
|
byModelMicros,
|
|
191
245
|
records,
|
|
@@ -257,11 +311,17 @@ export function moneyOfMicros(micros, currency = 'USD') {
|
|
|
257
311
|
|
|
258
312
|
/**
|
|
259
313
|
* Format a cost record (or a bare amount) for display.
|
|
260
|
-
*
|
|
314
|
+
*
|
|
315
|
+
* A cost that holds more than one currency is shown as one amount per
|
|
316
|
+
* currency; it is never collapsed into a single cross-currency number.
|
|
317
|
+
*
|
|
318
|
+
* @param {{ totalMicros?: number, total?: number, currency?: string, byCurrency?: Record<string, number> } | number | null} cost - cost.
|
|
261
319
|
* @param {string} [currency] - fallback currency code.
|
|
262
320
|
* @returns {string} formatted money, or `—` when unknown.
|
|
263
321
|
*/
|
|
264
322
|
export function formatMoney(cost, currency) {
|
|
323
|
+
const tally = cost && typeof cost === 'object' ? cost.byCurrency : null
|
|
324
|
+
if (tally && typeof tally === 'object' && Object.keys(tally).length > 1) return formatCurrencyTally(tally)
|
|
265
325
|
const code = (cost && typeof cost === 'object' && cost.currency) || currency || 'USD'
|
|
266
326
|
return moneyOfMicros(microsOf(cost), code)
|
|
267
327
|
}
|
package/lib/cron.js
ADDED
|
@@ -0,0 +1,387 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Zero-dependency cron parsing for scheduled runs.
|
|
3
|
+
*
|
|
4
|
+
* The scheduler needs two things from this module: a parse that fails when the
|
|
5
|
+
* plan is created (naming the field, not just "invalid cron"), and the next
|
|
6
|
+
* instant a local clock would reach, in a time zone that may be the caller's and
|
|
7
|
+
* not the host's. Both are computed with the runtime's own `Intl` data, so a
|
|
8
|
+
* plan does not depend on a package being installed next to the plugin.
|
|
9
|
+
*
|
|
10
|
+
* Supported: the standard five fields (minute hour day-of-month month
|
|
11
|
+
* day-of-week), star, star-with-step, ranges `a-b`, ranges with a step, lists
|
|
12
|
+
* `a,b,c`, three-letter month and weekday names, and `0`/`7` for Sunday. When
|
|
13
|
+
* both day-of-month and day-of-week are restricted, a day matching either one
|
|
14
|
+
* is selected, which is what Vixie cron does.
|
|
15
|
+
*
|
|
16
|
+
* Not supported, and refused at create time instead of at 03:00: a seconds
|
|
17
|
+
* field (six fields), `@daily`-style macros, and the Quartz extensions `L`,
|
|
18
|
+
* `W`, `#`, and `?`. A year field (seven fields) is also refused.
|
|
19
|
+
*
|
|
20
|
+
* @module dsh-superagent/cron
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** Fields in order, with the bounds a value must fall inside. */
|
|
24
|
+
const FIELDS = [
|
|
25
|
+
{ name: 'minute', min: 0, max: 59, aliases: null },
|
|
26
|
+
{ name: 'hour', min: 0, max: 23, aliases: null },
|
|
27
|
+
{ name: 'day-of-month', min: 1, max: 31, aliases: null },
|
|
28
|
+
{ name: 'month', min: 1, max: 12, aliases: { JAN: 1, FEB: 2, MAR: 3, APR: 4, MAY: 5, JUN: 6, JUL: 7, AUG: 8, SEP: 9, OCT: 10, NOV: 11, DEC: 12 } },
|
|
29
|
+
{ name: 'day-of-week', min: 0, max: 7, aliases: { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 } },
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
/** A create-time cron problem, carrying which field (1-based) was wrong. */
|
|
33
|
+
export class CronError extends Error {
|
|
34
|
+
/**
|
|
35
|
+
* @param {string} message - what is wrong, in one actionable sentence.
|
|
36
|
+
* @param {{ field?: number | null, fieldName?: string | null }} [where] - field position and name.
|
|
37
|
+
*/
|
|
38
|
+
constructor(message, { field = null, fieldName = null } = {}) {
|
|
39
|
+
super(message)
|
|
40
|
+
this.name = 'CronError'
|
|
41
|
+
this.field = field
|
|
42
|
+
this.fieldName = fieldName
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const MAX_SEARCH_DAYS = 366 * 8
|
|
47
|
+
const formatters = new Map()
|
|
48
|
+
|
|
49
|
+
/** Resolve one token (number or three-letter name) to its numeric value. */
|
|
50
|
+
function valueOf(token, spec, index) {
|
|
51
|
+
const text = String(token).toUpperCase()
|
|
52
|
+
const field = index
|
|
53
|
+
if (spec.aliases && Object.hasOwn(spec.aliases, text)) return spec.aliases[text]
|
|
54
|
+
if (!/^\d+$/.test(text)) {
|
|
55
|
+
throw new CronError(
|
|
56
|
+
`cron field ${field} (${spec.name}) has "${token}", which is not a number`
|
|
57
|
+
+ `${spec.aliases ? ' or a three-letter name' : ''}`,
|
|
58
|
+
{ field, fieldName: spec.name },
|
|
59
|
+
)
|
|
60
|
+
}
|
|
61
|
+
const value = Number(text)
|
|
62
|
+
if (value < spec.min || value > spec.max) {
|
|
63
|
+
throw new CronError(
|
|
64
|
+
`cron field ${field} (${spec.name}) "${token}" is out of range ${spec.min}-${spec.max}`,
|
|
65
|
+
{ field, fieldName: spec.name },
|
|
66
|
+
)
|
|
67
|
+
}
|
|
68
|
+
return value
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Parse `*`, `a`, `a-b`, or any of those with `/n`, into sorted values. */
|
|
72
|
+
function parseItem(item, spec, index) {
|
|
73
|
+
const text = item.trim()
|
|
74
|
+
if (!text) {
|
|
75
|
+
throw new CronError(`cron field ${index} (${spec.name}) has an empty list item`, { field: index, fieldName: spec.name })
|
|
76
|
+
}
|
|
77
|
+
// `?` is Quartz for "no specific value", and `L`/`W`/`#` are Quartz
|
|
78
|
+
// extensions. Refusing them by name is the difference between "your cron is
|
|
79
|
+
// wrong" and "your cron is a different dialect".
|
|
80
|
+
if (text.includes('?')) {
|
|
81
|
+
throw new CronError(`cron field ${index} (${spec.name}) uses "?", which is not supported; use "*" instead`, {
|
|
82
|
+
field: index,
|
|
83
|
+
fieldName: spec.name,
|
|
84
|
+
})
|
|
85
|
+
}
|
|
86
|
+
if (/^[LW]$/i.test(text) || (/[LW#]/i.test(text) && !/^[A-Za-z]+$/.test(text))) {
|
|
87
|
+
throw new CronError(
|
|
88
|
+
`cron field ${index} (${spec.name}) uses "${text}"; L, W and # are not supported. `
|
|
89
|
+
+ 'This parser supports only *, lists, ranges and /n steps',
|
|
90
|
+
{ field: index, fieldName: spec.name },
|
|
91
|
+
)
|
|
92
|
+
}
|
|
93
|
+
const [base, stepText, extra] = text.split('/')
|
|
94
|
+
if (extra !== undefined) {
|
|
95
|
+
throw new CronError(`cron field ${index} (${spec.name}) has more than one "/" step`, { field: index, fieldName: spec.name })
|
|
96
|
+
}
|
|
97
|
+
let step = 1
|
|
98
|
+
if (stepText !== undefined) {
|
|
99
|
+
if (!/^\d+$/.test(stepText) || Number(stepText) < 1) {
|
|
100
|
+
throw new CronError(`cron field ${index} (${spec.name}) has step "${stepText}"; a step must be a number of at least 1`, {
|
|
101
|
+
field: index,
|
|
102
|
+
fieldName: spec.name,
|
|
103
|
+
})
|
|
104
|
+
}
|
|
105
|
+
step = Number(stepText)
|
|
106
|
+
}
|
|
107
|
+
if (base === '*') {
|
|
108
|
+
return { values: expand(spec.min, spec.max, step), restricted: step !== 1 }
|
|
109
|
+
}
|
|
110
|
+
if (base === '' || base.includes('*')) {
|
|
111
|
+
throw new CronError(`cron field ${index} (${spec.name}) has "${text}"; "*" may only be the whole field or "*/n"`, {
|
|
112
|
+
field: index,
|
|
113
|
+
fieldName: spec.name,
|
|
114
|
+
})
|
|
115
|
+
}
|
|
116
|
+
const range = base.split('-')
|
|
117
|
+
if (range.length === 1) {
|
|
118
|
+
const value = valueOf(range[0], spec, index)
|
|
119
|
+
if (stepText !== undefined) {
|
|
120
|
+
// "5/10" is not a range in cron; reject it instead of inventing one.
|
|
121
|
+
throw new CronError(`cron field ${index} (${spec.name}) uses "${text}"; a step needs a range such as "5-20/2"`, {
|
|
122
|
+
field: index,
|
|
123
|
+
fieldName: spec.name,
|
|
124
|
+
})
|
|
125
|
+
}
|
|
126
|
+
return { values: [value], restricted: true }
|
|
127
|
+
}
|
|
128
|
+
if (range.length === 2) {
|
|
129
|
+
const from = valueOf(range[0], spec, index)
|
|
130
|
+
const to = valueOf(range[1], spec, index)
|
|
131
|
+
if (from > to) {
|
|
132
|
+
throw new CronError(`cron field ${index} (${spec.name}) range "${base}" runs backwards`, {
|
|
133
|
+
field: index,
|
|
134
|
+
fieldName: spec.name,
|
|
135
|
+
})
|
|
136
|
+
}
|
|
137
|
+
return { values: expand(from, to, step), restricted: true }
|
|
138
|
+
}
|
|
139
|
+
throw new CronError(`cron field ${index} (${spec.name}) has more than one "-"`, { field: index, fieldName: spec.name })
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function expand(from, to, step) {
|
|
143
|
+
const values = []
|
|
144
|
+
for (let value = from; value <= to; value += step) values.push(value)
|
|
145
|
+
return values
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Parse one five-field cron expression.
|
|
150
|
+
*
|
|
151
|
+
* @param {string} expression - e.g. `"0 9 * * MON-FRI"`.
|
|
152
|
+
* @returns {Readonly<object>} parsed spec, accepted by `nextCronTime`.
|
|
153
|
+
* @throws {CronError} naming the 1-based field that is wrong.
|
|
154
|
+
*/
|
|
155
|
+
export function parseCron(expression) {
|
|
156
|
+
const text = String(expression ?? '').trim()
|
|
157
|
+
if (!text) {
|
|
158
|
+
throw new CronError('cron is empty; expected 5 fields: minute hour day-of-month month day-of-week', {
|
|
159
|
+
field: 1,
|
|
160
|
+
fieldName: 'minute',
|
|
161
|
+
})
|
|
162
|
+
}
|
|
163
|
+
if (text.startsWith('@')) {
|
|
164
|
+
throw new CronError(
|
|
165
|
+
`cron macro "${text}" is not supported; write the five fields instead (e.g. "0 9 * * *" for 09:00 daily)`,
|
|
166
|
+
{ field: 1, fieldName: 'minute' },
|
|
167
|
+
)
|
|
168
|
+
}
|
|
169
|
+
const parts = text.split(/\s+/)
|
|
170
|
+
if (parts.length !== 5) {
|
|
171
|
+
const detail = parts.length === 6
|
|
172
|
+
? 'got 6; a seconds field is not supported — the first field is minutes'
|
|
173
|
+
: parts.length === 7
|
|
174
|
+
? 'got 7; a year field is not supported'
|
|
175
|
+
: `got ${parts.length}`
|
|
176
|
+
throw new CronError(`cron needs 5 fields (minute hour day-of-month month day-of-week) but ${detail}`, {
|
|
177
|
+
field: 1,
|
|
178
|
+
fieldName: 'minute',
|
|
179
|
+
})
|
|
180
|
+
}
|
|
181
|
+
const parsed = parts.map((part, index) => {
|
|
182
|
+
const field = index + 1
|
|
183
|
+
const spec = FIELDS[index]
|
|
184
|
+
if (part.includes('?')) {
|
|
185
|
+
throw new CronError(`cron field ${field} (${spec.name}) uses "?", which is not supported; use "*" instead`, {
|
|
186
|
+
field,
|
|
187
|
+
fieldName: spec.name,
|
|
188
|
+
})
|
|
189
|
+
}
|
|
190
|
+
const values = new Set()
|
|
191
|
+
let restricted = false
|
|
192
|
+
for (const item of part.split(',')) {
|
|
193
|
+
const result = parseItem(item, spec, field)
|
|
194
|
+
for (const value of result.values) values.add(value)
|
|
195
|
+
if (result.restricted) restricted = true
|
|
196
|
+
}
|
|
197
|
+
if (values.size === 0) {
|
|
198
|
+
throw new CronError(`cron field ${field} (${spec.name}) matches no value`, { field, fieldName: spec.name })
|
|
199
|
+
}
|
|
200
|
+
const list = [...values].sort((a, b) => a - b)
|
|
201
|
+
// 0 and 7 both mean Sunday; keeping both would make a range look larger than
|
|
202
|
+
// it is and would report two matches for one day.
|
|
203
|
+
if (spec.name === 'day-of-week') {
|
|
204
|
+
if (values.has(7)) {
|
|
205
|
+
values.delete(7)
|
|
206
|
+
values.add(0)
|
|
207
|
+
}
|
|
208
|
+
return { values: [...values].sort((a, b) => a - b), restricted: part !== '*' }
|
|
209
|
+
}
|
|
210
|
+
return { values: list, restricted: part !== '*' }
|
|
211
|
+
})
|
|
212
|
+
return Object.freeze({
|
|
213
|
+
expression: text,
|
|
214
|
+
minutes: Object.freeze(parsed[0].values),
|
|
215
|
+
hours: Object.freeze(parsed[1].values),
|
|
216
|
+
daysOfMonth: Object.freeze(parsed[2].values),
|
|
217
|
+
months: Object.freeze(parsed[3].values),
|
|
218
|
+
daysOfWeek: Object.freeze(parsed[4].values),
|
|
219
|
+
domRestricted: parsed[2].restricted,
|
|
220
|
+
dowRestricted: parsed[4].restricted,
|
|
221
|
+
})
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Refuse an unknown time zone at create time.
|
|
226
|
+
*
|
|
227
|
+
* @param {string} timeZone - IANA name such as `Asia/Shanghai`.
|
|
228
|
+
* @throws {CronError} when the runtime cannot resolve it.
|
|
229
|
+
*/
|
|
230
|
+
export function validateTimeZone(timeZone) {
|
|
231
|
+
const name = String(timeZone ?? '').trim()
|
|
232
|
+
if (!name) throw new CronError('timeZone is empty; use an IANA name such as "Asia/Shanghai" or "UTC"')
|
|
233
|
+
try {
|
|
234
|
+
formatterFor(name)
|
|
235
|
+
} catch {
|
|
236
|
+
throw new CronError(
|
|
237
|
+
`timeZone "${name}" is not known to this Node runtime; use an IANA name such as "Asia/Shanghai"`,
|
|
238
|
+
)
|
|
239
|
+
}
|
|
240
|
+
return name
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function formatterFor(timeZone) {
|
|
244
|
+
let formatter = formatters.get(timeZone)
|
|
245
|
+
if (!formatter) {
|
|
246
|
+
formatter = new Intl.DateTimeFormat('en-US', {
|
|
247
|
+
timeZone,
|
|
248
|
+
year: 'numeric',
|
|
249
|
+
month: '2-digit',
|
|
250
|
+
day: '2-digit',
|
|
251
|
+
hour: '2-digit',
|
|
252
|
+
minute: '2-digit',
|
|
253
|
+
second: '2-digit',
|
|
254
|
+
hourCycle: 'h23',
|
|
255
|
+
})
|
|
256
|
+
formatters.set(timeZone, formatter)
|
|
257
|
+
}
|
|
258
|
+
return formatter
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* Local calendar parts of one instant in a time zone.
|
|
263
|
+
*
|
|
264
|
+
* @param {number} ms - epoch milliseconds.
|
|
265
|
+
* @param {string} timeZone - IANA zone.
|
|
266
|
+
* @returns {{ year: number, month: number, day: number, hour: number, minute: number, second: number, weekday: number }}
|
|
267
|
+
*/
|
|
268
|
+
export function zonedParts(ms, timeZone) {
|
|
269
|
+
const parts = {}
|
|
270
|
+
for (const part of formatterFor(timeZone).formatToParts(new Date(ms))) {
|
|
271
|
+
if (part.type !== 'literal') parts[part.type] = part.value
|
|
272
|
+
}
|
|
273
|
+
const year = Number(parts.year)
|
|
274
|
+
const month = Number(parts.month)
|
|
275
|
+
const day = Number(parts.day)
|
|
276
|
+
const hour = Number(parts.hour)
|
|
277
|
+
const minute = Number(parts.minute)
|
|
278
|
+
const second = Number(parts.second)
|
|
279
|
+
return {
|
|
280
|
+
year,
|
|
281
|
+
month,
|
|
282
|
+
day,
|
|
283
|
+
hour,
|
|
284
|
+
minute,
|
|
285
|
+
second,
|
|
286
|
+
weekday: new Date(Date.UTC(year, month - 1, day)).getUTCDay(),
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Epoch of one local wall-clock time, or null when that time does not exist.
|
|
292
|
+
*
|
|
293
|
+
* A time can be missing on the spring-forward day. Cron semantics run the job
|
|
294
|
+
* at the next existing minute, so null is the honest answer and the caller
|
|
295
|
+
* moves on instead of inventing a shifted time. Ambiguous times on the fall-back
|
|
296
|
+
* day resolve to the earlier offset, which is what a "next run" should pick.
|
|
297
|
+
*
|
|
298
|
+
* @param {{ year: number, month: number, day: number, hour: number, minute: number }} wanted - local parts.
|
|
299
|
+
* @param {string} timeZone - IANA zone.
|
|
300
|
+
* @returns {number | null} epoch milliseconds, or null for a non-existent local time.
|
|
301
|
+
*/
|
|
302
|
+
export function localToEpoch(wanted, timeZone) {
|
|
303
|
+
const desired = Date.UTC(wanted.year, wanted.month - 1, wanted.day, wanted.hour, wanted.minute)
|
|
304
|
+
let guess = desired
|
|
305
|
+
for (let attempt = 0; attempt < 3; attempt++) {
|
|
306
|
+
const actual = zonedParts(guess, timeZone)
|
|
307
|
+
const actualMs = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute)
|
|
308
|
+
const delta = desired - actualMs
|
|
309
|
+
if (delta === 0) break
|
|
310
|
+
guess += delta
|
|
311
|
+
}
|
|
312
|
+
const final = zonedParts(guess, timeZone)
|
|
313
|
+
if (final.year !== wanted.year || final.month !== wanted.month || final.day !== wanted.day
|
|
314
|
+
|| final.hour !== wanted.hour || final.minute !== wanted.minute) {
|
|
315
|
+
return null
|
|
316
|
+
}
|
|
317
|
+
return guess
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
function matchesDay(spec, parts) {
|
|
321
|
+
if (!spec.months.includes(parts.month)) return false
|
|
322
|
+
const dom = spec.daysOfMonth.includes(parts.day)
|
|
323
|
+
const dow = spec.daysOfWeek.includes(parts.weekday)
|
|
324
|
+
if (spec.domRestricted && spec.dowRestricted) return dom || dow
|
|
325
|
+
if (spec.domRestricted) return dom
|
|
326
|
+
if (spec.dowRestricted) return dow
|
|
327
|
+
return true
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
function nextLocalDay(parts, timeZone) {
|
|
331
|
+
const midnight = Date.UTC(parts.year, parts.month - 1, parts.day)
|
|
332
|
+
const next = new Date(midnight)
|
|
333
|
+
next.setUTCDate(next.getUTCDate() + 1)
|
|
334
|
+
const wanted = {
|
|
335
|
+
year: next.getUTCFullYear(),
|
|
336
|
+
month: next.getUTCMonth() + 1,
|
|
337
|
+
day: next.getUTCDate(),
|
|
338
|
+
hour: 0,
|
|
339
|
+
minute: 0,
|
|
340
|
+
}
|
|
341
|
+
// Some zones skip midnight itself. Falling back to +24h keeps the search
|
|
342
|
+
// moving; the next iteration reads the real local parts from the clock.
|
|
343
|
+
return localToEpoch(wanted, timeZone) ?? localToEpoch({ ...wanted, hour: 1 }, timeZone) ?? Date.UTC(
|
|
344
|
+
wanted.year,
|
|
345
|
+
wanted.month - 1,
|
|
346
|
+
wanted.day,
|
|
347
|
+
0,
|
|
348
|
+
0,
|
|
349
|
+
)
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* The first instant strictly after `afterMs` that matches the expression.
|
|
354
|
+
*
|
|
355
|
+
* @param {object} spec - result of `parseCron`.
|
|
356
|
+
* @param {number} afterMs - epoch milliseconds; the boundary is exclusive.
|
|
357
|
+
* @param {string} timeZone - IANA zone the expression is written in.
|
|
358
|
+
* @returns {number} epoch milliseconds of the next match.
|
|
359
|
+
* @throws {CronError} when nothing matches within eight years (impossible dates such as 30 February).
|
|
360
|
+
*/
|
|
361
|
+
export function nextCronTime(spec, afterMs, timeZone) {
|
|
362
|
+
validateTimeZone(timeZone)
|
|
363
|
+
if (!Number.isFinite(afterMs)) throw new CronError('nextCronTime needs a finite epoch millisecond value')
|
|
364
|
+
let cursor = Math.floor(afterMs / 60000) * 60000
|
|
365
|
+
if (cursor <= afterMs) cursor += 60000
|
|
366
|
+
let day = zonedParts(cursor, timeZone)
|
|
367
|
+
for (let days = 0; days <= MAX_SEARCH_DAYS; days++) {
|
|
368
|
+
if (!matchesDay(spec, day)) {
|
|
369
|
+
cursor = nextLocalDay(day, timeZone)
|
|
370
|
+
day = zonedParts(cursor, timeZone)
|
|
371
|
+
continue
|
|
372
|
+
}
|
|
373
|
+
for (const hour of spec.hours) {
|
|
374
|
+
if (hour < day.hour) continue
|
|
375
|
+
for (const minute of spec.minutes) {
|
|
376
|
+
if (hour === day.hour && minute < day.minute) continue
|
|
377
|
+
const at = localToEpoch({ year: day.year, month: day.month, day: day.day, hour, minute }, timeZone)
|
|
378
|
+
if (at !== null && at > afterMs) return at
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
cursor = nextLocalDay(day, timeZone)
|
|
382
|
+
day = zonedParts(cursor, timeZone)
|
|
383
|
+
}
|
|
384
|
+
throw new CronError(
|
|
385
|
+
`cron "${spec.expression}" has no matching time within 8 years; check the day-of-month and month combination`,
|
|
386
|
+
)
|
|
387
|
+
}
|