Hyperfold AI

@OnSchedule

Run tasks on a recurring schedule using cron expressions.

Overview

The @OnSchedule decorator marks methods that run on a recurring schedule. Schedules are defined using standard cron syntax and executed via Google Cloud Scheduler.

import { HyperfoldAgent, OnSchedule } from '@hyperfold/actions-sdk';
@HyperfoldAgent({ name: 'ops-bot', type: 'custom' })
export class OpsBot {
  @OnSchedule('0 9 * * *')  // Every day at 9:00 AM
  async dailyReport() {
    const stats = await this.analytics.getDailyStats();
    await this.notifications.sendSlack({
      channel: '#sales-reports',
      message: `Daily Report: ${stats.conversions} conversions, $${stats.revenue}`,
    });
  }
  @OnSchedule('0 * * * *')  // Every hour
  async syncInventory() {
    await this.integrations.shopify.syncInventory();
  }
  @OnSchedule('0 0 1 * *')  // First day of each month
  async monthlyReconciliation() {
    await this.billing.reconcile();
  }
}

Cron Syntax

Standard 5-field cron expressions:

// minute hour day month weekday
// * * * * *
@OnSchedule('0 9 * * *')     // 9:00 AM every day
@OnSchedule('30 14 * * *')   // 2:30 PM every day
@OnSchedule('0 */4 * * *')   // Every 4 hours
@OnSchedule('*/15 * * * *')  // Every 15 minutes
@OnSchedule('0 9 * * 1')     // 9:00 AM every Monday
@OnSchedule('0 9 * * 1-5')   // 9:00 AM weekdays
@OnSchedule('0 0 1 * *')     // Midnight on 1st of month
@OnSchedule('0 0 * * 0')     // Midnight every Sunday

Common Patterns

ExpressionDescription
*/15 * * * *Every 15 minutes
0 * * * *Every hour
0 9 * * *Daily at 9 AM
0 9 * * 1-5Weekdays at 9 AM
0 0 * * 0Weekly on Sunday
0 0 1 * *Monthly on the 1st

Timezone Handling

Default timezone is UTC. Specify timezone for business-hours tasks:

@OnSchedule('0 9 * * *', { timezone: 'America/New_York' })
async eastCoastMorning() {
  // Runs at 9 AM Eastern Time
}
@OnSchedule('0 9 * * *', { timezone: 'Europe/London' })
async londonMorning() {
  // Runs at 9 AM London time
}

Best Practices

Use locking for long-running tasks, handle failures gracefully, and use idempotent operations. Avoid assuming tasks run at exactly the scheduled time—Cloud Scheduler may have slight delays.