/** * Pure helper: enabled state-machine events → Jev `choice` questions object. * Use when you want raw `./evaluate` instead of `./choose-transition`. * * @param events - Event id → description map, or `{ id, description }[]`. * @param options.questionKey - Answer key (default `transition`). * @param options.instructions - Choice instructions override. * @returns `{ questions, criteria, eventIds }` for evaluate / callers. * * @example * import buildChoiceFromEvents from 'kody:@kentcdodds/jev/build-choice-from-events' * const { questions } = buildChoiceFromEvents({ * RETRY: 'Retry the failed step', * ESCALATE: 'Hand off to a human', * }) */ import type { ChoiceQuestion, Questions, TransitionEvents, } from './types.ts' export type { TransitionEvents, TransitionEventListItem } from './types.ts' export type BuildChoiceFromEventsOptions = { /** Named answer key in `questions` / `answers` (default `transition`). */ questionKey?: string /** Override choice instructions. */ instructions?: string } export type BuildChoiceFromEventsResult = { /** Ready for `evaluate({ questions })`. */ questions: Questions /** Normalized criteria map (event id → description). */ criteria: Record /** Ordered event ids. */ eventIds: string[] questionKey: string } const DEFAULT_QUESTION_KEY = 'transition' const DEFAULT_INSTRUCTIONS = 'Which enabled event should fire next to move toward the goal? Pick exactly one.' /** * Normalize event map or list into a stable criteria Record. * Empty descriptions fall back to the event id. */ export function normalizeTransitionEvents( events: TransitionEvents | null | undefined, ): Record { if (!events) return {} if (Array.isArray(events)) { const criteria: Record = {} for (const item of events) { if (!item || typeof item !== 'object') continue const id = typeof item.id === 'string' ? item.id.trim() : '' if (!id) continue const description = typeof item.description === 'string' && item.description.trim() ? item.description.trim() : id criteria[id] = description } return criteria } if (typeof events !== 'object') return {} const criteria: Record = {} for (const [id, description] of Object.entries(events)) { const key = typeof id === 'string' ? id.trim() : '' if (!key) continue criteria[key] = typeof description === 'string' && description.trim() ? description.trim() : key } return criteria } /** * Pure helper: enabled state-machine events → Jev `choice` questions object. * Use when you want raw `./evaluate` instead of `./choose-transition`. * * @param events - Event id → description map, or `{ id, description }[]`. * @param options.questionKey - Answer key (default `transition`). * @param options.instructions - Choice instructions override. * @returns `{ questions, criteria, eventIds }` for evaluate / callers. * * @example * import buildChoiceFromEvents from 'kody:@kentcdodds/jev/build-choice-from-events' * const { questions } = buildChoiceFromEvents({ * RETRY: 'Retry the failed step', * ESCALATE: 'Hand off to a human', * }) */ export default function buildChoiceFromEvents( events: TransitionEvents, options: BuildChoiceFromEventsOptions = {}, ): BuildChoiceFromEventsResult { const criteria = normalizeTransitionEvents(events) const eventIds = Object.keys(criteria) const questionKey = typeof options.questionKey === 'string' && options.questionKey.trim() ? options.questionKey.trim() : DEFAULT_QUESTION_KEY const instructions = typeof options.instructions === 'string' && options.instructions.trim() ? options.instructions.trim() : DEFAULT_INSTRUCTIONS const choice: ChoiceQuestion = { type: 'choice', instructions, criteria, } return { questions: { [questionKey]: choice }, criteria, eventIds, questionKey, } }