[V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import type { PollSnapshot, MockPollSnapshot, PollLogEvent, } from "@/app/api/mock/store"; import { PollerCodeWorkbench } from "./poller-code-workbench"; type LifecycleState = "idle" | "running" | "completed" | "timeout"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type StartResponse = { runId: string; status: "running" | "completed" | "timeout"; snapshot: MockPollSnapshot; }; type PollerWorkflowLineMap = { poll: number[]; sleep: number[]; successReturn: number[]; timeoutReturn: number[]; }; type PollerStepLineMap = { poll: number[]; successReturn: number[]; }; type StatusPollerDemoProps = { workflowCode: string; workflowHtmlLines: string[]; workflowLineMap: PollerWorkflowLineMap; stepCode: string; stepHtmlLines: string[]; stepLineMap: PollerStepLineMap; }; const POLL_INTERVAL_MS = 120; const MAX_POLLS = 8; const INTERVAL_MS = 1_000; const DEFAULT_READY_AT_POLL = 4; const READY_AT_MIN = 1; const READY_AT_MAX = MAX_POLLS; const READY_AT_OPTIONS = Array.from( { length: READY_AT_MAX - READY_AT_MIN + 1 }, (_, index) => READY_AT_MIN + index ); function buildJobId(): string { return `job_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`; } function formatDurationLabel(durationMs: number): string { if (durationMs >= 1000 && durationMs % 1000 === 0) { return `${durationMs / 1000}s`; } return `${durationMs}ms`; } function formatElapsedLabel(durationMs: number): string { const seconds = (durationMs / 1000).toFixed(2); return `${seconds}s`; } async function postJson( url: string, body: Record, signal: AbortSignal ): Promise { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(body), signal, }); const payload = (await response .json() .catch(() => ({ error: "Failed to parse JSON response" }))) as | T | { error?: string }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = typeof payload === "object" && payload && "error" in payload ? (payload.error ?? `Request failed (${response.status})`) : `Request failed (${response.status})`; throw new Error(message); } return payload as T; } export function StatusPollerDemo({ workflowCode, workflowHtmlLines, workflowLineMap, stepCode, stepHtmlLines, stepLineMap, }: StatusPollerDemoProps) { const [readyAtPoll, setReadyAtPoll] = useState(DEFAULT_READY_AT_POLL); const [lifecycle, setLifecycle] = useState("idle"); const [runId, setRunId] = useState(null); const [snapshot, setSnapshot] = useState(null); const [error, setError] = useState(null); const pollTimerRef = useRef | null>(null); const inFlightRef = useRef(false); const abortRef = useRef(null); const startButtonRef = useRef(null); const stopPolling = useCallback(() => { if (pollTimerRef.current) { clearInterval(pollTimerRef.current); pollTimerRef.current = null; } inFlightRef.current = false; }, []); const ensureAbortController = useCallback((): AbortController => { if (!abortRef.current || abortRef.current.signal.aborted) { abortRef.current = new AbortController(); } return abortRef.current; }, []); useEffect(() => { return () => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; }; }, [stopPolling]); const fetchStatusSnapshot = useCallback(async (targetRunId: string, signal: AbortSignal) => { const response = await fetch( `/api/mock/status?runId=${encodeURIComponent(targetRunId)}`, { cache: "no-store", signal, } ); const payload = (await response .json() .catch(() => ({ error: "Failed to parse status response" }))) as | MockPollSnapshot | { error?: string }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = typeof payload === "object" && payload && "error" in payload ? payload.error ?? `Status request failed (${response.status})` : `Status request failed (${response.status})`; throw new Error(message); } return payload as MockPollSnapshot; }, []); const beginPolling = useCallback( (targetRunId: string) => { stopPolling(); const poll = async () => { if (inFlightRef.current) { return; } inFlightRef.current = true; let signal: AbortSignal | null = null; try { const controller = ensureAbortController(); signal = controller.signal; const nextSnapshot = await fetchStatusSnapshot(targetRunId, signal); if (signal.aborted) { return; } setSnapshot(nextSnapshot); if (nextSnapshot.status === "completed") { if (signal.aborted) { return; } setLifecycle("completed"); stopPolling(); return; } if (nextSnapshot.status === "timeout") { if (signal.aborted) { return; } setLifecycle("timeout"); stopPolling(); return; } if (signal.aborted) { return; } setLifecycle("running"); } catch (pollError) { if ((signal && signal.aborted) || (pollError instanceof Error && pollError.name === "AbortError")) { return; } stopPolling(); setLifecycle("timeout"); const message = pollError instanceof Error ? pollError.message : "Failed to read poll status"; setError(message); } finally { inFlightRef.current = false; } }; void poll(); pollTimerRef.current = setInterval(() => { void poll(); }, POLL_INTERVAL_MS); }, [ensureAbortController, fetchStatusSnapshot, stopPolling] ); const hasScrolledRef = useRef(false); useEffect(() => { if (lifecycle !== "idle" && !hasScrolledRef.current) { hasScrolledRef.current = true; const heading = document.getElementById("try-it-heading"); if (heading) { const top = heading.getBoundingClientRect().top + window.scrollY; window.scrollTo({ top, behavior: "smooth" }); } } if (lifecycle === "idle") { hasScrolledRef.current = false; } }, [lifecycle]); const handleStart = useCallback(async () => { setError(null); stopPolling(); abortRef.current?.abort(); abortRef.current = null; const controller = ensureAbortController(); const signal = controller.signal; try { const payload = await postJson("/api/mock/start", { jobId: buildJobId(), maxPolls: MAX_POLLS, readyAtPoll, intervalMs: INTERVAL_MS, }, signal); if (signal.aborted) { return; } setRunId(payload.runId); if (signal.aborted) { return; } setSnapshot(payload.snapshot); if (signal.aborted) { return; } setLifecycle(payload.status === "running" ? "running" : payload.status); if (payload.status === "running") { if (signal.aborted) { return; } beginPolling(payload.runId); } } catch (startError) { if (signal.aborted || (startError instanceof Error && startError.name === "AbortError")) { return; } const message = startError instanceof Error ? startError.message : "Failed to start mock poll run"; setError(message); setLifecycle("idle"); } }, [beginPolling, ensureAbortController, readyAtPoll, stopPolling]); const handleReset = useCallback(() => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; setLifecycle("idle"); setRunId(null); setSnapshot(null); setError(null); setTimeout(() => { startButtonRef.current?.focus(); }, 0); }, [stopPolling]); const isRunning = lifecycle === "running"; const phaseExplainer = useMemo(() => { if (!snapshot) { return "Waiting to start a run."; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "poll") { return `Poll ${snapshot.currentPhase.poll} is executing checkTranscodeJob() in a step.`; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "sleep") { return `sleep('${formatDurationLabel(snapshot.currentPhase.nextDelayMs ?? 0)}') in progress. The workflow is durably suspended and consuming zero compute.`; } if (snapshot.status === "completed") { return `Job ready on poll ${snapshot.result?.poll}. Transcoding complete.`; } if (snapshot.status === "timeout") { return `Timed out after poll ${snapshot.result?.poll}. Max polls exhausted.`; } return "Run is active."; }, [snapshot]); type GutterMarkKind = "success" | "fail"; const codeState = useMemo(() => { const wfMarks: Record = {}; const stepMarks: Record = {}; if (snapshot) { const lastReady = [...snapshot.executionLog].reverse().find((e) => e.kind === "ready"); let lastProcessingIdx = -1; let lastPollIdx = -1; for (let i = snapshot.executionLog.length - 1; i >= 0; i--) { if (lastProcessingIdx === -1 && snapshot.executionLog[i].kind === "processing") lastProcessingIdx = i; if (lastPollIdx === -1 && snapshot.executionLog[i].kind === "poll") lastPollIdx = i; if (lastProcessingIdx !== -1 && lastPollIdx !== -1) break; } if (lastReady) { for (const ln of workflowLineMap.poll) wfMarks[ln] = "success"; for (const ln of stepLineMap.poll) stepMarks[ln] = "success"; } else if (lastProcessingIdx > lastPollIdx) { for (const ln of workflowLineMap.poll) wfMarks[ln] = "fail"; for (const ln of stepLineMap.poll) stepMarks[ln] = "fail"; } const hasSlept = snapshot.executionLog.some( (e) => e.kind === "sleep" || e.kind === "wakeup" ); if (hasSlept) { for (const ln of workflowLineMap.sleep) wfMarks[ln] = "success"; } if (snapshot.status === "completed") { for (const ln of workflowLineMap.successReturn) wfMarks[ln] = "success"; for (const ln of stepLineMap.successReturn) stepMarks[ln] = "success"; } if (snapshot.status === "timeout") { for (const ln of workflowLineMap.timeoutReturn) wfMarks[ln] = "fail"; } } if (!snapshot) { return { tone: "amber" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "poll") { return { tone: "amber" as HighlightTone, workflowActiveLines: workflowLineMap.poll, stepActiveLines: stepLineMap.poll, workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "sleep") { return { tone: "cyan" as HighlightTone, workflowActiveLines: workflowLineMap.sleep, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "completed") { return { tone: "green" as HighlightTone, workflowActiveLines: workflowLineMap.successReturn, stepActiveLines: stepLineMap.successReturn, workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } return { tone: "red" as HighlightTone, workflowActiveLines: workflowLineMap.timeoutReturn, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; }, [snapshot, stepLineMap, workflowLineMap]); return (

{error && (

{error}

)}

{lifecycle !== "idle" && ( )} Ready at poll

{phaseExplainer}

{runId && ( run: {runId} )}

sleep() → durable polling interval with zero compute between checks

); } function PollLadder({ polls, currentPhase, }: { polls: PollSnapshot[]; currentPhase: MockPollSnapshot["currentPhase"]["phase"] | null; }) { if (polls.length === 0) { return (

No polls yet.

); } return (

{polls.map((poll) => { const statusTone = pollTone(poll.state); const sleepLabel = poll.sleepMs > 0 ? formatDurationLabel(poll.sleepMs) : "none"; const remainingLabel = poll.state === "sleeping" && poll.remainingSleepMs > 0 ? ` (${formatDurationLabel(poll.remainingSleepMs)} left)` : ""; return (

); })}

); } function ExecutionLog({ events, elapsedMs, }: { events: PollLogEvent[]; elapsedMs: number; }) { const scrollRef = useRef(null); useEffect(() => { const el = scrollRef.current; if (el) { el.scrollTop = el.scrollHeight; } }, [events.length]); return (

Execution log

{formatElapsedLabel(elapsedMs)}

{events.length === 0 && (

No events yet.

)} {events.map((event, index) => { const tone = eventTone(event.kind); return (

); })}

); } function pollTone(state: PollSnapshot["state"]): { dotClass: string; badgeClass: string; cardClass: string; } { switch (state) { case "running": return { dotClass: "bg-amber-700 animate-pulse", badgeClass: "border-amber-700/40 bg-amber-700/10 text-amber-700", cardClass: "border-amber-700/40 bg-amber-700/10", }; case "sleeping": return { dotClass: "bg-cyan-700 animate-pulse", badgeClass: "border-cyan-700/40 bg-cyan-700/10 text-cyan-700", cardClass: "border-cyan-700/40 bg-cyan-700/10", }; case "not_ready": return { dotClass: "bg-red-700", badgeClass: "border-red-700/40 bg-red-700/10 text-red-700", cardClass: "border-red-700/40 bg-red-700/10", }; case "ready": return { dotClass: "bg-green-700", badgeClass: "border-green-700/40 bg-green-700/10 text-green-700", cardClass: "border-green-700/40 bg-green-700/10", }; case "pending": default: return { dotClass: "bg-gray-500", badgeClass: "border-gray-400/70 bg-background-100 text-gray-900", cardClass: "border-gray-400/40 bg-background-100", }; } } function eventTone(kind: PollLogEvent["kind"]): { dotClass: string; labelClass: string; } { switch (kind) { case "poll": return { dotClass: "bg-blue-700", labelClass: "text-blue-700", }; case "processing": return { dotClass: "bg-red-700", labelClass: "text-red-700", }; case "sleep": return { dotClass: "bg-cyan-700", labelClass: "text-cyan-700", }; case "wakeup": return { dotClass: "bg-amber-700", labelClass: "text-amber-700", }; case "ready": return { dotClass: "bg-green-700", labelClass: "text-green-700", }; case "timeout": return { dotClass: "bg-red-700", labelClass: "text-red-700", }; default: return { dotClass: "bg-gray-500", labelClass: "text-gray-900", }; } } [V0_FILE]typescript:file="app/components/code-highlight-server.ts" import { highlight } from "sugar-high"; export function highlightCodeToHtmlLines(code: string): string[] { return highlight(code).split("\n"); } [V0_FILE]typescriptreact:file="app/components/poller-code-workbench.tsx" "use client"; import { useEffect, useMemo, useRef, useState } from "react"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type CopyState = "idle" | "copied" | "failed"; type HighlightStyle = { border: string; bg: string; text: string; }; const HIGHLIGHT_STYLES: Record = { amber: { border: "border-amber-700", bg: "bg-amber-700/15", text: "text-amber-700", }, cyan: { border: "border-cyan-700", bg: "bg-cyan-700/15", text: "text-cyan-700", }, green: { border: "border-green-700", bg: "bg-green-700/15", text: "text-green-700", }, red: { border: "border-red-700", bg: "bg-red-700/15", text: "text-red-700", }, }; const CHECKMARK_POINTS = "3,8.5 7,12.5 14,4.5"; type GutterMarkKind = "success" | "fail"; type CodePaneProps = { code: string; htmlLines: string[]; activeLines: number[]; gutterMarks: Record; filename: string; subtitle: string; tone: HighlightTone; }; function CodePane({ code, htmlLines, activeLines, gutterMarks, filename, subtitle, tone, }: CodePaneProps) { const [copyState, setCopyState] = useState("idle"); const activeLineSet = useMemo(() => new Set(activeLines), [activeLines]); const gutterMarkMap = useMemo(() => new Map(Object.entries(gutterMarks).map(([k, v]) => [Number(k), v])), [gutterMarks]); const prevMarkRef = useRef>(new Map()); const isFullReset = gutterMarkMap.size === 0 && activeLines.length === 0; useEffect(() => { if (isFullReset) { prevMarkRef.current.clear(); return; } gutterMarkMap.forEach((kind, line) => { prevMarkRef.current.set(line, kind); }); }, [gutterMarkMap, isFullReset]); const highlightStyle = HIGHLIGHT_STYLES[tone]; const handleCopy = async () => { try { await navigator.clipboard.writeText(code); setCopyState("copied"); window.setTimeout(() => setCopyState("idle"), 1200); } catch { setCopyState("failed"); window.setTimeout(() => setCopyState("idle"), 1200); } }; return (

{filename}

{subtitle}

          
            {htmlLines.map((lineHtml, index) => {
              const lineNumber = index + 1;
              const isActive = activeLineSet.has(lineNumber);
              const markKind = gutterMarkMap.get(lineNumber);
              const displayKind = isFullReset
                ? undefined
                : markKind ?? prevMarkRef.current.get(lineNumber);

              return (
                
                  
                    
                  
                  
                    {lineNumber}
                  
                   0 ? lineHtml : " ",
                    }}
                  />
                
              );
            })}

); } export type PollerCodeWorkbenchProps = { workflowCode: string; workflowHtmlLines: string[]; workflowActiveLines: number[]; workflowGutterMarks: Record; stepCode: string; stepHtmlLines: string[]; stepActiveLines: number[]; stepGutterMarks: Record; tone: HighlightTone; }; export function PollerCodeWorkbench({ workflowCode, workflowHtmlLines, workflowActiveLines, workflowGutterMarks, stepCode, stepHtmlLines, stepActiveLines, stepGutterMarks, tone, }: PollerCodeWorkbenchProps) { return (

); } [V0_FILE]typescriptreact:file="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Status Poller - Workflow DevKit Example", description: "Demonstrates durable status polling with sleep() in Workflow DevKit", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( Skip to main content {children} ); } [V0_FILE]typescript:file="app/api/mock/start/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockPollSnapshot, createMockPollRun, } from "../store"; type StartRequestBody = { jobId?: unknown; maxPolls?: unknown; readyAtPoll?: unknown; intervalMs?: unknown; }; const DEFAULT_JOB_ID = "job_transcode_001"; const DEFAULT_MAX_POLLS = 8; const DEFAULT_READY_AT_POLL = 4; const DEFAULT_INTERVAL_MS = 1_000; function generateRunId(): string { return `poll_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`; } function parseBoundedInteger(input: { field: string; value: unknown; min: number; max: number; fallback: number; }): { value: number } | { error: string } { if (input.value === undefined) { return { value: input.fallback }; } if ( typeof input.value !== "number" || !Number.isFinite(input.value) || !Number.isInteger(input.value) ) { return { error: `${input.field} must be an integer between ${input.min} and ${input.max}`, }; } if (input.value < input.min || input.value > input.max) { return { error: `${input.field} must be between ${input.min} and ${input.max}`, }; } return { value: input.value }; } function parseJobId(value: unknown): { value: string } | { error: string } { if (value === undefined) { return { value: DEFAULT_JOB_ID }; } if (typeof value !== "string") { return { error: "jobId must be a string" }; } const normalized = value.trim(); if (!normalized) { return { error: "jobId cannot be empty" }; } return { value: normalized }; } function validationErrorResponse( attempted: string, reason: string, body: StartRequestBody ): Response { console.warn("[mock-status-poller] start_validation_failed", { attempted, reason, body, }); return createApiErrorResponse( { code: "INVALID_REQUEST", message: reason, }, { status: 400 } ); } export async function POST(request: Request): Promise { let body: StartRequestBody; try { body = (await request.json()) as StartRequestBody; } catch { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body", }, { status: 400 } ); } const jobIdResult = parseJobId(body.jobId); if ("error" in jobIdResult) { return validationErrorResponse( "validate_job_id", jobIdResult.error, body ); } const maxPollsResult = parseBoundedInteger({ field: "maxPolls", value: body.maxPolls, min: 1, max: 20, fallback: DEFAULT_MAX_POLLS, }); if ("error" in maxPollsResult) { return validationErrorResponse( "validate_max_polls", maxPollsResult.error, body ); } const readyAtPollResult = parseBoundedInteger({ field: "readyAtPoll", value: body.readyAtPoll, min: 1, max: 20, fallback: DEFAULT_READY_AT_POLL, }); if ("error" in readyAtPollResult) { return validationErrorResponse( "validate_ready_at_poll", readyAtPollResult.error, body ); } const intervalMsResult = parseBoundedInteger({ field: "intervalMs", value: body.intervalMs, min: 100, max: 5_000, fallback: DEFAULT_INTERVAL_MS, }); if ("error" in intervalMsResult) { return validationErrorResponse( "validate_interval_ms", intervalMsResult.error, body ); } const run = createMockPollRun({ runId: generateRunId(), jobId: jobIdResult.value, maxPolls: maxPollsResult.value, readyAtPoll: readyAtPollResult.value, intervalMs: intervalMsResult.value, }); const snapshot = buildMockPollSnapshot(run, run.startedAtMs); return createApiSuccessResponse({ runId: run.id, jobId: run.jobId, status: snapshot.status, maxPolls: run.maxPolls, readyAtPoll: run.readyAtPoll, intervalMs: run.intervalMs, snapshot: { ...snapshot }, }); } [V0_FILE]typescript:file="app/api/mock/api.ts" import { NextResponse } from "next/server"; type ApiError = { code: string; message: string; }; export function createApiSuccessResponse>( fields: T, init?: ResponseInit ) { return NextResponse.json( { ok: true, ...fields, }, init ); } export function createApiErrorResponse(error: ApiError, init?: ResponseInit) { return NextResponse.json( { ok: false, error, }, init ); } [V0_FILE]typescript:file="app/api/mock/status/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockPollSnapshot, getMockPollRun } from "../store"; export async function GET(request: Request): Promise { const searchParams = new URL(request.url).searchParams; const runId = searchParams.get("runId"); if (!runId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "runId is required", }, { status: 400 } ); } const run = getMockPollRun(runId); if (!run) { console.warn("[mock-status-poller] status_lookup_failed", { attempted: "mock_poll_status_lookup", reason: "run_not_found", runId, }); return createApiErrorResponse( { code: "NOT_FOUND", message: "Run not found", }, { status: 404 } ); } return createApiSuccessResponse({ ...buildMockPollSnapshot(run) }); } [V0_FILE]typescript:file="app/api/mock/store.ts" export const POLL_WORK_MS = 500; export type MockRunStatus = "running" | "completed" | "timeout"; export type PollOutcome = "not_ready" | "ready"; export type PollRuntimeState = | "pending" | "running" | "not_ready" | "ready" | "sleeping"; export type PollPhaseKind = "poll" | "sleep" | "done"; export type JobState = "queued" | "processing" | "encoding" | "finalizing" | "ready"; const JOB_STATE_SEQUENCE: JobState[] = [ "queued", "processing", "encoding", "finalizing", "ready", ]; export interface PollPlan { poll: number; startMs: number; endMs: number; sleepMs: number; outcome: PollOutcome; jobState: JobState; } export interface MockPollRun { id: string; jobId: string; maxPolls: number; readyAtPoll: number; intervalMs: number; startedAt: string; startedAtMs: number; status: MockRunStatus; plan: PollPlan[]; } export interface PollSnapshot extends PollPlan { state: PollRuntimeState; sleepEndMs: number; remainingSleepMs: number; } export interface PollPhase { phase: PollPhaseKind; poll: number | null; nextDelayMs: number | null; } export type PollLogEventKind = | "poll" | "processing" | "sleep" | "wakeup" | "ready" | "timeout"; export interface PollLogEvent { atMs: number; poll: number; kind: PollLogEventKind; message: string; } export interface MockPollSnapshot { runId: string; jobId: string; status: MockRunStatus; maxPolls: number; readyAtPoll: number; intervalMs: number; pollWorkMs: number; startedAt: string; startedAtMs: number; elapsedMs: number; totalDurationMs: number; polls: PollSnapshot[]; currentPhase: PollPhase; executionLog: PollLogEvent[]; result: | { poll: number; outcome: "ready" | "timeout"; } | null; } declare global { // eslint-disable-next-line no-var var __mockStatusPollerRuns: Map | undefined; } function toIso(timestampMs: number): string { return new Date(timestampMs).toISOString(); } export function getRunStore(): Map { return ( globalThis.__mockStatusPollerRuns ?? (globalThis.__mockStatusPollerRuns = new Map()) ); } function jobStateForPoll(poll: number, readyAtPoll: number): JobState { if (poll >= readyAtPoll) { return "ready"; } // Distribute intermediate states across polls before ready const statesBeforeReady = JOB_STATE_SEQUENCE.slice(0, -1); // exclude "ready" const idx = Math.min(poll - 1, statesBeforeReady.length - 1); return statesBeforeReady[idx]; } function runStatusTransition( run: MockPollRun, nextStatus: MockRunStatus, reason: string, context: Record ): void { if (run.status === nextStatus) { return; } console.info("[mock-status-poller] run_status_transition", { runId: run.id, from: run.status, to: nextStatus, reason, ...context, }); run.status = nextStatus; } export function buildPollPlan(input: { maxPolls: number; readyAtPoll: number; intervalMs: number; }): PollPlan[] { const { maxPolls, readyAtPoll, intervalMs } = input; const plan: PollPlan[] = []; let cursorMs = 0; const effectiveReadyPoll = readyAtPoll <= maxPolls ? readyAtPoll : null; for (let poll = 1; poll <= maxPolls; poll += 1) { const startMs = cursorMs; const endMs = startMs + POLL_WORK_MS; const state = jobStateForPoll(poll, effectiveReadyPoll ?? maxPolls + 1); const outcome: PollOutcome = state === "ready" ? "ready" : "not_ready"; const hasNextPoll = poll < maxPolls && outcome === "not_ready"; const sleepMs = hasNextPoll ? intervalMs : 0; plan.push({ poll, startMs, endMs, sleepMs, outcome, jobState: state, }); cursorMs = endMs + sleepMs; if (outcome === "ready") { break; } } return plan; } export function createMockPollRun(input: { runId: string; jobId: string; maxPolls: number; readyAtPoll: number; intervalMs: number; nowMs?: number; }): MockPollRun { const nowMs = input.nowMs ?? Date.now(); const run: MockPollRun = { id: input.runId, jobId: input.jobId, maxPolls: input.maxPolls, readyAtPoll: input.readyAtPoll, intervalMs: input.intervalMs, startedAt: toIso(nowMs), startedAtMs: nowMs, status: "running", plan: buildPollPlan({ maxPolls: input.maxPolls, readyAtPoll: input.readyAtPoll, intervalMs: input.intervalMs, }), }; console.info("[mock-status-poller] run_created", { runId: run.id, jobId: run.jobId, maxPolls: run.maxPolls, readyAtPoll: run.readyAtPoll, intervalMs: run.intervalMs, planLength: run.plan.length, totalDurationMs: run.plan.at(-1)?.endMs ?? 0, }); getRunStore().set(run.id, run); return run; } export function getMockPollRun(runId: string): MockPollRun | undefined { return getRunStore().get(runId); } function buildExecutionTimeline(plan: PollPlan[]): PollLogEvent[] { const events: PollLogEvent[] = []; for (const entry of plan) { events.push({ atMs: entry.startMs, poll: entry.poll, kind: "poll", message: `Poll ${entry.poll} started`, }); if (entry.outcome === "ready") { events.push({ atMs: entry.endMs, poll: entry.poll, kind: "ready", message: `Poll ${entry.poll}: job is ready (${entry.jobState})`, }); continue; } events.push({ atMs: entry.endMs, poll: entry.poll, kind: "processing", message: `Poll ${entry.poll}: still ${entry.jobState}`, }); if (entry.sleepMs > 0) { events.push({ atMs: entry.endMs, poll: entry.poll, kind: "sleep", message: `sleep("${entry.sleepMs}ms") started`, }); events.push({ atMs: entry.endMs + entry.sleepMs, poll: entry.poll, kind: "wakeup", message: `Woke up after ${entry.sleepMs}ms`, }); } } const finalPoll = plan.at(-1); if (finalPoll && finalPoll.outcome === "not_ready") { events.push({ atMs: finalPoll.endMs, poll: finalPoll.poll, kind: "timeout", message: `Max polls exhausted (${finalPoll.poll})`, }); } return events.sort((left, right) => left.atMs - right.atMs); } export function buildMockPollSnapshot( run: MockPollRun, nowMs: number = Date.now() ): MockPollSnapshot { const elapsedMs = Math.max(0, nowMs - run.startedAtMs); const polls: PollSnapshot[] = run.plan.map((entry) => ({ ...entry, state: "pending", sleepEndMs: entry.endMs + entry.sleepMs, remainingSleepMs: 0, })); let status: MockRunStatus = "running"; let currentPhase: PollPhase = { phase: "done", poll: null, nextDelayMs: null, }; let result: MockPollSnapshot["result"] = null; for (let index = 0; index < polls.length; index += 1) { const poll = polls[index]; if (elapsedMs < poll.endMs) { poll.state = "running"; currentPhase = { phase: "poll", poll: poll.poll, nextDelayMs: poll.sleepMs > 0 ? poll.sleepMs : null, }; break; } if (poll.outcome === "ready") { poll.state = "ready"; status = "completed"; currentPhase = { phase: "done", poll: poll.poll, nextDelayMs: null, }; result = { poll: poll.poll, outcome: "ready" }; break; } if (poll.sleepMs > 0 && elapsedMs < poll.sleepEndMs) { poll.state = "sleeping"; poll.remainingSleepMs = Math.max(0, poll.sleepEndMs - elapsedMs); currentPhase = { phase: "sleep", poll: poll.poll, nextDelayMs: poll.sleepMs, }; break; } poll.state = "not_ready"; if (index === polls.length - 1) { status = "timeout"; currentPhase = { phase: "done", poll: poll.poll, nextDelayMs: null, }; result = { poll: poll.poll, outcome: "timeout" }; break; } } runStatusTransition(run, status, "snapshot_recomputed", { elapsedMs, currentPhase, }); return { runId: run.id, jobId: run.jobId, status, maxPolls: run.maxPolls, readyAtPoll: run.readyAtPoll, intervalMs: run.intervalMs, pollWorkMs: POLL_WORK_MS, startedAt: run.startedAt, startedAtMs: run.startedAtMs, elapsedMs, totalDurationMs: run.plan.at(-1)?.endMs ?? 0, polls, currentPhase, executionLog: buildExecutionTimeline(run.plan).filter( (event) => event.atMs <= elapsedMs ), result, }; } [V0_FILE]typescriptreact:file="app/page.tsx" import { highlightCodeToHtmlLines } from "./components/code-highlight-server"; import { StatusPollerDemo } from "./components/demo"; const directiveUseWorkflow = `"use ${"workflow"}"`; const directiveUseStep = `"use ${"step"}"`; const workflowCode = `import { sleep } from "workflow"; export async function pollTranscodeStatus(jobId: string) { ${directiveUseWorkflow}; const maxPolls = 8; const intervalMs = 2000; for (let poll = 1; poll <= maxPolls; poll++) { const state = await checkTranscodeJob(jobId, poll); if (state === "ready") { return { jobId, status: "completed", pollCount: poll }; } if (poll < maxPolls) { await sleep(\`${"${intervalMs}"}ms\`); } } return { jobId, status: "timeout", pollCount: maxPolls }; }`; const stepCode = `async function checkTranscodeJob(jobId: string, poll: number) { ${directiveUseStep}; const response = await fetch(\`https://transcode.example.com/jobs/\${jobId}\`, { method: "GET", headers: { "x-poll": String(poll) }, }); if (!response.ok) { throw new Error(\`Transcode API error on poll \${poll}\`); } const result = await response.json(); return result.state; }`; function buildWorkflowLineMap(code: string) { const lines = code.split("\n"); const poll = lines .map((line, index) => line.includes("await checkTranscodeJob(") ? index + 1 : null ) .filter((line): line is number => line !== null); const sleep = lines .map((line, index) => (line.includes("await sleep(") ? index + 1 : null)) .filter((line): line is number => line !== null); const successReturn = lines .map((line, index) => line.includes('status: "completed"') ? index + 1 : null ) .filter((line): line is number => line !== null); const timeoutReturn = lines .map((line, index) => line.includes('status: "timeout"') ? index + 1 : null ) .filter((line): line is number => line !== null); return { poll, sleep, successReturn, timeoutReturn, }; } function buildStepLineMap(code: string) { const lines = code.split("\n"); const poll = lines .map((line, index) => line.includes("const response = await fetch(") ? index + 1 : null ) .filter((line): line is number => line !== null); const successReturn = lines .map((line, index) => (line.includes("return result.state;") ? index + 1 : null)) .filter((line): line is number => line !== null); return { poll, successReturn }; } const workflowHtmlLines = highlightCodeToHtmlLines(workflowCode); const stepHtmlLines = highlightCodeToHtmlLines(stepCode); const workflowLineMap = buildWorkflowLineMap(workflowCode); const stepLineMap = buildStepLineMap(stepCode); export default function Home() { return (

Workflow DevKit Example

Status Poller

Polling an external service until it is ready should not require cron jobs, database tables, or cleanup logic. This workflow polls a transcoding service with durable{" "} sleep(){" "} between checks, which means zero compute while waiting.

Try It

{/* ── Why this matters ────────────────────────────────────── */}

Why Not Just Use a Cron Job?

Traditional

You build a polling table with a database, a cron job or background worker, and manual bookkeeping for poll counts, interval timers, and timeout thresholds. Stale polls sit in a table until the next sweep. The {"\u201C"}polling logic{"\u201D"} is scattered across the scheduler, the handler, and the DB schema.

Workflow Poller

A for loop with{" "} sleep(){" "} is the polling logic. Each{" "} sleep() is a durable pause at zero compute{"\u2014"}no cron, no timers, no database rows. The poll counter and interval are plain local variables that survive across restarts.

In production, add dead-letter handling or alert on max-polls exhausted to avoid silent timeouts.

); } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @theme { --color-background-100: #0a0a0a; --color-background-200: #171717; --color-gray-100: #1a1a1a; --color-gray-200: #1f1f1f; --color-gray-300: #292929; --color-gray-400: #737373; --color-gray-500: #525252; --color-gray-600: #404040; --color-gray-700: #262626; --color-gray-800: #171717; --color-gray-900: #a1a1a1; --color-gray-1000: #ededed; --color-blue-700: #0070F3; --color-red-700: #E5484D; --color-amber-700: #FFB224; --color-green-700: #46A758; --color-violet-700: #8B5CF6; --color-cyan-700: #06B6D4; --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } body { background: #0a0a0a; color: #ededed; font-family: var(--font-sans), -apple-system, BlinkMacSystemFont, sans-serif; } /* sugar-high syntax tokens */ :root, .dark { --sh-class: #52a8ff; --sh-identifier: #ededed; --sh-sign: #a1a1a1; --sh-property: #ff6166; --sh-entity: #62c073; --sh-jsxliterals: #ededed; --sh-string: #62c073; --sh-keyword: #f75f8f; --sh-comment: #a1a1a1; } /* Prism token colors - Geist dark-mode palette Extracted from vercel.com/geist/code-block (dark theme) */ .token.keyword, .token.keyword.control-flow { color: #f75f8f; } /* pink - keywords */ .token.plain, .token.parameter, .token.punctuation, .token.plain-text, .token.property-access, .token.operator, .token.tag.punctuation { color: #ededed; } /* gray-1000 - plain text */ .token.function, .token.function.maybe-class-name { color: #bf7af0; } /* purple - functions */ .token.tag { color: #62c073; } /* green - JSX/HTML tags */ .token.literal-property.property { color: #ff6166; } /* red - properties */ .token.string, .token.boolean { color: #62c073; } /* green - strings, booleans */ .token.comment { color: #a1a1a1; } /* gray-900 - comments */ .token.class-name { color: #52a8ff; } /* blue - types */ .token.number { color: #62c073; } /* green - numbers */ .token.attr-name { color: #ff6166; } /* red - attribute names */ .token.attr-value { color: #62c073; } /* green - attribute values */ .token.builtin { color: #52a8ff; } /* blue - builtins */ .token.template-string { color: #62c073; } /* green - template literals */ .token.interpolation { color: #ededed; } /* gray-1000 - interpolation */ [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; [V0_FILE]typescript:file="workflows/status-poller.ts" import { sleep } from "workflow"; export interface PollResult { jobId: string; status: "completed" | "timeout"; pollCount: number; finalState?: string; } export async function pollTranscodeStatus( jobId: string, maxPolls: number = 10, intervalMs: number = 2000 ): Promise { "use workflow"; for (let poll = 1; poll <= maxPolls; poll++) { const state = await checkTranscodeJob(jobId, poll); if (state === "ready") { return { jobId, status: "completed", pollCount: poll, finalState: state }; } if (poll < maxPolls) { await sleep(`${intervalMs}ms`); } } return { jobId, status: "timeout", pollCount: maxPolls }; } async function checkTranscodeJob(jobId: string, poll: number): Promise { "use step"; console.info("[status-poller] check_transcode", { jobId, poll }); // In production: fetch("https://transcode.example.com/jobs/" + jobId) // Returns "processing", "encoding", "finalizing", or "ready" return "processing"; // Simulated } [V0_FILE]json:file="package.json" { "name": "status-poller", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "16.0.10", "react": "19.2.3", "react-dom": "19.2.3", "sugar-high": "^0.9.5", "workflow": "4.1.0-beta.53" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5" } } [V0_FILE]json:file="tsconfig.json" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "react-jsx", "incremental": true, "plugins": [ { "name": "next" }, { "name": "workflow" } ], "paths": { "@/*": ["./*"] } }, "include": [ "next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", "**/*.mts" ], "exclude": ["node_modules"] } [V0_FILE]typescript:file="next.config.ts" import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = {}; export default withWorkflow(nextConfig);