[V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useCallback, useEffect, useMemo, useRef, useState, } from "react"; import type { ReminderSnapshot, ReminderLogEvent } from "@/app/api/mock/store"; import { WakeableReminderCodeWorkbench } from "./wakeable-reminder-code-workbench"; /* ── Types ───────────────────────────────────────────────── */ type LifecycleState = | "idle" | "sleeping" | "snoozed" | "sending" | "sent" | "cancelled"; type HighlightTone = "amber" | "cyan" | "green" | "red" | "blue"; type GutterMarkKind = "success" | "fail"; type WorkflowLineMap = { sleepAndRace: number[]; cancelReturn: number[]; snoozeBlock: number[]; sendNowFallthrough: number[]; sendEmail: number[]; sentReturn: number[]; createHook: number[]; }; type StepLineMap = { body: number[]; }; type WakeableReminderDemoProps = { workflowCode: string; workflowHtmlLines: string[]; workflowLineMap: WorkflowLineMap; stepCode: string; stepHtmlLines: string[]; stepLineMap: StepLineMap; }; const POLL_INTERVAL_MS = 200; const DELAY_OPTIONS: { label: string; ms: number }[] = [ { label: "10s", ms: 10_000 }, { label: "30s", ms: 30_000 }, { label: "1m", ms: 60_000 }, ]; /* ── Helpers ─────────────────────────────────────────────── */ 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 | { message?: string } }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { let message = `Request failed (${response.status})`; if (typeof payload === "object" && payload && "error" in payload) { const err = payload.error; if (typeof err === "string") message = err; else if (typeof err === "object" && err && "message" in err) message = (err as { message: string }).message; } throw new Error(message); } return payload as T; } function formatCountdown(ms: number): string { if (ms <= 0) return "00:00"; const totalSeconds = Math.ceil(ms / 1000); const minutes = Math.floor(totalSeconds / 60); const seconds = totalSeconds % 60; return `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`; } function formatTimeLabel(ms: number): string { return new Date(ms).toLocaleTimeString(); } /* ── Demo Component ──────────────────────────────────────── */ export function WakeableReminderDemo({ workflowCode, workflowHtmlLines, workflowLineMap, stepCode, stepHtmlLines, stepLineMap, }: WakeableReminderDemoProps) { const [delayMs, setDelayMs] = useState(DELAY_OPTIONS[0].ms); const [lifecycle, setLifecycle] = useState("idle"); const [runId, setRunId] = useState(null); const [snapshot, setSnapshot] = useState(null); const [error, setError] = useState(null); const [countdownMs, setCountdownMs] = useState(0); const pollTimerRef = useRef | null>(null); const inFlightRef = useRef(false); const abortRef = useRef(null); const startButtonRef = useRef(null); const rafRef = useRef(null); const stopPolling = useCallback(() => { if (pollTimerRef.current) { clearInterval(pollTimerRef.current); pollTimerRef.current = null; } inFlightRef.current = false; }, []); const stopCountdown = useCallback(() => { if (rafRef.current !== null) { cancelAnimationFrame(rafRef.current); rafRef.current = null; } }, []); const ensureAbortController = useCallback((): AbortController => { if (!abortRef.current || abortRef.current.signal.aborted) { abortRef.current = new AbortController(); } return abortRef.current; }, []); useEffect(() => { return () => { stopPolling(); stopCountdown(); abortRef.current?.abort(); abortRef.current = null; }; }, [stopPolling, stopCountdown]); // RAF-based countdown ticker useEffect(() => { if ( !snapshot || (lifecycle !== "sleeping" && lifecycle !== "snoozed") ) { stopCountdown(); return; } const sendAtMs = snapshot.sendAtMs; const tick = () => { const remaining = Math.max(0, sendAtMs - Date.now()); setCountdownMs(remaining); if (remaining > 0) { rafRef.current = requestAnimationFrame(tick); } }; tick(); return () => { stopCountdown(); }; }, [snapshot, lifecycle, stopCountdown]); const fetchStatus = 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 ReminderSnapshot | { error?: string }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = typeof payload === "object" && payload && "error" in payload ? String(payload.error) : `Status request failed (${response.status})`; throw new Error(message); } return payload as ReminderSnapshot; }, [] ); 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 fetchStatus(targetRunId, signal); if (signal.aborted) return; setSnapshot(nextSnapshot); const status = nextSnapshot.status; if (status === "sent") { setLifecycle("sent"); stopPolling(); return; } if (status === "cancelled") { setLifecycle("cancelled"); stopPolling(); return; } if (status === "sending") { setLifecycle("sending"); } else if (status === "snoozed") { setLifecycle("snoozed"); } else if (status === "sleeping") { setLifecycle("sleeping"); } } catch (pollError) { if ( (signal && signal.aborted) || (pollError instanceof Error && pollError.name === "AbortError") ) { return; } stopPolling(); setLifecycle("idle"); setError( pollError instanceof Error ? pollError.message : "Failed to read status" ); } finally { inFlightRef.current = false; } }; void poll(); pollTimerRef.current = setInterval(() => { void poll(); }, POLL_INTERVAL_MS); }, [ensureAbortController, fetchStatus, stopPolling] ); const handleStart = useCallback(async () => { setError(null); stopPolling(); stopCountdown(); abortRef.current?.abort(); abortRef.current = null; const controller = ensureAbortController(); const signal = controller.signal; try { const payload = await postJson<{ runId: string; status: string; snapshot: ReminderSnapshot; }>("/api/mock/start", { userId: "user-42", delayMs }, signal); if (signal.aborted) return; setRunId(payload.runId); setSnapshot(payload.snapshot); setLifecycle("sleeping"); beginPolling(payload.runId); } catch (startError) { if ( signal.aborted || (startError instanceof Error && startError.name === "AbortError") ) { return; } setError( startError instanceof Error ? startError.message : "Failed to start reminder" ); setLifecycle("idle"); } }, [beginPolling, delayMs, ensureAbortController, stopPolling, stopCountdown]); const handleAction = useCallback( async (action: { type: string; seconds?: number }) => { if (!runId) return; const controller = ensureAbortController(); const signal = controller.signal; try { const payload = await postJson<{ snapshot: ReminderSnapshot }>( "/api/mock/action", { runId, action }, signal ); if (signal.aborted) return; setSnapshot(payload.snapshot); } catch (err) { if ( signal.aborted || (err instanceof Error && err.name === "AbortError") ) return; setError( err instanceof Error ? err.message : "Action failed" ); } }, [runId, ensureAbortController] ); const handleWake = useCallback(async () => { if (!runId) return; const controller = ensureAbortController(); const signal = controller.signal; try { const payload = await postJson<{ snapshot: ReminderSnapshot }>( "/api/mock/wake", { runId }, signal ); if (signal.aborted) return; setSnapshot(payload.snapshot); } catch (err) { if ( signal.aborted || (err instanceof Error && err.name === "AbortError") ) return; setError(err instanceof Error ? err.message : "Wake failed"); } }, [runId, ensureAbortController]); const handleReset = useCallback(() => { stopPolling(); stopCountdown(); abortRef.current?.abort(); abortRef.current = null; setLifecycle("idle"); setRunId(null); setSnapshot(null); setError(null); setCountdownMs(0); setTimeout(() => { startButtonRef.current?.focus(); }, 0); }, [stopPolling, stopCountdown]); const isActive = lifecycle === "sleeping" || lifecycle === "snoozed" || lifecycle === "sending"; const isDone = lifecycle === "sent" || lifecycle === "cancelled"; /* ── Code workbench state ─────────────────────────── */ const codeState = useMemo(() => { const wfMarks: Record = {}; const stepMarks: Record = {}; if (!snapshot) { return { tone: "amber" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } const status = snapshot.status; // Mark createHook as success once we are past idle if (status !== "sleeping" || snapshot.elapsedMs > 100) { for (const ln of workflowLineMap.createHook) wfMarks[ln] = "success"; } if (status === "sleeping" || status === "snoozed") { return { tone: "amber" as HighlightTone, workflowActiveLines: workflowLineMap.sleepAndRace, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (status === "sending") { for (const ln of workflowLineMap.sleepAndRace) wfMarks[ln] = "success"; for (const ln of workflowLineMap.sendEmail) wfMarks[ln] = "success"; return { tone: "green" as HighlightTone, workflowActiveLines: workflowLineMap.sendEmail, stepActiveLines: stepLineMap.body, workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (status === "sent") { for (const ln of workflowLineMap.sleepAndRace) wfMarks[ln] = "success"; for (const ln of workflowLineMap.sendEmail) wfMarks[ln] = "success"; for (const ln of workflowLineMap.sentReturn) wfMarks[ln] = "success"; for (const ln of stepLineMap.body) stepMarks[ln] = "success"; return { tone: "green" as HighlightTone, workflowActiveLines: workflowLineMap.sentReturn, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (status === "cancelled") { for (const ln of workflowLineMap.sleepAndRace) wfMarks[ln] = "success"; for (const ln of workflowLineMap.cancelReturn) wfMarks[ln] = "fail"; return { tone: "red" as HighlightTone, workflowActiveLines: workflowLineMap.cancelReturn, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } return { tone: "amber" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; }, [snapshot, workflowLineMap, stepLineMap]); /* ── Phase explainer ──────────────────────────────── */ const phaseExplainer = useMemo(() => { if (!snapshot) return "Waiting to schedule a reminder."; if (snapshot.status === "sleeping") return "sleep(Date) in progress. The workflow is durably suspended and consuming zero compute."; if (snapshot.status === "snoozed") return "Snoozed. sleep(Date) restarted with a new target time."; if (snapshot.status === "sending") return "sendReminderEmail() step is executing."; if (snapshot.status === "sent") return "Reminder email sent successfully."; if (snapshot.status === "cancelled") return "Reminder cancelled. Workflow returned early."; return "Run is active."; }, [snapshot]); /* ── Status badge ─────────────────────────────────── */ const statusBadge = useMemo(() => { if (!snapshot) return null; const status = snapshot.status; const map: Record< string, { label: string; dotClass: string; badgeClass: string } > = { sleeping: { label: "Sleeping", dotClass: "bg-amber-700 animate-pulse", badgeClass: "border-amber-700/40 bg-amber-700/10 text-amber-700", }, snoozed: { label: "Snoozed", dotClass: "bg-cyan-700 animate-pulse", badgeClass: "border-cyan-700/40 bg-cyan-700/10 text-cyan-700", }, sending: { label: "Sending", dotClass: "bg-green-700 animate-pulse", badgeClass: "border-green-700/40 bg-green-700/10 text-green-700", }, sent: { label: "Sent", dotClass: "bg-green-700", badgeClass: "border-green-700/40 bg-green-700/10 text-green-700", }, cancelled: { label: "Cancelled", dotClass: "bg-red-700", badgeClass: "border-red-700/40 bg-red-700/10 text-red-700", }, }; const s = map[status] ?? { label: status, dotClass: "bg-gray-500", badgeClass: "border-gray-400/70 bg-background-100 text-gray-900", }; return ( ); }, [snapshot]); /* ── Render ────────────────────────────────────────── */ return (

{error && (

{error}

)} {/* Controls row */}

{lifecycle !== "idle" && ( )} Delay

{/* Main visualization */}

{/* Status header */}

{statusBadge}

{phaseExplainer}

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

{/* Left: Countdown + actions */}

{/* Countdown */}

{lifecycle === "idle" ? (

No reminder scheduled.

) : ( <>

{lifecycle === "sent" ? "SENT" : lifecycle === "cancelled" ? "CANCELLED" : lifecycle === "sending" ? "SENDING..." : formatCountdown(countdownMs)}

{snapshot && (lifecycle === "sleeping" || lifecycle === "snoozed") && (

Target: {formatTimeLabel(snapshot.sendAtMs)}

)} )}

{/* Action buttons */} {isActive && (

)} {/* Token inspector */} {snapshot && ( )}

{/* Right: Event log */}

sleep(Date) + createHook() + wakeUpRun() — no cron, no DB polling

{/* Code workbench */}

); } /* ── Token Inspector ─────────────────────────────────────── */ function TokenInspector({ token, metadata, }: { token: string; metadata: { userId: string; initialSendAt: string; channel: string }; }) { const [expanded, setExpanded] = useState(false); return (

{expanded && (

getHookByToken( "{token}")

{`{
  userId: "${metadata.userId}",
  initialSendAt: "${metadata.initialSendAt}",
  channel: "${metadata.channel}"
}`}

)}

); } /* ── Event Log ───────────────────────────────────────────── */ function EventLog({ events, elapsedMs, }: { events: ReminderLogEvent[]; elapsedMs: number; }) { const scrollRef = useRef(null); useEffect(() => { const el = scrollRef.current; if (el) { el.scrollTop = el.scrollHeight; } }, [events.length]); return (

Execution log

{(elapsedMs / 1000).toFixed(1)}s

{events.length === 0 && (

No events yet.

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

); })}

); } function eventTone(kind: string): { dotClass: string; labelClass: string; } { switch (kind) { case "scheduled": return { dotClass: "bg-blue-700", labelClass: "text-blue-700" }; case "sleeping": return { dotClass: "bg-amber-700", labelClass: "text-amber-700" }; case "action_received": return { dotClass: "bg-violet-700", labelClass: "text-violet-700" }; case "snoozed": return { dotClass: "bg-cyan-700", labelClass: "text-cyan-700" }; case "woke": return { dotClass: "bg-blue-700", labelClass: "text-blue-700" }; case "sending": return { dotClass: "bg-green-700 animate-pulse", labelClass: "text-green-700" }; case "sent": return { dotClass: "bg-green-700", labelClass: "text-green-700" }; case "cancelled": 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/wakeable-reminder-code-workbench.tsx" "use client"; import { useEffect, useMemo, useRef, useState } from "react"; type HighlightTone = "amber" | "cyan" | "green" | "red" | "blue"; 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", }, blue: { border: "border-blue-700", bg: "bg-blue-700/15", text: "text-blue-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 WakeableReminderCodeWorkbenchProps = { workflowCode: string; workflowHtmlLines: string[]; workflowActiveLines: number[]; workflowGutterMarks: Record; stepCode: string; stepHtmlLines: string[]; stepActiveLines: number[]; stepGutterMarks: Record; tone: HighlightTone; }; export function WakeableReminderCodeWorkbench({ workflowCode, workflowHtmlLines, workflowActiveLines, workflowGutterMarks, stepCode, stepHtmlLines, stepActiveLines, stepGutterMarks, tone, }: WakeableReminderCodeWorkbenchProps) { 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: "Wakeable Reminder - Workflow DevKit Example", description: "Demonstrates sleep(Date) + createHook + wakeUpRun for schedulable, cancellable reminders 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 { createRun, buildSnapshot } from "../store"; export async function POST(request: Request): Promise { let body: { userId?: unknown; delayMs?: unknown }; try { body = (await request.json()) as { userId?: unknown; delayMs?: unknown }; } catch { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body" }, { status: 400 } ); } const userId = typeof body.userId === "string" && body.userId.trim() ? body.userId.trim() : "user-42"; const delayMs = typeof body.delayMs === "number" && Number.isFinite(body.delayMs) && body.delayMs >= 1000 ? body.delayMs : 10_000; const run = createRun({ userId, delayMs }); const snapshot = buildSnapshot(run, run.createdAtMs); return createApiSuccessResponse({ runId: run.id, status: snapshot.status, 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 { getRun, buildSnapshot } 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 = getRun(runId); if (!run) { return createApiErrorResponse( { code: "NOT_FOUND", message: "Run not found" }, { status: 404 } ); } return createApiSuccessResponse({ ...buildSnapshot(run) }); } [V0_FILE]typescript:file="app/api/mock/wake/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { getRun, wakeRun, buildSnapshot } from "../store"; export async function POST(request: Request): Promise { let body: { runId?: unknown }; try { body = (await request.json()) as { runId?: unknown }; } catch { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body" }, { status: 400 } ); } const runId = typeof body.runId === "string" ? body.runId : null; if (!runId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "runId is required" }, { status: 400 } ); } const run = getRun(runId); if (!run) { return createApiErrorResponse( { code: "NOT_FOUND", message: "Run not found" }, { status: 404 } ); } if (run.status === "sent" || run.status === "cancelled") { return createApiErrorResponse( { code: "CONFLICT", message: `Run already ${run.status}` }, { status: 409 } ); } wakeRun(run); const snapshot = buildSnapshot(run); return createApiSuccessResponse({ snapshot }); } [V0_FILE]typescript:file="app/api/mock/action/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { getRun, applyAction, buildSnapshot } from "../store"; import type { ReminderAction } from "../store"; export async function POST(request: Request): Promise { let body: { runId?: unknown; action?: unknown }; try { body = (await request.json()) as { runId?: unknown; action?: unknown }; } catch { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body" }, { status: 400 } ); } const runId = typeof body.runId === "string" ? body.runId : null; if (!runId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "runId is required" }, { status: 400 } ); } const action = body.action as ReminderAction | undefined; if (!action || typeof action !== "object" || !("type" in action)) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "action is required with a type field" }, { status: 400 } ); } const run = getRun(runId); if (!run) { return createApiErrorResponse( { code: "NOT_FOUND", message: "Run not found" }, { status: 404 } ); } if (run.status === "sent" || run.status === "cancelled") { return createApiErrorResponse( { code: "CONFLICT", message: `Run already ${run.status}` }, { status: 409 } ); } applyAction(run, action); const snapshot = buildSnapshot(run); return createApiSuccessResponse({ snapshot }); } [V0_FILE]typescript:file="app/api/mock/hook/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { getHookByToken } from "../store"; export async function GET(request: Request): Promise { const searchParams = new URL(request.url).searchParams; const token = searchParams.get("token"); if (!token) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "token is required" }, { status: 400 } ); } const run = getHookByToken(token); if (!run) { return createApiErrorResponse( { code: "NOT_FOUND", message: "Hook not found" }, { status: 404 } ); } return createApiSuccessResponse({ token: run.token, metadata: run.metadata, runId: run.id, status: run.status, }); } [V0_FILE]typescript:file="app/api/mock/store.ts" export const SEND_STEP_MS = 500; export type MockRunStatus = | "sleeping" | "snoozed" | "sending" | "sent" | "cancelled"; export type ReminderLogEventKind = | "scheduled" | "sleeping" | "action_received" | "snoozed" | "woke" | "sending" | "sent" | "cancelled"; export interface ReminderLogEvent { atMs: number; kind: ReminderLogEventKind; message: string; } export interface MockReminderRun { id: string; userId: string; status: MockRunStatus; createdAtMs: number; sendAtMs: number; originalSendAtMs: number; token: string; metadata: { userId: string; initialSendAt: string; channel: string; }; events: ReminderLogEvent[]; sendingStartedAtMs: number | null; } declare global { // eslint-disable-next-line no-var var __mockWakeableReminderRuns: Map | undefined; } function getRunStore(): Map { return ( globalThis.__mockWakeableReminderRuns ?? (globalThis.__mockWakeableReminderRuns = new Map()) ); } function generateRunId(): string { return `rem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`; } export function createRun(input: { userId: string; delayMs: number; }): MockReminderRun { const now = Date.now(); const sendAtMs = now + input.delayMs; const token = `reminder:${input.userId}`; const run: MockReminderRun = { id: generateRunId(), userId: input.userId, status: "sleeping", createdAtMs: now, sendAtMs, originalSendAtMs: sendAtMs, token, metadata: { userId: input.userId, initialSendAt: new Date(sendAtMs).toISOString(), channel: "email", }, events: [ { atMs: 0, kind: "scheduled", message: `Reminder scheduled for ${new Date(sendAtMs).toLocaleTimeString()}`, }, { atMs: 0, kind: "sleeping", message: `sleep(Date) — durable pause until ${new Date(sendAtMs).toISOString()}`, }, ], sendingStartedAtMs: null, }; console.info("[mock-wakeable-reminder] run_created", { runId: run.id, userId: run.userId, sendAtMs: run.sendAtMs, token: run.token, }); getRunStore().set(run.id, run); return run; } export function getRun(runId: string): MockReminderRun | undefined { return getRunStore().get(runId); } export type ReminderAction = | { type: "cancel" } | { type: "send_now" } | { type: "snooze"; seconds: number }; export function applyAction( run: MockReminderRun, action: ReminderAction ): void { const now = Date.now(); const elapsed = now - run.createdAtMs; if (run.status === "sent" || run.status === "cancelled") { return; } if (action.type === "cancel") { run.status = "cancelled"; run.events.push({ atMs: elapsed, kind: "action_received", message: `Hook resolved with { type: "cancel" }`, }); run.events.push({ atMs: elapsed, kind: "cancelled", message: "Reminder cancelled — workflow returned early", }); return; } if (action.type === "send_now") { run.sendAtMs = now; run.events.push({ atMs: elapsed, kind: "action_received", message: `Hook resolved with { type: "send_now" }`, }); run.events.push({ atMs: elapsed, kind: "woke", message: "wakeUpRun() — sleep interrupted, sending immediately", }); return; } if (action.type === "snooze") { const newSendAtMs = now + action.seconds * 1000; run.sendAtMs = newSendAtMs; run.status = "snoozed"; run.sendingStartedAtMs = null; run.events.push({ atMs: elapsed, kind: "action_received", message: `Hook resolved with { type: "snooze", seconds: ${action.seconds} }`, }); run.events.push({ atMs: elapsed, kind: "snoozed", message: `Snoozed — new send time: ${new Date(newSendAtMs).toISOString()}`, }); return; } } export function wakeRun(run: MockReminderRun): void { const now = Date.now(); const elapsed = now - run.createdAtMs; if (run.status === "sent" || run.status === "cancelled") { return; } run.sendAtMs = now; run.events.push({ atMs: elapsed, kind: "woke", message: "wakeUpRun() — sleep interrupted, sending immediately", }); } export function getHookByToken(token: string): MockReminderRun | undefined { for (const run of getRunStore().values()) { if (run.token === token) { return run; } } return undefined; } export interface ReminderSnapshot { runId: string; userId: string; status: MockRunStatus; createdAtMs: number; sendAtMs: number; originalSendAtMs: number; remainingMs: number; token: string; metadata: MockReminderRun["metadata"]; events: ReminderLogEvent[]; elapsedMs: number; } export function buildSnapshot( run: MockReminderRun, nowMs: number = Date.now() ): ReminderSnapshot { const elapsedMs = Math.max(0, nowMs - run.createdAtMs); // Transition logic based on timestamps if (run.status !== "sent" && run.status !== "cancelled") { if (nowMs >= run.sendAtMs) { // Time has arrived — transition to sending/sent if (run.sendingStartedAtMs === null) { run.sendingStartedAtMs = nowMs; run.status = "sending" as MockRunStatus; run.events.push({ atMs: elapsedMs, kind: "sending", message: "sendReminderEmail() step executing...", }); } const sendingElapsed = nowMs - run.sendingStartedAtMs; if (sendingElapsed >= SEND_STEP_MS) { run.status = "sent"; run.events.push({ atMs: elapsedMs, kind: "sent", message: "Reminder email sent successfully", }); } } } const remainingMs = run.status === "sleeping" || run.status === "snoozed" ? Math.max(0, run.sendAtMs - nowMs) : 0; return { runId: run.id, userId: run.userId, status: run.status, createdAtMs: run.createdAtMs, sendAtMs: run.sendAtMs, originalSendAtMs: run.originalSendAtMs, remainingMs, token: run.token, metadata: run.metadata, events: run.events, elapsedMs, }; } [V0_FILE]typescript:file="app/api/start/route.ts" import { NextResponse } from "next/server"; import { start } from "workflow/api"; import { scheduleReminder } from "@/workflows/wakeable-reminder"; export async function POST(request: Request) { const { userId, delayMs } = await request.json(); const run = await start(scheduleReminder, [userId, delayMs]); return NextResponse.json({ runId: run.runId }); } [V0_FILE]typescriptreact:file="app/page.tsx" import { highlightCodeToHtmlLines } from "./components/code-highlight-server"; import { WakeableReminderDemo } from "./components/demo"; const directiveUseWorkflow = `"use ${"workflow"}"`; const directiveUseStep = `"use ${"step"}"`; const workflowCode = `import { sleep, createHook } from "workflow"; export async function scheduleReminder(userId: string, delayMs: number) { ${directiveUseWorkflow}; let sendAt = new Date(Date.now() + delayMs); const action = createHook({ token: \`reminder:\${userId}\`, metadata: { userId, initialSendAt: sendAt.toISOString(), channel: "email", }, }); const outcome = await Promise.race([ sleep(sendAt).then(() => ({ kind: "time" })), action.then((payload) => ({ kind: "action", payload })), ]); if (outcome.kind === "action") { if (outcome.payload.type === "cancel") { return { userId, status: "cancelled", token: action.token }; } if (outcome.payload.type === "snooze") { sendAt = new Date(Date.now() + outcome.payload.seconds * 1000); await sleep(sendAt); } // "send_now" falls through to send immediately } await sendReminderEmail(userId, sendAt); return { userId, status: "sent", sentAt: sendAt.toISOString(), token: action.token, }; }`; const stepCode = `async function sendReminderEmail(userId: string, sendAt: Date) { ${directiveUseStep}; console.info("[wakeable-reminder] send_email", { userId, scheduledFor: sendAt.toISOString(), }); }`; function buildWorkflowLineMap(code: string) { const lines = code.split("\n"); const sleepAndRace: number[] = []; const cancelReturn: number[] = []; const snoozeBlock: number[] = []; const sendNowFallthrough: number[] = []; const sendEmail: number[] = []; const sentReturn: number[] = []; const createHook: number[] = []; for (let i = 0; i < lines.length; i++) { const line = lines[i]; const ln = i + 1; if (line.includes("const action = createHook")) createHook.push(ln); if (line.includes("token:") && line.includes("reminder:")) createHook.push(ln); if (line.includes("metadata:")) createHook.push(ln); if (line.includes("const outcome = await Promise.race")) sleepAndRace.push(ln); if (line.includes("sleep(sendAt)")) sleepAndRace.push(ln); if (line.includes("action.then(")) sleepAndRace.push(ln); if (line.includes('status: "cancelled"')) cancelReturn.push(ln); if (line.includes('outcome.payload.type === "snooze"')) snoozeBlock.push(ln); if (line.includes("outcome.payload.seconds * 1000")) snoozeBlock.push(ln); if (line.includes("await sleep(sendAt)") && i > 10) snoozeBlock.push(ln); if (line.includes('"send_now" falls through')) sendNowFallthrough.push(ln); if (line.includes("await sendReminderEmail(")) sendEmail.push(ln); if (line.includes('status: "sent"')) sentReturn.push(ln); if (line.includes("sentAt: sendAt.toISOString()")) sentReturn.push(ln); } return { sleepAndRace, cancelReturn, snoozeBlock, sendNowFallthrough, sendEmail, sentReturn, createHook, }; } function buildStepLineMap(code: string) { const lines = code.split("\n"); const body: number[] = []; for (let i = 0; i < lines.length; i++) { const line = lines[i]; if (line.includes("console.info(")) body.push(i + 1); if (line.includes("scheduledFor:")) body.push(i + 1); } return { body }; } const workflowHtmlLines = highlightCodeToHtmlLines(workflowCode); const stepHtmlLines = highlightCodeToHtmlLines(stepCode); const workflowLineMap = buildWorkflowLineMap(workflowCode); const stepLineMap = buildStepLineMap(stepCode); export default function Home() { return (

Workflow DevKit Example

Wakeable Reminder

Schedule a reminder for an exact time, then cancel, snooze, or send it early without cron jobs or database polling. This workflow uses{" "} sleep(Date){" "} to park until the target time,{" "} createHook(){" "} for external signals, and{" "} wakeUpRun(){" "} to interrupt a sleep.

Try It

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

Why Not Just Use a Cron Job?

Traditional

Store a send_at timestamp in a database, sweep it with a cron job every N seconds, and handle race conditions for cancellation, snoozing, and early sends. The scheduling logic lives across three systems: the DB schema, the cron handler, and the cancellation endpoint.

Workflow DevKit

sleep(Date) durably parks the workflow at zero compute.{" "} createHook() lets external systems cancel, snooze, or fast-forward.{" "} wakeUpRun() interrupts the sleep instantly. All scheduling logic lives in one function.

); } [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 */ .token.keyword, .token.keyword.control-flow { color: #f75f8f; } .token.plain, .token.parameter, .token.punctuation, .token.plain-text, .token.property-access, .token.operator, .token.tag.punctuation { color: #ededed; } .token.function, .token.function.maybe-class-name { color: #bf7af0; } .token.tag { color: #62c073; } .token.literal-property.property { color: #ff6166; } .token.string, .token.boolean { color: #62c073; } .token.comment { color: #a1a1a1; } .token.class-name { color: #52a8ff; } .token.number { color: #62c073; } .token.attr-name { color: #ff6166; } .token.attr-value { color: #62c073; } .token.builtin { color: #52a8ff; } .token.template-string { color: #62c073; } .token.interpolation { color: #ededed; } [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; [V0_FILE]typescript:file="workflows/wakeable-reminder.ts" import { sleep, createHook } from "workflow"; export type ReminderAction = | { type: "cancel" } | { type: "send_now" } | { type: "snooze"; seconds: number }; export type ReminderResult = { userId: string; status: "sent" | "cancelled"; sentAt?: string; token: string; }; export async function scheduleReminder( userId: string, delayMs: number ): Promise { "use workflow"; let sendAt = new Date(Date.now() + delayMs); const action = createHook({ token: `reminder:${userId}`, metadata: { userId, initialSendAt: sendAt.toISOString(), channel: "email", }, }); const outcome = await Promise.race([ sleep(sendAt).then(() => ({ kind: "time" as const })), action.then((payload) => ({ kind: "action" as const, payload })), ]); if (outcome.kind === "action") { if (outcome.payload.type === "cancel") { return { userId, status: "cancelled", token: action.token }; } if (outcome.payload.type === "snooze") { sendAt = new Date(Date.now() + outcome.payload.seconds * 1000); await sleep(sendAt); } // "send_now" falls through to send immediately } await sendReminderEmail(userId, sendAt); return { userId, status: "sent", sentAt: sendAt.toISOString(), token: action.token, }; } async function sendReminderEmail(userId: string, sendAt: Date) { "use step"; console.info("[wakeable-reminder] send_email", { userId, scheduledFor: sendAt.toISOString(), }); } [V0_FILE]json:file="package.json" { "name": "wakeable-reminder", "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);