@cronwatch/sdk 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { C as CronWatchOptions, a as CronWatch } from './client-Di5HAWQz.cjs';
-export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-Di5HAWQz.cjs';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-BjBbCGeJ.cjs';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as StoredJob, T as TriageContext, n as TriageFn } from './types-BjBbCGeJ.cjs';
+import { C as CronWatchOptions, a as CronWatch } from './client-D35cfnNV.cjs';
+export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-D35cfnNV.cjs';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Cz47Boks.cjs';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as StoredJob, T as TriageContext, n as TriageFn } from './types-Cz47Boks.cjs';
 
 /**
  * Keeps everything in process memory. The default when no store is given,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { C as CronWatchOptions, a as CronWatch } from './client-B5hM4l-D.js';
-export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-B5hM4l-D.js';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-BjBbCGeJ.js';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as StoredJob, T as TriageContext, n as TriageFn } from './types-BjBbCGeJ.js';
+import { C as CronWatchOptions, a as CronWatch } from './client-CQm-8-mR.js';
+export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-CQm-8-mR.js';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Cz47Boks.js';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as StoredJob, T as TriageContext, n as TriageFn } from './types-Cz47Boks.js';
 
 /**
  * Keeps everything in process memory. The default when no store is given,

package/dist/index.js

@@ -65,6 +65,14 @@ function formatRelative(at, now) {
   if (abs < 5e3) return text;
   return diff < 0 ? `${text} ago` : `in ${text}`;
 }
+var FIRST_DATE_MS = -621355968e5;
+var LAST_DATE_MS = 253402300799999;
+function isoTime(at) {
+  return at >= FIRST_DATE_MS && at <= LAST_DATE_MS ? new Date(at).toISOString() : null;
+}
+function beyondDates(at) {
+  return at > LAST_DATE_MS ? "after 9999-12-31 23:59:59 UTC" : "before 0001-01-01 00:00:00 UTC";
+}
 
 // src/env.ts
 function readEnv(name) {
@@ -102,15 +110,36 @@ function parseSchedule(schedule, timezone) {
   cache.set(key, parsed);
   return parsed;
 }
+var CYCLE_MS = 146097 * 864e5;
+var CRONER_FIRST_MS = Date.UTC(400, 0, 1);
+var CRONER_LAST_MS = Date.UTC(2800, 0, 1);
+function runsAfter(cron, n, from) {
+  let shift = 0;
+  if (from < CRONER_FIRST_MS) shift = Math.ceil((CRONER_FIRST_MS - from) / CYCLE_MS) * CYCLE_MS;
+  else if (from >= CRONER_LAST_MS) shift = -(Math.floor((from - CRONER_LAST_MS) / CYCLE_MS) + 1) * CYCLE_MS;
+  const out = [];
+  for (const date of cron.nextRuns(n, new Date(from + shift))) {
+    const t = date.getTime() - shift;
+    if (t > LAST_DATE_MS) break;
+    out.push(t);
+  }
+  return out;
+}
+function countFrom(from) {
+  if (from >= LAST_DATE_MS) return null;
+  return from >= FIRST_DATE_MS ? from : FIRST_DATE_MS - 1;
+}
 function fireAfter(parsed, from) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
-  let probe = from;
+  const start = countFrom(from);
+  if (start === null) return null;
+  let probe = start;
   for (let attempt = 0; attempt < 4; attempt++) {
-    const runs = cron.nextRuns(8, new Date(probe));
+    const runs = runsAfter(cron, 8, probe);
     if (runs.length === 0) return null;
-    const found = runs.find((d) => d.getTime() > from);
-    if (found) return found.getTime();
+    const found = runs.find((t) => t > start);
+    if (found !== void 0) return found;
     probe += 36e5;
   }
   return null;
@@ -119,20 +148,21 @@ function firesBetween(parsed, from, to, limit) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
   const out = [];
-  let probe = from;
-  let last = from;
+  const start = countFrom(from);
+  if (start === null) return out;
+  let probe = start;
+  let last = start;
   for (let guard = 0; guard < 1e3; guard++) {
-    const batch = cron.nextRuns(Math.min(limit + 1 - out.length, 24), new Date(probe));
+    const batch = runsAfter(cron, Math.min(limit + 1 - out.length, 24), probe);
     if (batch.length === 0) return out;
-    for (const date of batch) {
-      const t = date.getTime();
+    for (const t of batch) {
       if (t <= last) continue;
       if (t > to) return out;
       out.push(t);
       last = t;
       if (out.length > limit) return null;
     }
-    const end = batch[batch.length - 1].getTime();
+    const end = batch[batch.length - 1];
     probe = end > probe ? end : probe + 36e5;
   }
   return out;
@@ -168,6 +198,7 @@ function runCovers(startedAt, dueAt, followingAt = null) {
 }
 function inSpringForwardGap(parsed, startedAt, fireAt) {
   const LOOKBACK = 3 * 36e5;
+  if (fireAt - LOOKBACK < FIRST_DATE_MS) return false;
   const after2 = utcOffset(fireAt, parsed.timezone);
   const before = utcOffset(fireAt - LOOKBACK, parsed.timezone);
   const gap = after2 - before;
@@ -204,8 +235,10 @@ function utcOffset(at, timezone) {
   for (const part of format.formatToParts(new Date(at))) {
     if (part.type !== "literal") parts[part.type] = Number(part.value);
   }
-  const wall = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
-  return wall - Math.floor(at / 1e3) * 1e3;
+  const wall = /* @__PURE__ */ new Date(0);
+  wall.setUTCFullYear(parts.year, parts.month - 1, parts.day);
+  wall.setUTCHours(parts.hour, parts.minute, parts.second);
+  return wall.getTime() - Math.floor(at / 1e3) * 1e3;
 }
 
 // src/stats.ts
@@ -228,6 +261,20 @@ var DEFAULT_TIMEOUT_MS = 60 * 6e4;
 var SLOW_FLOOR_MS = 1e4;
 var BASELINE_MIN_RUNS = 5;
 var BASELINE_WINDOW = 20;
+var MAX_DURATION_MS = Number.MAX_SAFE_INTEGER;
+function runDuration(startedAt, finishedAt) {
+  const ms = finishedAt - startedAt;
+  return ms > 0 ? Math.min(ms, MAX_DURATION_MS) : 0;
+}
+function stateVersion(state) {
+  const version = state?.version;
+  return typeof version === "number" && Number.isSafeInteger(version) && version >= 0 ? version + 0 : 0;
+}
+function failureCount(state) {
+  const count = state?.consecutiveFailures;
+  if (typeof count !== "number" || !Number.isInteger(count) || count <= 0) return 0;
+  return Math.min(count, MAX_DURATION_MS);
+}
 function emptyState(job) {
   return { job, open: {}, consecutiveFailures: 0, silencedUntil: null, lastAlertAt: null, pendingRecovery: [], undelivered: [] };
 }
@@ -237,6 +284,7 @@ function normalizeState(state, job) {
     ...emptyState(job),
     ...state,
     open: { ...state.open },
+    consecutiveFailures: failureCount(state),
     pendingRecovery: [...state.pendingRecovery ?? []],
     undelivered: [...state.undelivered ?? []]
   };
@@ -335,7 +383,7 @@ function onRunFinish(def, run, state, history, now) {
     }
     return { state: next, alerts };
   }
-  next.consecutiveFailures += 1;
+  next.consecutiveFailures = Math.min(next.consecutiveFailures + 1, MAX_DURATION_MS);
   closeCondition(next, "missed");
   const threshold = Math.max(1, def.failuresBeforeAlert ?? 1);
   const condition = run.status === "timeout" ? "stuck" : "failed";
@@ -438,7 +486,9 @@ function summary(stored, recent, state, nextExpectedAt, health) {
 // src/format.ts
 function when(at, now) {
   if (at === null || at === void 0) return "never";
-  return `${new Date(at).toISOString().replace("T", " ").slice(0, 19)} UTC (${formatRelative(at, now)})`;
+  const iso = isoTime(at);
+  if (iso === null) return beyondDates(at);
+  return `${iso.replace("T", " ").slice(0, 19)} UTC (${formatRelative(at, now)})`;
 }
 function firstLines(text, n) {
   if (!text) return "";
@@ -547,6 +597,9 @@ function capOutput(text) {
 function stripNul(text) {
   return text.includes("\0") ? text.replace(/\u0000/g, "") : text;
 }
+function stripJsonNul(json2) {
+  return json2.includes("\\u0000") ? json2.replace(/\\(u0000|[\s\S])/g, (escape, next) => next === "u0000" ? "" : escape) : json2;
+}
 function errorMessage(error) {
   return capOutput(describeError(error));
 }
@@ -834,9 +887,13 @@ function dayLabel(t) {
   return `${WEEKDAYS[d.getUTCDay()]} ${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
 }
 function when2(t, now) {
+  if (t > LAST_DATE_MS) return "after 31 Dec 9999 23:59";
+  if (!(t >= FIRST_DATE_MS)) return "before 1 Jan 0001 00:00";
   if (Math.floor(t / DAY) === Math.floor(now / DAY)) return clock(t);
   const d = new Date(t);
-  return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${clock(t)}`;
+  const year = d.getUTCFullYear();
+  const other = year === new Date(now).getUTCFullYear() ? "" : ` ${String(year).padStart(4, "0")}`;
+  return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}${other} ${clock(t)}`;
 }
 function parsedSchedule(job) {
   if (!job.definition.schedule) return null;
@@ -1327,7 +1384,8 @@ function sparkline(runs) {
 }
 function stamp(at, now) {
   if (at === null) return `<span class="muted">never</span>`;
-  const iso = new Date(at).toISOString();
+  const iso = isoTime(at);
+  if (iso === null) return `<span class="nowrap">${beyondDates(at)}</span>`;
   return `<time class="nowrap" datetime="${iso}" title="${iso.replace("T", " ").slice(0, 19)} UTC">${h(formatRelative(at, now))}</time>`;
 }
 function healthFigures(jobs) {
@@ -1794,13 +1852,21 @@ function memory() {
   const states = /* @__PURE__ */ new Map();
   let seq = 0;
   const clone = (v) => JSON.parse(JSON.stringify(v));
+  const kept = (v) => JSON.parse(stripJsonNul(JSON.stringify(v)));
+  const keptRun = (run) => ({
+    ...clone(run),
+    trigger: stripNul(run.trigger),
+    output: run.output === null ? null : stripNul(run.output),
+    error: run.error === null ? null : stripNul(run.error),
+    metrics: kept(run.metrics)
+  });
   const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
   return {
     async upsertJob(definition, now) {
       const existing = jobs.get(definition.name);
       jobs.set(definition.name, {
         name: definition.name,
-        definition: clone(definition),
+        definition: kept(definition),
         createdAt: existing?.createdAt ?? now,
         updatedAt: now
       });
@@ -1822,19 +1888,19 @@ function memory() {
     },
     async insertRun(run) {
       if (runs.has(run.id)) throw new Error(`run ${run.id} already exists`);
-      runs.set(run.id, clone(run));
+      runs.set(run.id, keptRun(run));
       order.set(run.id, ++seq);
     },
     async updateRun(run) {
       const existing = runs.get(run.id);
       if (!existing) return;
-      const { status, finishedAt, durationMs, error, output, metrics } = clone(run);
+      const { status, finishedAt, durationMs, error, output, metrics } = keptRun(run);
       runs.set(run.id, { ...existing, status, finishedAt, durationMs, error, output, metrics });
     },
     async updateRunIf(run, fromStatuses) {
       const existing = runs.get(run.id);
       if (!existing || !fromStatuses.includes(existing.status)) return false;
-      const { status, finishedAt, durationMs, error, output, metrics } = clone(run);
+      const { status, finishedAt, durationMs, error, output, metrics } = keptRun(run);
       runs.set(run.id, { ...existing, status, finishedAt, durationMs, error, output, metrics });
       return true;
     },
@@ -1857,11 +1923,11 @@ function memory() {
       return s ? clone(s) : null;
     },
     async setState(state) {
-      states.set(state.job, clone(state));
+      states.set(state.job, kept(state));
     },
     async compareAndSetState(state, expectedVersion) {
-      if ((states.get(state.job)?.version ?? 0) !== expectedVersion) return false;
-      states.set(state.job, clone(state));
+      if (stateVersion(states.get(state.job)) !== expectedVersion) return false;
+      states.set(state.job, kept(state));
       return true;
     },
     async prune(before) {
@@ -1949,6 +2015,8 @@ var CronWatch = class {
   synced = /* @__PURE__ */ new Set();
   /** The tail of each job's queue of state updates. See serial(). */
   queues = /* @__PURE__ */ new Map();
+  /** The tail of each job's queue of declaration writes. See sync(). */
+  syncing = /* @__PURE__ */ new Map();
   /** start() calls with an id still in flight, so two at once in this process record one run. */
   starting = /* @__PURE__ */ new Map();
   ready = null;
@@ -2087,26 +2155,40 @@ var CronWatch = class {
     }
     await this.ready;
   }
+  /**
+   * Writes the declaration of `definition`'s name as it stands, unless the
+   * store has it. A handle kept from an earlier declaration writes the one
+   * that replaced it, never its own over it, and one forgotten since writes
+   * its own. The writes of one name take turns, in the order they were asked
+   * for, so one still under way cannot land after a later one; and a name
+   * declared again while its write was under way is still to be written.
+   */
   async sync(definition) {
     await this.ensureReady();
-    if (this.synced.has(definition.name)) return;
-    await this.store.upsertJob(toStored(definition), this.now());
-    this.synced.add(definition.name);
+    const name = definition.name;
+    if (this.synced.has(name)) return;
+    await this.serial(name, async () => {
+      if (this.synced.has(name)) return;
+      const standing = this.definitions.get(name) ?? definition;
+      await this.store.upsertJob(toStored(standing), this.now());
+      if ((this.definitions.get(name) ?? standing) === standing) this.synced.add(name);
+    }, this.syncing);
   }
   /**
    * Runs `fn` after every earlier state update for the same job has settled,
    * so two runs (or a run and a check) in this process never read and write
    * the job's state over each other. Other processes are coordinated by
-   * updateState() instead.
+   * updateState() instead. sync() queues a job's declaration writes the same
+   * way, in `syncing`.
    */
-  serial(job, fn) {
-    const result = (this.queues.get(job) ?? Promise.resolve()).then(fn);
+  serial(job, fn, queues = this.queues) {
+    const result = (queues.get(job) ?? Promise.resolve()).then(fn);
     const tail2 = result.then(() => {
     }, () => {
     });
-    this.queues.set(job, tail2);
+    queues.set(job, tail2);
     void tail2.then(() => {
-      if (this.queues.get(job) === tail2) this.queues.delete(job);
+      if (queues.get(job) === tail2) queues.delete(job);
     });
     return result;
   }
@@ -2130,7 +2212,7 @@ var CronWatch = class {
         const current = await this.readState(job);
         const { state, result } = await change(current);
         if (sameState(state, current)) return { state: current, result };
-        const version = current.version ?? 0;
+        const version = stateVersion(current);
         const next = { ...state, version: version + 1 };
         if (await this.writeState(next, version)) return { state: next, result };
         if (attempt >= STATE_ATTEMPTS) {
@@ -2190,7 +2272,7 @@ var CronWatch = class {
     }
     const finishedAt = this.now();
     run.finishedAt = finishedAt;
-    run.durationMs = Math.max(0, finishedAt - startedAt);
+    run.durationMs = runDuration(startedAt, finishedAt);
     run.metrics = recorder.metrics();
     run.output = recorder.output() ?? (typeof result === "string" ? capOutput(result) : null);
     this.conclude(definition, run, result, error, threw, recorder.expectText() ?? (typeof result === "string" ? result : null));
@@ -2424,7 +2506,7 @@ ${id}`;
           ...from,
           status: "running",
           finishedAt,
-          durationMs: Math.max(0, finishedAt - from.startedAt),
+          durationMs: runDuration(from.startedAt, finishedAt),
           error: null,
           output: joinOutput(from.output, added),
           metrics: { ...from.metrics, ...recorder.metrics() }
@@ -2506,6 +2588,7 @@ ${id}`;
   async recordRun(input, options = {}) {
     const declared = this.definitions.get(input.job);
     if (!declared) throw new Error(`recordRun: job "${input.job}" is not declared; call job() first`);
+    if (input.id.includes("\0")) throw new Error(`recordRun: run ids cannot contain a NUL character (job "${input.job}")`);
     await this.sync(declared);
     const run = { ...input, metrics: { ...input.metrics } };
     if (run.status === "ok") {
@@ -2613,7 +2696,7 @@ ${id}`;
         const timeout = timeoutMs(definition);
         run.status = "timeout";
         run.finishedAt = now;
-        run.durationMs = now - run.startedAt;
+        run.durationMs = runDuration(run.startedAt, now);
         run.error = `Still running after ${formatDuration(timeout)}; marked as timed out`;
         if (!await this.writeRunIf(run, ["running"])) continue;
         alerts.push(...await this.finishRun(definition, run, now));
@@ -2876,6 +2959,7 @@ function checkRunId(job, id, method) {
   if (typeof id !== "string" || id.length === 0 || id.length > 200) {
     throw new Error(`job "${job}": ${method}() needs a run id of 1 to 200 characters (got ${typeof id === "string" ? `${id.length} characters` : typeof id})`);
   }
+  if (id.includes("\0")) throw new Error(`job "${job}": ${method}() cannot take a run id containing a NUL character`);
   if (id.startsWith(RESERVED_RUN_ID_PREFIX)) {
     throw new Error(`job "${job}": ${method}() cannot take a run id starting with "${RESERVED_RUN_ID_PREFIX}", which the pg_cron source uses for its runs`);
   }