@skelm/scheduler

Long-running trigger management for skelm pipelines — cron, interval, and webhook triggers with deduplication and overlap policies.

Part of skelm.

The scheduler turns "run this once" into "run this whenever". It is the same code path used by @skelm/gateway to fire scheduled work, but exposed as a small standalone library so embedders can drive triggers without taking the full gateway dependency.

Install

npm install @skelm/scheduler

Quick Start

import { Scheduler, createCronTrigger, createWebhookTrigger } from '@skelm/scheduler'

const scheduler = new Scheduler({ maxConcurrentRuns: 8 })

scheduler.register(
  createCronTrigger({ id: 'nightly-digest', schedule: '0 9 * * 1-5' }),
  async (ctx) => {
    // run a pipeline, post results, etc.
  },
)

scheduler.register(
  createWebhookTrigger({ id: 'issue-events', path: '/webhooks/issue-events' }),
  async (ctx) => { /* ... */ },
)

await scheduler.start()

Trigger types

| Builder | When it fires | | ------------------------ | --------------------------------------------------------- | | createCronTrigger | On a cron schedule ('0 9 * * 1-5') | | createIntervalTrigger | Every N milliseconds | | createWebhookTrigger | When the gateway receives a request at the trigger's path |

Policies

• Deduplication — provide a dedupeKey(ctx); the scheduler suppresses duplicate firings within a configurable window.
• Overlap — choose what happens when a trigger fires while a previous run is still in flight: skip, queue, or parallel.
• Retry / backoff — handled at the pipeline runner layer; the scheduler treats every firing as a fresh request.

Metadata

Each TriggerRegistration records baseline operator metadata: runCount, errorCount, lastRunAt, lastError, and lastErrorAt. It also reports scheduling/runtime state through nextRunAt, runningCount, and lastOutcome (dispatched, skipped, succeeded, or failed). Invalid cron expressions and invalid interval durations move the registration to status: 'error' instead of arming a timer. Intervals must be finite and within Node's supported timer range (1..2147483647 ms).

Public exports

export { Scheduler } from './scheduler.js'
export {
  createCronTrigger, createIntervalTrigger, createWebhookTrigger,
} from './builders.js'
export type {
  SchedulerConfig, Trigger, TriggerRegistration, TriggerContext, TriggerType,
  DedupePolicy, OverlapPolicy, TriggerBase,
  CronTrigger, IntervalTrigger, WebhookTrigger,
  TriggerOptions,
} from './types.js'

Stability

0.x — APIs may change between minor versions until v1.

License

MIT