workflow-cron-sleep 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Dave Daly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,137 @@
+# workflow-cron-sleep
+
+Sleep until the next cron expression occurrence in [Vercel Workflows](https://vercel.com/docs/workflow).
+
+## What This Does
+
+`cronSleep` pauses your workflow until the **next single occurrence** of a cron expression. It is **not** a recurring cron job scheduler.
+
+```typescript
+// This sleeps ONCE until the next 9 AM, then continues execution
+await cronSleep("0 9 * * *", { timezone: "America/New_York" })
+```
+
+If you need recurring behavior, you'll need to structure your workflows to handle that (see [Recurring Workflows](#recurring-workflows) below).
+
+## Installation
+
+```bash
+npm install workflow-cron-sleep
+```
+
+## Quick Start
+
+```typescript
+import { cronSleep } from "workflow-cron-sleep"
+
+async function myWorkflow() {
+    "use workflow"
+    
+    // Sleep until the next 9 AM Eastern Time
+    await cronSleep("0 9 * * *", { timezone: "America/New_York" })
+    
+    // This runs once at 9 AM, then the workflow ends
+    console.log("It's 9 AM!")
+}
+```
+
+## Timezone Behavior
+
+**Important:** When no timezone is specified, `cronSleep` uses the **local system timezone** of the server running your workflow. On Vercel, this depends on the region your function is deployed to.
+
+For predictable behavior, **always specify a timezone**:
+
+```typescript
+// Recommended: Explicit timezone
+await cronSleep("0 9 * * *", { timezone: "America/New_York" })
+
+// UTC for timezone-agnostic scheduling
+await cronSleep("0 14 * * *", { timezone: "UTC" })
+
+// Not recommended: Server's local timezone (varies by region)
+await cronSleep("0 9 * * *")
+```
+
+## API
+
+### `cronSleep(cronExpression, options?)`
+
+Sleeps until the **next occurrence** of a cron expression.
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cronExpression` | `string` | A valid cron expression (e.g., `"0 9 * * *"`) |
+| `options.timezone` | `string` (optional) | IANA timezone (e.g., `"America/New_York"`, `"UTC"`) |
+
+#### Returns
+
+`Promise<void>` - Resolves when the workflow resumes at the scheduled time.
+
+#### Throws
+
+Throws an error if the cron expression is invalid or has no future occurrences.
+
+## Cron Expression Reference
+
+| Expression | Description |
+|------------|-------------|
+| `0 9 * * *` | Every day at 9:00 AM |
+| `30 8 * * 1` | Every Monday at 8:30 AM |
+| `0 0 1 * *` | First day of every month at midnight |
+| `0 */2 * * *` | Every 2 hours |
+| `0 9 * * 1-5` | Weekdays at 9:00 AM |
+| `59 23 L * *` | Last day of every month at 11:59 PM |
+
+## Recurring Workflows
+
+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
+
+Separate your scheduling logic from your business logic by keeping workflows and steps in different files:
+
+**`workflows/report-scheduler.ts`** - The scheduler workflow
+```typescript
+import { cronSleep } from "workflow-cron-sleep"
+import { startReportProcessor } from "./steps"
+
+interface ReportSchedulerInput {
+    reportId: string
+    cronExpression: string
+}
+
+export async function reportScheduler(input: ReportSchedulerInput) {
+    "use workflow"
+    
+    const { reportId, cronExpression } = input
+    
+    // Wait for the next scheduled time
+    await cronSleep(cronExpression, { timezone: "America/New_York" })
+    
+    // Trigger the processor workflow
+    await startReportProcessor(reportId)
+}
+```
+
+**`workflows/steps.ts`** - Step functions in a separate file
+```typescript
+import { start } from "workflow"
+import { reportProcessorWorkflow } from "./report-processor"
+
+export async function startReportProcessor(reportId: string) {
+    "use step"
+    await start(reportProcessorWorkflow, [{ reportId }])
+}
+```
+
+This pattern keeps your scheduling and business logic decoupled, making each workflow easier to test and maintain.
+
+## Requirements
+
+- `workflow` package (Vercel Workflows SDK)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for cronSleep function
+ */
+export interface CronSleepOptions {
+    /**
+     * Timezone for the cron expression (e.g., "America/New_York", "Europe/London")
+     * If not specified, uses the system's local timezone
+     */
+    timezone?: string;
+}
+/**
+ * Sleeps until the next occurrence of a cron expression.
+ *
+ * This function parses the provided cron expression, calculates when it would
+ * next trigger, and suspends the workflow until that time.
+ *
+ * @param cronExpression - A valid cron expression (e.g., "0 9 * * *" for 9 AM daily)
+ * @param options - Optional configuration including timezone
+ * @returns A promise that resolves when the workflow resumes at the scheduled time
+ * @throws Error if the cron expression is invalid or has no future runs
+ *
+ * @example
+ * // Sleep until the next 9 AM
+ * await cronSleep("0 9 * * *")
+ *
+ * @example
+ * // Sleep until the next 9 AM in New York timezone
+ * await cronSleep("0 9 * * *", { timezone: "America/New_York" })
+ *
+ * @example
+ * // Sleep until the next Monday at 8:30 AM
+ * await cronSleep("30 8 * * 1")
+ */
+export declare function cronSleep(cronExpression: string, options?: CronSleepOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,SAAS,CAC7B,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/index.js

@@ -0,0 +1,34 @@
+import { sleep } from "workflow";
+import { Cron } from "croner";
+/**
+ * Sleeps until the next occurrence of a cron expression.
+ *
+ * This function parses the provided cron expression, calculates when it would
+ * next trigger, and suspends the workflow until that time.
+ *
+ * @param cronExpression - A valid cron expression (e.g., "0 9 * * *" for 9 AM daily)
+ * @param options - Optional configuration including timezone
+ * @returns A promise that resolves when the workflow resumes at the scheduled time
+ * @throws Error if the cron expression is invalid or has no future runs
+ *
+ * @example
+ * // Sleep until the next 9 AM
+ * await cronSleep("0 9 * * *")
+ *
+ * @example
+ * // Sleep until the next 9 AM in New York timezone
+ * await cronSleep("0 9 * * *", { timezone: "America/New_York" })
+ *
+ * @example
+ * // Sleep until the next Monday at 8:30 AM
+ * await cronSleep("30 8 * * 1")
+ */
+export async function cronSleep(cronExpression, options) {
+    const cron = new Cron(cronExpression, { timezone: options?.timezone });
+    const nextRun = cron.nextRun();
+    if (!nextRun) {
+        throw new Error(`Invalid cron expression or no future runs: ${cronExpression}`);
+    }
+    await sleep(nextRun);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAa7B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,cAAsB,EACtB,OAA0B;IAE1B,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;IACtE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA;IAE9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8CAA8C,cAAc,EAAE,CAAC,CAAA;IACjF,CAAC;IAED,MAAM,KAAK,CAAC,OAAO,CAAC,CAAA;AACtB,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "workflow-cron-sleep",
+    "version": "1.0.0",
+    "description": "Sleep until the next cron expression occurrence in Vercel Workflows",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "workflow",
+        "vercel",
+        "cron",
+        "sleep",
+        "scheduler",
+        "cron-expression"
+    ],
+    "author": "Dave Daly",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/dalyd14/workflow-cron-sleep.git"
+    },
+    "bugs": {
+        "url": "https://github.com/dalyd14/workflow-cron-sleep/issues"
+    },
+    "homepage": "https://github.com/dalyd14/workflow-cron-sleep#readme",
+    "peerDependencies": {
+        "workflow": ">=4.0.0"
+    },
+    "dependencies": {
+        "croner": "^8.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.3.0",
+        "workflow": "^4.0.1-beta.44"
+    }
+}