@namzu/sdk 45.0.0 → 45.1.0

package/dist/schedules/describe.js

@@ -0,0 +1,133 @@
+/**
+ * A schedule in words, for a confirmation screen or a listing.
+ *
+ * Covers the common shapes exactly and falls back to the expression itself
+ * for anything else, rather than paraphrasing it wrongly.
+ */
+import { parseCronExpression } from './cron.js';
+import { formatWall } from './tz.js';
+const MINUTE = 60_000;
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+function plural(n, unit) {
+    return `${n} ${unit}${n === 1 ? '' : 's'}`;
+}
+function describeInterval(ms) {
+    if (ms % (7 * 24 * 60 * MINUTE) === 0) {
+        const w = ms / (7 * 24 * 60 * MINUTE);
+        return w === 1 ? 'every week' : `every ${plural(w, 'week')}`;
+    }
+    if (ms % (24 * 60 * MINUTE) === 0) {
+        const d = ms / (24 * 60 * MINUTE);
+        return d === 1 ? 'every 24 hours' : `every ${plural(d, 'day')}`;
+    }
+    if (ms % (60 * MINUTE) === 0) {
+        const h = ms / (60 * MINUTE);
+        return h === 1 ? 'every hour' : `every ${plural(h, 'hour')}`;
+    }
+    const m = ms / MINUTE;
+    return m === 1 ? 'every minute' : `every ${plural(m, 'minute')}`;
+}
+/** `1,2,3,5` → `1–3, 5`. */
+function ranges(values, name) {
+    const out = [];
+    let i = 0;
+    while (i < values.length) {
+        let j = i;
+        while (j + 1 < values.length && values[j + 1] === values[j] + 1)
+            j++;
+        const a = values[i];
+        const b = values[j];
+        if (j - i >= 2)
+            out.push(`${name(a)} through ${name(b)}`);
+        else
+            for (let k = i; k <= j; k++)
+                out.push(name(values[k]));
+        i = j + 1;
+    }
+    return out.join(', ');
+}
+function isFull(values, min, max) {
+    return values.length === max - min + 1;
+}
+function describeDays(e) {
+    const allDom = !e.domRestricted;
+    const allDow = !e.dowRestricted;
+    const allMonths = isFull(e.months, 1, 12);
+    let days;
+    if (allDom && allDow)
+        days = 'every day';
+    else if (allDom)
+        days = `on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`;
+    else if (allDow)
+        days = `on day ${ranges(e.daysOfMonth, String)} of the month`;
+    else
+        days = `on day ${ranges(e.daysOfMonth, String)} of the month and on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`;
+    if (!allMonths)
+        days += ` in ${ranges(e.months, (m) => MONTH_NAMES[m - 1] ?? String(m))}`;
+    return days;
+}
+function describeTimes(e, source) {
+    const [mi = '', ho = ''] = source.split(' ');
+    const allMinutes = isFull(e.minutes, 0, 59);
+    const allHours = isFull(e.hours, 0, 23);
+    if (allMinutes && allHours)
+        return 'every minute';
+    const stepMinute = /^\*\/(\d+)$/.exec(mi);
+    if (stepMinute && allHours)
+        return `every ${plural(Number(stepMinute[1]), 'minute')}`;
+    if (allHours && e.minutes.length <= 4) {
+        return e.minutes.length === 1 && e.minutes[0] === 0
+            ? 'every hour, on the hour'
+            : `every hour at minute ${e.minutes.join(', ')}`;
+    }
+    const stepHour = /^\*\/(\d+)$/.exec(ho);
+    if (stepHour && e.minutes.length === 1) {
+        return `every ${plural(Number(stepHour[1]), 'hour')} at minute ${e.minutes[0]}`;
+    }
+    if (e.hours.length * e.minutes.length <= 6) {
+        const times = [];
+        for (const h of e.hours)
+            for (const m of e.minutes)
+                times.push(`${pad(h)}:${pad(m)}`);
+        return `at ${times.join(', ')}`;
+    }
+    return `at minute ${ranges(e.minutes, String)} of hour ${ranges(e.hours, String)}`;
+}
+/** The schedule in words: `at 03:00 every day (Europe/Istanbul)`. */
+export function describeSchedule(spec, options = {}) {
+    const tz = options.tz ?? 'UTC';
+    switch (spec.kind) {
+        case 'at':
+            return `once at ${formatWall(Date.parse(spec.at), tz)} (${tz})`;
+        case 'every':
+            return describeInterval(spec.everyMs);
+        case 'cron': {
+            let e;
+            try {
+                e = parseCronExpression(spec.expr);
+            }
+            catch {
+                return `cron "${spec.expr}" (${spec.tz})`;
+            }
+            return `${describeTimes(e, e.source)} ${describeDays(e)} (${spec.tz})`;
+        }
+    }
+}
+//# sourceMappingURL=describe.js.map

package/dist/schedules/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/schedules/describe.ts"],"names":[],"mappings":"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"}

package/dist/schedules/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A schedule, cron expression or time zone that cannot be used.
+ *
+ * `token` names the piece of the input that was refused, so a caller can
+ * point at it instead of repeating the whole expression back.
+ */
+export declare class ScheduleValidationError extends Error {
+    readonly token: string | undefined;
+    constructor(message: string, token?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/schedules/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/schedules/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAK3C"}

package/dist/schedules/errors.js

@@ -0,0 +1,15 @@
+/**
+ * A schedule, cron expression or time zone that cannot be used.
+ *
+ * `token` names the piece of the input that was refused, so a caller can
+ * point at it instead of repeating the whole expression back.
+ */
+export class ScheduleValidationError extends Error {
+    token;
+    constructor(message, token) {
+        super(message);
+        this.name = 'ScheduleValidationError';
+        this.token = token;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/schedules/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/schedules/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACxC,KAAK,CAAoB;IAElC,YAAY,OAAe,EAAE,KAAc;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;CACD"}

package/dist/schedules/evaluate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What to do about one job now: fire, skip, record a miss, or nothing.
+ *
+ * Pure: no clock, no I/O. The host passes the instant, the state it kept and
+ * whether an occurrence was already claimed, and applies the decision itself
+ * (append history, claim, dispatch). Evaluating the same `(state, now)` twice
+ * gives the same answer, so a host that lost its in-memory queue rebuilds it
+ * by evaluating again; an already-claimed key is never fired twice.
+ *
+ * Rules, in order:
+ *
+ * 1. Occurrences due are those in `(lastEvaluatedAt, now]`, counted with a
+ *    cap and never enumerated. A new job counts from its creation. A changed
+ *    revision counts from the change, so editing `0 3 * * *` into `0 4 * * *`
+ *    does not invent catch-ups for 04:00s that never belonged to the job.
+ * 2. `lastEvaluatedAt` never moves backwards: after a backward clock jump
+ *    nothing is due until the wall clock passes it again.
+ * 3. A job that is not active produces skip records only (paused and
+ *    awaiting-confirmation are collapsed per evaluation). A one-shot whose
+ *    time passed while inactive is expired.
+ * 4. The latest due occurrence fires on time (`scheduled`, or `late` once
+ *    more than five seconds late) within the late grace; within the catch-up
+ *    window it fires once as `catch-up` and everything earlier is one
+ *    `missed` record; older than the window, nothing fires.
+ * 5. An unfinished run of the same job skips what came due meanwhile.
+ * 6. A provider quota hold skips what comes due before the hold ends.
+ */
+import type { ScheduleDecision, ScheduleEvaluationInput } from './types.js';
+/** Default catch-up window: seven days. */
+export declare const SCHEDULE_CATCH_UP_WINDOW_MS: number;
+/** Default grace for a fire to still count as on time: two minutes. */
+export declare const SCHEDULE_LATE_GRACE_MS = 120000;
+/** Evaluate one job at `now`. */
+export declare function evaluateJob(input: ScheduleEvaluationInput): ScheduleDecision;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/schedules/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/schedules/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EAGvB,MAAM,YAAY,CAAA;AAEnB,2CAA2C;AAC3C,eAAO,MAAM,2BAA2B,QAA0B,CAAA;AAClE,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,SAAU,CAAA;AAe7C,iCAAiC;AACjC,wBAAgB,WAAW,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB,CA0H5E"}

package/dist/schedules/evaluate.js

@@ -0,0 +1,158 @@
+/**
+ * What to do about one job now: fire, skip, record a miss, or nothing.
+ *
+ * Pure: no clock, no I/O. The host passes the instant, the state it kept and
+ * whether an occurrence was already claimed, and applies the decision itself
+ * (append history, claim, dispatch). Evaluating the same `(state, now)` twice
+ * gives the same answer, so a host that lost its in-memory queue rebuilds it
+ * by evaluating again; an already-claimed key is never fired twice.
+ *
+ * Rules, in order:
+ *
+ * 1. Occurrences due are those in `(lastEvaluatedAt, now]`, counted with a
+ *    cap and never enumerated. A new job counts from its creation. A changed
+ *    revision counts from the change, so editing `0 3 * * *` into `0 4 * * *`
+ *    does not invent catch-ups for 04:00s that never belonged to the job.
+ * 2. `lastEvaluatedAt` never moves backwards: after a backward clock jump
+ *    nothing is due until the wall clock passes it again.
+ * 3. A job that is not active produces skip records only (paused and
+ *    awaiting-confirmation are collapsed per evaluation). A one-shot whose
+ *    time passed while inactive is expired.
+ * 4. The latest due occurrence fires on time (`scheduled`, or `late` once
+ *    more than five seconds late) within the late grace; within the catch-up
+ *    window it fires once as `catch-up` and everything earlier is one
+ *    `missed` record; older than the window, nothing fires.
+ * 5. An unfinished run of the same job skips what came due meanwhile.
+ * 6. A provider quota hold skips what comes due before the hold ends.
+ */
+import { countOccurrences, nextFireTime, previousFireTime } from './next-fire.js';
+/** Default catch-up window: seven days. */
+export const SCHEDULE_CATCH_UP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Default grace for a fire to still count as on time: two minutes. */
+export const SCHEDULE_LATE_GRACE_MS = 120_000;
+/** A fire later than this is reported `late` rather than `scheduled`. */
+const LATE_THRESHOLD_MS = 5_000;
+function missedReason(input, firstMissed) {
+    const gap = input.daemon.observedGap;
+    if (gap && firstMissed.getTime() >= gap.from.getTime()) {
+        if (gap.kind === 'asleep')
+            return 'machine-asleep';
+        if (gap.kind === 'clock-forward')
+            return 'clock-jumped-forward';
+    }
+    return 'daemon-not-running';
+}
+/** Evaluate one job at `now`. */
+export function evaluateJob(input) {
+    const { job, state, now } = input;
+    const nowMs = now.getTime();
+    const lateGrace = input.lateGraceMs ?? SCHEDULE_LATE_GRACE_MS;
+    const windowMs = job.catchUp?.windowMs ?? SCHEDULE_CATCH_UP_WINDOW_MS;
+    let baseMs = Date.parse(state.lastEvaluatedAt ?? job.createdAt);
+    if (!Number.isFinite(baseMs))
+        baseMs = Date.parse(job.createdAt);
+    if (state.jobRevision !== undefined && state.jobRevision !== job.revision) {
+        baseMs = Math.max(baseMs, Date.parse(job.updatedAt));
+    }
+    const nextState = (evaluatedMs) => {
+        const next = nextFireTime(job.spec, new Date(evaluatedMs));
+        return {
+            lastEvaluatedAt: new Date(evaluatedMs),
+            ...(next ? { nextFireAt: next } : {}),
+            jobRevision: job.revision,
+        };
+    };
+    if (job.state === 'completed' || job.state === 'expired') {
+        return {
+            skip: [],
+            nextState: { lastEvaluatedAt: new Date(Math.max(baseMs, nowMs)), jobRevision: job.revision },
+        };
+    }
+    // Rule 2: a clock that went backwards decides nothing new.
+    if (nowMs <= baseMs)
+        return { skip: [], nextState: nextState(baseMs) };
+    const due = countOccurrences(job.spec, new Date(baseMs), now);
+    if (due.count === 0 || !due.latest) {
+        if (job.spec.kind === 'at' && Date.parse(job.spec.at) <= baseMs && job.state !== 'active') {
+            return { skip: [], jobTransition: 'expired', nextState: nextState(nowMs) };
+        }
+        return { skip: [], nextState: nextState(nowMs) };
+    }
+    const latest = due.latest;
+    const collapsed = (reason) => [
+        { scheduledFor: latest, reason, count: due.count },
+    ];
+    if (job.state === 'paused' || job.state === 'pending-confirmation') {
+        const reason = job.state === 'paused' ? 'paused' : 'awaiting-confirmation';
+        return {
+            skip: collapsed(reason),
+            ...(job.spec.kind === 'at' ? { jobTransition: 'expired' } : {}),
+            nextState: nextState(nowMs),
+        };
+    }
+    const hold = state.quotaHoldUntil ? Date.parse(state.quotaHoldUntil) : Number.NaN;
+    if (Number.isFinite(hold) && hold > nowMs) {
+        return { skip: collapsed('quota-hold'), nextState: nextState(nowMs) };
+    }
+    if (state.activeRun) {
+        return {
+            skip: collapsed(state.activeRun.status === 'awaiting-approval'
+                ? 'previous-run-awaiting-approval'
+                : 'previous-run-active'),
+            nextState: nextState(nowMs),
+        };
+    }
+    const key = String(latest.getTime());
+    const lateBy = nowMs - latest.getTime();
+    const earlier = due.count - 1;
+    const missedBefore = () => {
+        if (earlier <= 0 || !due.first)
+            return undefined;
+        // The occurrence just before the fired one.
+        const to = previousFireTime(job.spec, new Date(latest.getTime() - 1)) ?? due.first;
+        return {
+            from: due.first,
+            to,
+            count: earlier,
+            capped: due.capped,
+            reason: missedReason(input, due.first),
+        };
+    };
+    const transition = job.spec.kind === 'at' ? { jobTransition: 'completed' } : {};
+    if (input.isClaimed?.(key)) {
+        // Somebody already started it; nothing to fire, nothing missed.
+        return { skip: [], ...transition, nextState: nextState(nowMs) };
+    }
+    if (lateBy <= lateGrace || lateBy <= windowMs) {
+        const trigger = lateBy <= lateGrace ? (lateBy > LATE_THRESHOLD_MS ? 'late' : 'scheduled') : 'catch-up';
+        const missed = missedBefore();
+        return {
+            fire: { key, scheduledFor: latest, trigger },
+            skip: [],
+            ...(missed ? { missed } : {}),
+            ...transition,
+            nextState: nextState(nowMs),
+        };
+    }
+    // Everything due is older than the window.
+    const first = due.first ?? latest;
+    return {
+        skip: [
+            {
+                scheduledFor: latest,
+                reason: job.spec.kind === 'at' ? 'one-shot-expired' : 'beyond-catch-up-window',
+                count: 1,
+            },
+        ],
+        missed: {
+            from: first,
+            to: latest,
+            count: due.count,
+            capped: due.capped,
+            reason: missedReason(input, first),
+        },
+        ...(job.spec.kind === 'at' ? { jobTransition: 'expired' } : {}),
+        nextState: nextState(nowMs),
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/schedules/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/schedules/evaluate.ts"],"names":[],"mappings":"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"}

package/dist/schedules/index.d.ts

@@ -0,0 +1,11 @@
+export { parseCronExpression } from './cron.js';
+export { describeSchedule } from './describe.js';
+export type { DescribeScheduleOptions } from './describe.js';
+export { ScheduleValidationError } from './errors.js';
+export { SCHEDULE_CATCH_UP_WINDOW_MS, SCHEDULE_LATE_GRACE_MS, evaluateJob, } from './evaluate.js';
+export { countOccurrences, nextFireTime, previousFireTime, } from './next-fire.js';
+export { parseDuration, parseScheduleSpec, upcomingFireTimes } from './spec.js';
+export type { ParseScheduleOptions } from './spec.js';
+export { hostTimeZone, validateTimeZone } from './tz.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schedules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EACN,2BAA2B,EAC3B,sBAAsB,EACtB,WAAW,GACX,MAAM,eAAe,CAAA;AACtB,OAAO,EACN,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GAChB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC/E,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACxD,mBAAmB,YAAY,CAAA"}

package/dist/schedules/index.js

@@ -0,0 +1,8 @@
+export { parseCronExpression } from './cron.js';
+export { describeSchedule } from './describe.js';
+export { ScheduleValidationError } from './errors.js';
+export { SCHEDULE_CATCH_UP_WINDOW_MS, SCHEDULE_LATE_GRACE_MS, evaluateJob, } from './evaluate.js';
+export { countOccurrences, nextFireTime, previousFireTime, } from './next-fire.js';
+export { parseDuration, parseScheduleSpec, upcomingFireTimes } from './spec.js';
+export { hostTimeZone, validateTimeZone } from './tz.js';
+//# sourceMappingURL=index.js.map

package/dist/schedules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EACN,2BAA2B,EAC3B,sBAAsB,EACtB,WAAW,GACX,MAAM,eAAe,CAAA;AACtB,OAAO,EACN,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GAChB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAE/E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA"}

package/dist/schedules/next-fire.d.ts

@@ -0,0 +1,50 @@
+/**
+ * When a spec fires: the next instant, the previous one, and how many fall
+ * in a window.
+ *
+ * Cron is walked a local DAY at a time — never a minute at a time over years
+ * — and a day with no DST change is computed arithmetically from one offset.
+ * Only a day whose offset changes is examined slot by slot, and that is where
+ * cronie's rule is applied:
+ *
+ * - a fixed-time expression (`30 2 * * *`) whose time falls in a
+ *   spring-forward gap fires once, at the first instant after the gap;
+ *   whose time is repeated by a fall-back fires once, at the first of the two;
+ * - a wildcard or step expression (`0 * * * *`, `*\/15 * * * *`) fires at
+ *   every instant whose wall time matches: the repeated hour runs twice and
+ *   slots inside the gap do not exist.
+ */
+import type { CronExpression, OccurrenceCount, ScheduleSpec } from './types.js';
+/** How far ahead a cron search looks before deciding the expression never fires. */
+export declare const CRON_HORIZON_DAYS: number;
+/**
+ * Occurrence counts stop here. Counting a day without a DST change costs one
+ * multiplication, so the cap bounds the pathological case (a years-long gap
+ * on a per-minute job) rather than the ordinary one.
+ */
+export declare const OCCURRENCE_COUNT_CAP = 100000;
+/**
+ * Every instant the expression fires on one local day (`dayWall` is that
+ * day's midnight as a wall value), ascending.
+ */
+export declare function cronInstantsOnDay(expr: CronExpression, tz: string, dayWall: number): number[];
+/**
+ * The first instant strictly after `afterExclusive` at which `spec` fires,
+ * or `null` when there is none (a past `at`, or a cron expression with no
+ * occurrence in the next five years).
+ */
+export declare function nextFireTime(spec: ScheduleSpec, afterExclusive: Date): Date | null;
+/**
+ * The last instant at or before `atOrBefore` at which `spec` fired, or
+ * `null` if none within the horizon (or before the anchor / the `at`).
+ */
+export declare function previousFireTime(spec: ScheduleSpec, atOrBefore: Date): Date | null;
+/**
+ * How many times `spec` fires in `(fromExclusive, toInclusive]`, with the
+ * first and latest of them. Stops counting at `cap` (default 100 000) and
+ * says so, without enumerating beyond it; the latest is exact either way.
+ */
+export declare function countOccurrences(spec: ScheduleSpec, fromExclusive: Date, toInclusive: Date, cap?: number): OccurrenceCount;
+/** Validate a spec as a whole: its zone, its expression, and that it can ever fire after `now`. */
+export declare function assertSpecFires(spec: ScheduleSpec, now: Date): void;
+//# sourceMappingURL=next-fire.d.ts.map

package/dist/schedules/next-fire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-fire.d.ts","sourceRoot":"","sources":["../../src/schedules/next-fire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM/E,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,QAAc,CAAA;AAC5C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAmB3C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAoC7F;AAgBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAwBlF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CA0BlF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,YAAY,EAClB,aAAa,EAAE,IAAI,EACnB,WAAW,EAAE,IAAI,EACjB,GAAG,GAAE,MAA6B,GAChC,eAAe,CA4DjB;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAanE"}