Metrics and Compatibility

getEnergyMetrics

function getEnergyMetrics(state: EnergyState, now?: number): EnergyMetrics

Derive app-agnostic EnergyMetrics from the current state. now defaults to Date.now(); non-finite values fall back to Date.now(). State age is clamped to be non-negative. The result is frozen; recoveryHintMinutes is only present for levels 50, 25, and 0.

import { createEnergyEngine, getEnergyMetrics } from '@kumbatio/energy-system'

const engine = createEnergyEngine({ initialLevel: 50 })
const metrics = getEnergyMetrics(engine.getState())
metrics.expectedProductivityWindowMinutes // 45
metrics.sustainable                       // true
metrics.recoveryHintMinutes               // 10

Values per level

Level	expectedProductivityWindowMinutes	suggestedBreakIntervalMinutes	recommendedTaskComplexity	sustainable	recoveryHintMinutes
`100`	120	90	`complex`	false	-
`75`	90	60	`moderate`	true	-
`50`	45	45	`routine`	true	10
`25`	25	25	`simple`	true	20
`0`	0	0	`consumption`	false	30

Rest (0) has no break cadence: the user is already resting, so there is nothing to take a break from. suggestedBreakIntervalMinutes: 0 means "no breaks suggested".

Compatibility helpers

Bridges for systems that use non-native level values (e.g. a legacy 4-level model) while keeping the package's fixed 5-level model unchanged.

cycleDiscreteLevel

function cycleDiscreteLevel<TLevel extends number>(
  current: number,
  levels: readonly TLevel[],
  fallback: TLevel,
): TLevel

Cycle through any discrete numeric level list. Returns the element after current in levels (wrapping), or fallback when current is not in the list.

mapToNearestDiscreteLevel

function mapToNearestDiscreteLevel<TLevel extends number>(
  value: number,
  levels: readonly TLevel[],
  fallback: TLevel,
): TLevel

Map an arbitrary number to the nearest available discrete level. Returns fallback for an empty list or a non-finite value.

mapToNearestEnergyLevel

function mapToNearestEnergyLevel(value: number): EnergyLevel

Map any number to the closest native package energy level (100, 75, 50, 25, 0); falls back to 100 for non-finite input.

mapToNearestEnergyLevel(66) // 75
mapToNearestEnergyLevel(10) // 0

createExternalLevelCompatibility

function createExternalLevelCompatibility<TExternal extends number>(
  options: ExternalLevelCompatibilityOptions<TExternal>,
): ExternalLevelCompatibility<TExternal>

Build a compatibility bridge for systems that use non-native level values. Useful during migrations while keeping the native model unchanged. The returned object is frozen.

Validation - each throws an Error:

levels must be non-empty, all finite, and unique
fallbackLevel must be present in levels
every level in levels must have a toEnergyLevel mapping to a valid native level
fallbackEnergyLevel, when provided, must be a valid native level

ExternalLevelCompatibilityOptions

Prop

Type

ExternalLevelCompatibility

Prop

Type

import { createExternalLevelCompatibility } from '@kumbatio/energy-system'

const legacy = createExternalLevelCompatibility({
  levels: [100, 66, 33, 0],
  toEnergyLevel: { 100: 100, 66: 75, 33: 25, 0: 0 },
  fallbackLevel: 100,
})

legacy.toEnergyLevel(66)        // 75
legacy.fromEnergyLevel(50)      // 66 (closest mapped native level)
legacy.cycleExternalLevel(66)   // 33
legacy.cycleMappedEnergyLevel(66) // 25

Metrics and Compatibility

On this page