workflow-cron-sleep 1.0.1 → 1.0.2

package/README.md

@@ -88,14 +88,14 @@ Throws an error if the cron expression is invalid or has no future occurrences.
 
 Since `cronSleep` only sleeps until the **next** occurrence, you need to design your workflow architecture to handle recurring schedules.
 
-### Pattern: Separate Scheduler and Processor Workflows
+### Pattern: While Loop Scheduler
 
-Separate your scheduling logic from your business logic by keeping workflows and steps in different files:
+The simplest approach is a single workflow with a `while (true)` loop that sleeps and triggers your business logic workflow repeatedly:
 
 **`workflows/report-scheduler.ts`** - The scheduler workflow
 ```typescript
 import { cronSleep } from "workflow-cron-sleep"
-import { startReportProcessor } from "./steps"
+import { triggerReportProcessor } from "./steps"
 
 export interface ReportSchedulerInput {
     reportId: string
@@ -107,57 +107,65 @@ export async function reportScheduler(input: ReportSchedulerInput) {
     
     const { reportId, cronExpression } = input
     
-    // Wait for the next scheduled time
-    await cronSleep(cronExpression, { timezone: "America/New_York" })
-    
-    // Trigger the processor workflow
-    await startReportProcessor(reportId, cronExpression)
+    while (true) {
+        // Wait for the next scheduled time
+        await cronSleep(cronExpression, { timezone: "America/New_York" })
+        
+        // Trigger the processor workflow
+        await triggerReportProcessor(reportId)
+    }
 }
 ```
 
-**`workflows/report-processor.ts`** - The processor workflow (business logic)
+**`workflows/steps.ts`** - Step function to start the processor
 ```typescript
-import { restartScheduler } from "./steps"
+import { start } from "workflow/api"
+import { reportProcessorWorkflow } from "./report-processor"
+
+export async function triggerReportProcessor(reportId: string) {
+    "use step"
+    await start(reportProcessorWorkflow, [{ reportId }])
+}
+```
 
+**`workflows/report-processor.ts`** - The processor workflow (business logic)
+```typescript
 export interface ReportProcessorInput {
     reportId: string
-    cronExpression: string
 }
 
 export async function reportProcessorWorkflow(input: ReportProcessorInput) {
     "use workflow"
     
-    const { reportId, cronExpression } = input
+    const { reportId } = input
     
-    // Your business logic here
+    // Your business logic here - completely agnostic to scheduling
     await generateReport(reportId)
     await sendNotifications(reportId)
-    
-    // Restart the scheduler for the next occurrence
-    await restartScheduler(reportId, cronExpression)
 }
 ```
 
-**`workflows/steps.ts`** - Step functions in a separate file
+### Starting and Canceling
+
 ```typescript
-import { start } from "workflow"
-import { reportProcessorWorkflow } from "./report-processor"
-import { reportScheduler } from "./report-scheduler"
+import { start, getRun } from "workflow/api"
+import { reportScheduler } from "./workflows/report-scheduler"
 
-export async function startReportProcessor(reportId: string, cronExpression: string) {
-    "use step"
-    await start(reportProcessorWorkflow, [{ reportId, cronExpression }])
-}
+// Start the cron scheduler
+const run = await start(reportScheduler, [{
+    reportId: "daily-report",
+    cronExpression: "0 9 * * *"
+}])
 
-export async function restartScheduler(reportId: string, cronExpression: string) {
-    "use step"
-    await start(reportScheduler, [{ reportId, cronExpression }])
-}
-```
+// Save the run ID to cancel later
+await db.cronJobs.create({ runId: run.id })
 
-This pattern keeps your scheduling and business logic decoupled, and creates a recurring loop: scheduler → processor → scheduler → ...
+// To cancel the cron (stops the while loop)
+const currentRun = getRun(run.id)
+await currentRun.cancel()
+```
 
-For this pattern, it is recommended to return and persist your `runId` for each scheduler workflow run, in case you need to cancel a run. If the cron expression changes, you can cancel the current scheduler run and create a new one with the new cron expression.
+This pattern keeps your scheduling and business logic decoupled. The scheduler runs forever, triggering your processor workflow on schedule. Save the `runId` so you can cancel if the cron expression changes or the job is no longer needed.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "workflow-cron-sleep",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "description": "Sleep until the next cron expression occurrence in Vercel Workflows",
     "type": "module",
     "main": "dist/index.js",