Skip to content
← Public packages

@kentcdodds/jev

Call TypeSafe Jev evaluations via Cloudflare AI Gateway (same token/gateway as @kentcdodds/ai).

FollowFork

Files

build-choice-from-events.ts

128 lines · 3.8 KB · TypeScript
/**
 * 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<string, string>
	/** 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<string, string> {
	if (!events) return {}

	if (Array.isArray(events)) {
		const criteria: Record<string, string> = {}
		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<string, string> = {}
	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,
	}
}