Molecule.dev

← All @molecule/* packages · App templates

@molecule/api-scheduler-default

Provider bond · scheduler · API (Node) · v1.0.1 · Apache-2.0

Default in-process task scheduler

npm install @molecule/api-scheduler-default

npm · Source on GitHub · Implements @molecule/api-scheduler

How it works

@molecule/api-scheduler-default is a provider bond on the API (Node) side: it implements the scheduler core interface (@molecule/api-scheduler) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { schedule, setProvider, start } from '@molecule/api-scheduler'
import { provider } from '@molecule/api-scheduler-default'

setProvider(provider)

schedule({
  name: 'cleanup',
  intervalMs: 60000,
  async handler() {
    // ...
  },
})

// REQUIRED: nothing runs until start() — scheduling alone does not execute
// tasks. Tasks scheduled after start() begin automatically (staggered).
start()

Works with: @molecule/api-bond, @molecule/api-scheduler

Reference

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Default in-process scheduler provider for molecule.dev.

Uses setInterval for periodic task execution with staggered startup to prevent thundering herd.

Quick Start

import { schedule, setProvider, start } from '@molecule/api-scheduler'
import { provider } from '@molecule/api-scheduler-default'

setProvider(provider)

schedule({
  name: 'cleanup',
  intervalMs: 60000,
  async handler() {
    // ...
  },
})

// REQUIRED: nothing runs until start() — scheduling alone does not execute
// tasks. Tasks scheduled after start() begin automatically (staggered).
start()

Type

provider

Installation

npm install @molecule/api-scheduler-default @molecule/api-bond @molecule/api-scheduler

API

Interfaces

DefaultSchedulerOptions

Configuration options for the default scheduler provider.

interface DefaultSchedulerOptions {
  /**
   * Stagger offset in milliseconds between task starts to prevent
   * thundering herd. Defaults to 2000.
   *
   * Each task's actual delay is `(index % currentEnabledTaskCount) * staggerMs`
   * — the index wraps at the current number of enabled tasks rather than
   * growing forever, so repeatedly calling `schedule()` at runtime (e.g. to
   * replace a task) never accrues an ever-larger startup delay. The worst
   * case is always `(enabledTaskCount - 1) * staggerMs`, whether the tasks
   * were all registered before `start()` or scheduled one at a time
   * afterward.
   */
  staggerMs?: number
}

Functions

createProvider(options)

Creates a default in-process scheduler provider.

function createProvider(options?: DefaultSchedulerOptions): SchedulerProvider
  • options — Configuration options.

Returns: A SchedulerProvider implementation.

Constants

provider

The provider implementation.

const provider: SchedulerProvider

Core Interface

Implements @molecule/api-scheduler interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-scheduler'
import { provider } from '@molecule/api-scheduler-default'

export function setupSchedulerDefault(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-scheduler ^1.0.1
  • @molecule/api-bond ^1.0.1

Runtime Dependencies

  • @molecule/api-bond
  • @molecule/api-scheduler