Deferral

Deferral ("snooze") is the "not now" primitive. Deferring an item is an energy statement: it declares insufficient capacity for it right now and names when it should resurface. Presets are pure (now: Date) => Date functions; the energy-aware strategy orders them so the default suggestion matches current capacity - low energy means longer deferrals, because items should resurface when capacity has plausibly recovered, not in an hour.

DEFERRAL_PRESET_IDS

const DEFERRAL_PRESET_IDS: Readonly<{
  inOneHour: 'in-1-hour'
  thisEvening: 'this-evening'
  tomorrowMorning: 'tomorrow-morning'
  nextWorkday: 'next-workday'
  nextMonday: 'next-monday'
}>

Stable preset ids, exported so configs/strategies can reference them.

DeferralPreset

A named deferral option.

/>

createDeferralPresets

function createDeferralPresets(options?: DeferralPresetOptions): readonly DeferralPreset[]

Build the standard deferral presets. Times are computed in local time - "tomorrow morning" means the user's morning. Throws for hours outside the integer range 0-23.

DeferralPresetOptions

/>

The five presets

import { createDeferralPresets, resolveDeferral, DEFERRAL_PRESET_IDS } from '@kumbatio/energy-system'

const presets = createDeferralPresets({ morningHour: 8 })
const resurfaceAt = resolveDeferral(presets, DEFERRAL_PRESET_IDS.tomorrowMorning)
// epoch ms for tomorrow 08:00 local time

resolveDeferral

function resolveDeferral(
  presets: readonly DeferralPreset[],
  presetId: string,
  now?: Date,   // default: new Date()
): number | null

Resolve a preset id to a resurface timestamp (epoch ms). Returns null for an unknown id - callers decide whether that is an error.

deferralStrategy

const deferralStrategy: AdaptationStrategy<DeferralConfig>

The energy-aware ordering strategy (name: 'deferral'). Resolve it directly or through the engine like any built-in strategy.

DeferralConfig

/>

Values per level