@swirls/looms 0.3.0 → 0.5.0

package/dist/schedule/module.js

@@ -0,0 +1,22 @@
+import { defineModule, makeDefinitionStore } from '@swirls/looms/core';
+import { ScheduleDefinitionsLive } from './definitions-store.js';
+import { fireEffect, planEffect } from './effects.js';
+import { scheduleStatus } from './projections.js';
+import { scheduleModule } from './scope.js';
+import { DEFAULT_MIN_INTERVAL_MS } from './specs.js';
+import { createScheduleThread } from './threads.js';
+export function schedule(options = {}) {
+    const listed = options.definitions ?? [];
+    const definitions = makeDefinitionStore('schedule', listed);
+    const minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+    return defineModule(scheduleModule, () => ({
+        definitions: listed,
+        threads: { schedule: createScheduleThread(definitions, minIntervalMs) },
+        effects: { plan: planEffect, fire: fireEffect },
+        projections: { scheduleStatus },
+        services: () => ScheduleDefinitionsLive(definitions),
+        bindHost(host) {
+            definitions.useResolver(host.definitionResolver);
+        },
+    }));
+}

package/dist/schedule/projections.d.ts

@@ -0,0 +1,55 @@
+import { Schema } from 'effect';
+export declare const ScheduleRecentSchema: Schema.Struct<{
+    readonly at: Schema.Finite;
+    readonly runId: Schema.NullOr<Schema.String>;
+    readonly outcome: Schema.Union<readonly [Schema.Literal<"fired">, Schema.Literal<"skipped">]>;
+    readonly reason: Schema.optional<Schema.String>;
+}>;
+export type ScheduleRecent = Schema.Schema.Type<typeof ScheduleRecentSchema>;
+export declare const ScheduleStatusSchema: Schema.Struct<{
+    readonly spec: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"cron">;
+        readonly expr: Schema.String;
+        readonly tz: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"every">;
+        readonly everyMs: Schema.Finite;
+        readonly anchor: Schema.optional<Schema.Finite>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"once">;
+        readonly at: Schema.Finite;
+    }>]>>;
+    readonly status: Schema.Union<readonly [Schema.Literal<"running">, Schema.Literal<"paused">, Schema.Literal<"retired">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+    readonly nextAt: Schema.NullOr<Schema.Finite>;
+    readonly fireCount: Schema.Finite;
+    readonly recent: Schema.$Array<Schema.Struct<{
+        readonly at: Schema.Finite;
+        readonly runId: Schema.NullOr<Schema.String>;
+        readonly outcome: Schema.Union<readonly [Schema.Literal<"fired">, Schema.Literal<"skipped">]>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>;
+}>;
+export type ScheduleStatus = Schema.Schema.Type<typeof ScheduleStatusSchema>;
+export declare const scheduleStatus: import("@swirls/looms/core").ProjectionDefinition<{
+    readonly spec: {
+        readonly type: "cron";
+        readonly expr: string;
+        readonly tz?: string | undefined;
+    } | {
+        readonly type: "every";
+        readonly everyMs: number;
+        readonly anchor?: number | undefined;
+    } | {
+        readonly type: "once";
+        readonly at: number;
+    } | null;
+    readonly status: "cancelled" | "completed" | "failed" | "paused" | "retired" | "running";
+    readonly nextAt: number | null;
+    readonly fireCount: number;
+    readonly recent: readonly {
+        readonly at: number;
+        readonly runId: string | null;
+        readonly outcome: "fired" | "skipped";
+        readonly reason?: string | undefined;
+    }[];
+}>;

package/dist/schedule/projections.js

@@ -0,0 +1,88 @@
+import { Schema } from 'effect';
+import { scheduleModule } from './scope.js';
+import { ScheduleSpecSchema } from './specs.js';
+const RECENT_LIMIT = 20;
+export const ScheduleRecentSchema = Schema.Struct({
+    at: Schema.Finite,
+    runId: Schema.NullOr(Schema.String),
+    outcome: Schema.Union([Schema.Literal('fired'), Schema.Literal('skipped')]),
+    reason: Schema.optional(Schema.String),
+});
+export const ScheduleStatusSchema = Schema.Struct({
+    spec: Schema.NullOr(ScheduleSpecSchema),
+    status: Schema.Union([
+        Schema.Literal('running'),
+        Schema.Literal('paused'),
+        Schema.Literal('retired'),
+        Schema.Literal('completed'),
+        Schema.Literal('failed'),
+        Schema.Literal('cancelled'),
+    ]),
+    nextAt: Schema.NullOr(Schema.Finite),
+    fireCount: Schema.Finite,
+    recent: Schema.Array(ScheduleRecentSchema),
+});
+export const scheduleStatus = scheduleModule.projection({
+    name: 'scheduleStatus',
+    shape: ScheduleStatusSchema,
+    initialState: {
+        spec: null,
+        status: 'running',
+        nextAt: null,
+        fireCount: 0,
+        recent: [],
+    },
+    reduce(state, event) {
+        switch (event.type) {
+            case 'schedule.planned':
+                return { ...state, spec: event.payload.spec, nextAt: event.payload.nextAt };
+            case 'schedule.updated':
+                return event.payload.spec === undefined ? state : { ...state, spec: event.payload.spec };
+            case 'schedule.fired':
+                return {
+                    ...state,
+                    nextAt: event.payload.nextAt,
+                    fireCount: state.fireCount + 1,
+                    recent: remember(state.recent, {
+                        at: event.payload.at,
+                        runId: event.payload.runId,
+                        outcome: 'fired',
+                    }),
+                };
+            case 'schedule.skipped':
+                return {
+                    ...state,
+                    nextAt: event.payload.nextAt,
+                    recent: remember(state.recent, {
+                        at: event.payload.at,
+                        runId: null,
+                        outcome: 'skipped',
+                        reason: event.payload.reason,
+                    }),
+                };
+            case 'schedule.paused':
+                return {
+                    ...state,
+                    status: state.status === 'retired' ? 'retired' : 'paused',
+                    nextAt: null,
+                };
+            case 'schedule.resumed':
+                return { ...state, status: 'running' };
+            case 'schedule.retired':
+                return { ...state, status: 'retired', nextAt: null };
+            case 'runtime.thread.completed':
+                return { ...state, status: 'completed', nextAt: null };
+            case 'runtime.thread.failed':
+                return { ...state, status: 'failed', nextAt: null };
+            case 'runtime.run.cancelled':
+            case 'runtime.thread.cancelled':
+                return { ...state, status: 'cancelled', nextAt: null };
+            default:
+                return state;
+        }
+    },
+});
+function remember(recent, item) {
+    const next = [...recent, item];
+    return next.length > RECENT_LIMIT ? next.slice(next.length - RECENT_LIMIT) : next;
+}

package/dist/schedule/scope.d.ts

@@ -0,0 +1,121 @@
+import { type EventOf } from '@swirls/looms/core';
+export declare const scheduleModule: import("@swirls/looms/core").ModuleScope<"schedule", import("@swirls/looms/core").ScopeUniverse<import("@swirls/looms/core").EventCatalog<"schedule", {
+    planned: import("effect/Schema").Struct<{
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly spec: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"cron">;
+            readonly expr: import("effect/Schema").String;
+            readonly tz: import("effect/Schema").optional<import("effect/Schema").String>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"every">;
+            readonly everyMs: import("effect/Schema").Finite;
+            readonly anchor: import("effect/Schema").optional<import("effect/Schema").Finite>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"once">;
+            readonly at: import("effect/Schema").Finite;
+        }>]>;
+    }>;
+    fired: import("effect/Schema").Struct<{
+        readonly at: import("effect/Schema").Finite;
+        readonly runId: import("effect/Schema").String;
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly manual: import("effect/Schema").Boolean;
+        readonly triggerId: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    skipped: import("effect/Schema").Struct<{
+        readonly at: import("effect/Schema").Finite;
+        readonly reason: import("effect/Schema").String;
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly manual: import("effect/Schema").Boolean;
+        readonly triggerId: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    updated: import("effect/Schema").Struct<{
+        readonly spec: import("effect/Schema").optional<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"cron">;
+            readonly expr: import("effect/Schema").String;
+            readonly tz: import("effect/Schema").optional<import("effect/Schema").String>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"every">;
+            readonly everyMs: import("effect/Schema").Finite;
+            readonly anchor: import("effect/Schema").optional<import("effect/Schema").Finite>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"once">;
+            readonly at: import("effect/Schema").Finite;
+        }>]>>;
+        readonly input: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>>;
+        readonly endAt: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Finite>>;
+        readonly maxFires: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Finite>>;
+        readonly definitionName: import("effect/Schema").optional<import("effect/Schema").String>;
+        readonly definitionVersion: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    paused: import("effect/Schema").Struct<{}>;
+    resumed: import("effect/Schema").Struct<{}>;
+    retired: import("effect/Schema").Struct<{}>;
+    triggered: import("effect/Schema").Struct<{}>;
+    rejected: import("effect/Schema").Struct<{
+        readonly reason: import("effect/Schema").String;
+    }>;
+}>, undefined>, import("@swirls/looms/core").EventCatalog<"schedule", {
+    planned: import("effect/Schema").Struct<{
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly spec: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"cron">;
+            readonly expr: import("effect/Schema").String;
+            readonly tz: import("effect/Schema").optional<import("effect/Schema").String>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"every">;
+            readonly everyMs: import("effect/Schema").Finite;
+            readonly anchor: import("effect/Schema").optional<import("effect/Schema").Finite>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"once">;
+            readonly at: import("effect/Schema").Finite;
+        }>]>;
+    }>;
+    fired: import("effect/Schema").Struct<{
+        readonly at: import("effect/Schema").Finite;
+        readonly runId: import("effect/Schema").String;
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly manual: import("effect/Schema").Boolean;
+        readonly triggerId: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    skipped: import("effect/Schema").Struct<{
+        readonly at: import("effect/Schema").Finite;
+        readonly reason: import("effect/Schema").String;
+        readonly nextAt: import("effect/Schema").NullOr<import("effect/Schema").Finite>;
+        readonly generation: import("effect/Schema").Finite;
+        readonly manual: import("effect/Schema").Boolean;
+        readonly triggerId: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    updated: import("effect/Schema").Struct<{
+        readonly spec: import("effect/Schema").optional<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"cron">;
+            readonly expr: import("effect/Schema").String;
+            readonly tz: import("effect/Schema").optional<import("effect/Schema").String>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"every">;
+            readonly everyMs: import("effect/Schema").Finite;
+            readonly anchor: import("effect/Schema").optional<import("effect/Schema").Finite>;
+        }>, import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Literal<"once">;
+            readonly at: import("effect/Schema").Finite;
+        }>]>>;
+        readonly input: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>>;
+        readonly endAt: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Finite>>;
+        readonly maxFires: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Finite>>;
+        readonly definitionName: import("effect/Schema").optional<import("effect/Schema").String>;
+        readonly definitionVersion: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>;
+    paused: import("effect/Schema").Struct<{}>;
+    resumed: import("effect/Schema").Struct<{}>;
+    retired: import("effect/Schema").Struct<{}>;
+    triggered: import("effect/Schema").Struct<{}>;
+    rejected: import("effect/Schema").Struct<{
+        readonly reason: import("effect/Schema").String;
+    }>;
+}>, undefined>;
+export type ScheduleEvent = EventOf<typeof scheduleModule>;

package/dist/schedule/scope.js

@@ -0,0 +1,7 @@
+import { createModuleScope } from '@swirls/looms/core';
+import { scheduleCatalog } from './events.js';
+export const scheduleModule = createModuleScope({
+    namespace: 'schedule',
+    protocolVersion: '1.0.0',
+    events: scheduleCatalog,
+});

package/dist/schedule/signals.d.ts

@@ -0,0 +1,25 @@
+import type { EventInput, JsonValue } from '@swirls/looms/core';
+import type { ScheduleSpec } from './specs';
+export interface ScheduleUpdate {
+    readonly spec?: ScheduleSpec;
+    readonly input?: JsonValue | null;
+    /** `null` clears the bound. Omit the field to leave it unchanged. */
+    readonly endAt?: number | null;
+    /** `null` clears the bound. Omit the field to leave it unchanged. */
+    readonly maxFires?: number | null;
+    readonly definitionName?: string;
+    readonly definitionVersion?: string;
+}
+/** Replace the spec, stored input, or bounds. A no-op when nothing changed. */
+export declare function update(patch: ScheduleUpdate): EventInput;
+/** Drop the armed fire and delete the alarm. A later `resume` rebases from now. */
+export declare function pause(): EventInput;
+/** Arm the next fire after now. Missed fires are not caught up. */
+export declare function resume(): EventInput;
+/**
+ * Park a removed schedule without cancelling it, so the same run id can be resumed.
+ * Cancel remains the permanent delete.
+ */
+export declare function retire(): EventInput;
+/** Start one target run now, without moving the armed fire. */
+export declare function trigger(): EventInput;

package/dist/schedule/signals.js

@@ -0,0 +1,33 @@
+import { scheduleModule } from './scope.js';
+/** Replace the spec, stored input, or bounds. A no-op when nothing changed. */
+export function update(patch) {
+    return scheduleModule.input('updated', {
+        ...(patch.spec === undefined ? undefined : { spec: patch.spec }),
+        ...(patch.input === undefined ? undefined : { input: patch.input }),
+        ...(patch.endAt === undefined ? undefined : { endAt: patch.endAt }),
+        ...(patch.maxFires === undefined ? undefined : { maxFires: patch.maxFires }),
+        ...(patch.definitionName === undefined ? undefined : { definitionName: patch.definitionName }),
+        ...(patch.definitionVersion === undefined
+            ? undefined
+            : { definitionVersion: patch.definitionVersion }),
+    });
+}
+/** Drop the armed fire and delete the alarm. A later `resume` rebases from now. */
+export function pause() {
+    return scheduleModule.input('paused', {});
+}
+/** Arm the next fire after now. Missed fires are not caught up. */
+export function resume() {
+    return scheduleModule.input('resumed', {});
+}
+/**
+ * Park a removed schedule without cancelling it, so the same run id can be resumed.
+ * Cancel remains the permanent delete.
+ */
+export function retire() {
+    return scheduleModule.input('retired', {});
+}
+/** Start one target run now, without moving the armed fire. */
+export function trigger() {
+    return scheduleModule.input('triggered', {});
+}

package/dist/schedule/specs.d.ts

@@ -0,0 +1,59 @@
+import { Schema } from 'effect';
+/** Default minimum gap between fires. Cron's own minute is the floor. */
+export declare const DEFAULT_MIN_INTERVAL_MS = 60000;
+/** A late alarm within this window still counts as on time. */
+export declare const MISFIRE_GRACE_MS = 1000;
+export declare const CronSpecSchema: Schema.Struct<{
+    readonly type: Schema.Literal<"cron">;
+    readonly expr: Schema.String;
+    readonly tz: Schema.optional<Schema.String>;
+}>;
+export declare const EverySpecSchema: Schema.Struct<{
+    readonly type: Schema.Literal<"every">;
+    readonly everyMs: Schema.Finite;
+    readonly anchor: Schema.optional<Schema.Finite>;
+}>;
+export declare const OnceSpecSchema: Schema.Struct<{
+    readonly type: Schema.Literal<"once">;
+    readonly at: Schema.Finite;
+}>;
+export declare const ScheduleSpecSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"cron">;
+    readonly expr: Schema.String;
+    readonly tz: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"every">;
+    readonly everyMs: Schema.Finite;
+    readonly anchor: Schema.optional<Schema.Finite>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"once">;
+    readonly at: Schema.Finite;
+}>]>;
+export type ScheduleSpec = Schema.Schema.Type<typeof ScheduleSpecSchema>;
+export type CronSpec = Schema.Schema.Type<typeof CronSpecSchema>;
+export type EverySpec = Schema.Schema.Type<typeof EverySpecSchema>;
+export type OnceSpec = Schema.Schema.Type<typeof OnceSpecSchema>;
+export interface EveryOptions {
+    /** Epoch millisecond the interval is aligned to. Defaults to the unix epoch. */
+    readonly anchor?: number;
+}
+/** A cron expression. `tz` is an IANA name; omitted expressions are evaluated in UTC. */
+export declare function cron(expr: string, options?: {
+    readonly tz?: string;
+}): CronSpec;
+/** A fixed interval. `duration` is milliseconds, or a string such as `15m`, `1h`, or `30s`. */
+export declare function every(duration: string | number, options?: EveryOptions): EverySpec;
+/** One fire at an absolute epoch millisecond. */
+export declare function once(at: number): OnceSpec;
+/**
+ * The first fire strictly after `after`. Invalid specs and an exhausted `once` return null.
+ * This is pure: it does not read the clock.
+ */
+export declare function nextFireAt(spec: ScheduleSpec, after: number): number | null;
+/** A short label for the debugger and logs. */
+export declare function describeSpec(spec: ScheduleSpec): string;
+/**
+ * Why `spec` cannot be armed, or undefined when it is allowed.
+ * `once` has no gap. A gap equal to `minIntervalMs` is allowed.
+ */
+export declare function specRejection(spec: ScheduleSpec, minIntervalMs: number): string | undefined;

package/dist/schedule/specs.js

@@ -0,0 +1,231 @@
+import { Cron, Result, Schema } from 'effect';
+/** Default minimum gap between fires. Cron's own minute is the floor. */
+export const DEFAULT_MIN_INTERVAL_MS = 60_000;
+/** A late alarm within this window still counts as on time. */
+export const MISFIRE_GRACE_MS = 1_000;
+const GAP_SAMPLE_STARTS = [
+    1_768_435_200_000, 1_774_656_000_000, 1_772_841_600_000, 1_792_800_000_000, 1_793_491_200_000,
+];
+const GAP_SAMPLE_COUNT = 32;
+const DURATION_UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+export const CronSpecSchema = Schema.Struct({
+    type: Schema.Literal('cron'),
+    expr: Schema.String,
+    tz: Schema.optional(Schema.String),
+});
+export const EverySpecSchema = Schema.Struct({
+    type: Schema.Literal('every'),
+    everyMs: Schema.Finite,
+    anchor: Schema.optional(Schema.Finite),
+});
+export const OnceSpecSchema = Schema.Struct({
+    type: Schema.Literal('once'),
+    at: Schema.Finite,
+});
+export const ScheduleSpecSchema = Schema.Union([CronSpecSchema, EverySpecSchema, OnceSpecSchema]);
+/** A cron expression. `tz` is an IANA name; omitted expressions are evaluated in UTC. */
+export function cron(expr, options) {
+    const tz = options?.tz;
+    return tz === undefined ? { type: 'cron', expr } : { type: 'cron', expr, tz };
+}
+/** A fixed interval. `duration` is milliseconds, or a string such as `15m`, `1h`, or `30s`. */
+export function every(duration, options) {
+    const everyMs = isMilliseconds(duration) ? duration : parseDuration(duration);
+    if (!Number.isFinite(everyMs) || everyMs <= 0) {
+        throw new Error('every() duration must be a positive number of milliseconds');
+    }
+    const anchor = options?.anchor;
+    if (anchor !== undefined && !Number.isFinite(anchor)) {
+        throw new Error('every() anchor must be a finite epoch timestamp');
+    }
+    return anchor === undefined ? { type: 'every', everyMs } : { type: 'every', everyMs, anchor };
+}
+/** One fire at an absolute epoch millisecond. */
+export function once(at) {
+    if (!Number.isFinite(at)) {
+        throw new Error('once() at must be a finite epoch timestamp');
+    }
+    return { type: 'once', at };
+}
+/**
+ * The first fire strictly after `after`. Invalid specs and an exhausted `once` return null.
+ * This is pure: it does not read the clock.
+ */
+export function nextFireAt(spec, after) {
+    switch (spec.type) {
+        case 'cron':
+            return nextCronAt(spec, after);
+        case 'every':
+            return nextEveryAt(spec, after);
+        case 'once':
+            return spec.at > after ? spec.at : null;
+        default: {
+            const unexpected = spec;
+            return unexpected;
+        }
+    }
+}
+/** A short label for the debugger and logs. */
+export function describeSpec(spec) {
+    switch (spec.type) {
+        case 'cron':
+            return spec.tz === undefined ? spec.expr : `${spec.expr} (${spec.tz})`;
+        case 'every':
+            return `every ${formatDuration(spec.everyMs)}`;
+        case 'once':
+            return `once at ${spec.at}`;
+        default: {
+            const unexpected = spec;
+            return unexpected;
+        }
+    }
+}
+/**
+ * Why `spec` cannot be armed, or undefined when it is allowed.
+ * `once` has no gap. A gap equal to `minIntervalMs` is allowed.
+ */
+export function specRejection(spec, minIntervalMs) {
+    switch (spec.type) {
+        case 'cron': {
+            const parsed = parseCron(spec);
+            if (Result.isFailure(parsed)) {
+                return `invalid cron expression "${spec.expr}"`;
+            }
+            return gapRejection(smallestCronGap(parsed.success, minIntervalMs), minIntervalMs, spec.expr);
+        }
+        case 'every': {
+            if (!Number.isFinite(spec.everyMs) || spec.everyMs <= 0) {
+                return 'every() duration must be a positive number of milliseconds';
+            }
+            if (spec.anchor !== undefined && !Number.isFinite(spec.anchor)) {
+                return 'every() anchor must be a finite epoch timestamp';
+            }
+            return gapRejection(spec.everyMs, minIntervalMs, describeSpec(spec));
+        }
+        case 'once':
+            return Number.isFinite(spec.at) ? undefined : 'once() at must be a finite epoch timestamp';
+        default: {
+            const unexpected = spec;
+            return unexpected;
+        }
+    }
+}
+function gapRejection(gapMs, minIntervalMs, label) {
+    if (minIntervalMs <= 0 || gapMs >= minIntervalMs) {
+        return undefined;
+    }
+    return `schedule "${label}" repeats every ${gapMs}ms, below the minimum ${minIntervalMs}ms`;
+}
+function parseCron(spec) {
+    return Cron.parse(spec.expr, spec.tz ?? 'UTC');
+}
+function nextCronAt(spec, after) {
+    const parsed = parseCron(spec);
+    if (Result.isFailure(parsed)) {
+        return null;
+    }
+    try {
+        return Cron.next(parsed.success, after).getTime();
+    }
+    catch {
+        return null;
+    }
+}
+function nextEveryAt(spec, after) {
+    if (!Number.isFinite(spec.everyMs) || spec.everyMs <= 0) {
+        return null;
+    }
+    const anchor = spec.anchor ?? 0;
+    if (after < anchor) {
+        return anchor;
+    }
+    const steps = Math.floor((after - anchor) / spec.everyMs) + 1;
+    return anchor + steps * spec.everyMs;
+}
+function smallestCronGap(parsed, minIntervalMs) {
+    if (parsed.seconds.size === 1 && minIntervalMs <= DEFAULT_MIN_INTERVAL_MS) {
+        return DEFAULT_MIN_INTERVAL_MS;
+    }
+    let smallest = Number.POSITIVE_INFINITY;
+    if (parsed.seconds.size > 1) {
+        const seconds = [...parsed.seconds].toSorted((a, b) => a - b);
+        for (let index = 1; index < seconds.length; index += 1) {
+            const current = seconds[index];
+            const prev = seconds[index - 1];
+            if (current !== undefined && prev !== undefined) {
+                smallest = Math.min(smallest, (current - prev) * 1_000);
+            }
+        }
+        if (smallest < minIntervalMs) {
+            return smallest;
+        }
+    }
+    for (const start of GAP_SAMPLE_STARTS) {
+        let cursor = start;
+        let previous;
+        for (let index = 0; index < GAP_SAMPLE_COUNT; index += 1) {
+            let next;
+            try {
+                next = Cron.next(parsed, cursor).getTime();
+            }
+            catch {
+                return 0;
+            }
+            if (previous !== undefined) {
+                smallest = Math.min(smallest, next - previous);
+            }
+            previous = next;
+            cursor = next;
+        }
+    }
+    return smallest;
+}
+function parseDuration(duration) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(duration.trim());
+    const amount = match?.[1];
+    const unit = match?.[2];
+    if (amount === undefined || unit === undefined) {
+        throw new Error(`every() duration "${duration}" must be a number of milliseconds or a string like "15m"`);
+    }
+    const multiplier = durationUnitMs(unit);
+    if (multiplier === undefined) {
+        throw new Error(`every() duration "${duration}" must be a number of milliseconds or a string like "15m"`);
+    }
+    return Number(amount) * multiplier;
+}
+function isMilliseconds(duration) {
+    return Number.isFinite(duration);
+}
+function durationUnitMs(unit) {
+    switch (unit) {
+        case 'ms':
+        case 's':
+        case 'm':
+        case 'h':
+        case 'd':
+            return DURATION_UNITS[unit];
+        default:
+            return undefined;
+    }
+}
+function formatDuration(ms) {
+    if (ms % 86_400_000 === 0) {
+        return `${ms / 86_400_000}d`;
+    }
+    if (ms % 3_600_000 === 0) {
+        return `${ms / 3_600_000}h`;
+    }
+    if (ms % 60_000 === 0) {
+        return `${ms / 60_000}m`;
+    }
+    if (ms % 1_000 === 0) {
+        return `${ms / 1_000}s`;
+    }
+    return `${ms}ms`;
+}