Schedule Management

/**
 * Client for schedule operations
 */
class ScheduleClient extends BaseClient {
  /** Create new schedule */
  create<A extends any[]>(options: ScheduleOptions<A>): Promise<ScheduleHandle>;

  /** Get handle to existing schedule */
  getHandle(scheduleId: string): ScheduleHandle;

  /** List schedules with optional filtering */
  list(options?: ListScheduleOptions): AsyncIterable<ScheduleSummary>;

  /** Raw gRPC access to WorkflowService */
  readonly workflowService: WorkflowService;
}

interface ScheduleClientOptions extends BaseClientOptions {
  namespace?: string;
  dataConverter?: DataConverter;
  interceptors?: ScheduleClientInterceptor[];
}

import { ScheduleClient } from "@temporalio/client";

const scheduleClient = new ScheduleClient();

// Create daily backup schedule
const handle = await scheduleClient.create({
  scheduleId: 'daily-backup',
  spec: {
    calendars: [{
      hour: [2], // 2 AM
      dayOfWeek: [], // Every day
    }],
  },
  action: {
    type: 'startWorkflow',
    workflowType: 'backup-data',
    args: ['full-backup'],
    taskQueue: 'backup-queue',
  },
});

// List all schedules
for await (const schedule of scheduleClient.list()) {
  console.log(`Schedule: ${schedule.scheduleId}, State: ${schedule.info.paused ? 'Paused' : 'Active'}`);
}

/**
 * Handle to single schedule instance
 */
interface ScheduleHandle {
  /** Schedule identifier */
  readonly scheduleId: string;
  /** Reference to ScheduleClient */
  readonly client: ScheduleClient;

  /** Get schedule description */
  describe(): Promise<ScheduleDescription>;

  /** Update schedule configuration */
  update<W extends Workflow = Workflow>(
    updateFn: (previous: ScheduleDescription) => ScheduleUpdateOptions<ScheduleOptionsStartWorkflowAction<W>>
  ): Promise<void>;

  /** Delete schedule */
  delete(): Promise<void>;

  /** Trigger immediate execution */
  trigger(overlap?: ScheduleOverlapPolicy): Promise<void>;

  /** Backfill schedule over time periods */
  backfill(options: Backfill | Backfill[]): Promise<void>;

  /** Pause schedule */
  pause(note?: string): Promise<void>;

  /** Unpause schedule */
  unpause(note?: string): Promise<void>;
}

// Get schedule handle and describe
const handle = scheduleClient.getHandle('daily-backup');
const description = await handle.describe();
console.log('Next runs:', description.info.nextActionTimes.slice(0, 3));

// Update schedule to run every 2 hours
await handle.update({
  schedule: {
    spec: {
      intervals: [{
        every: '2h',
      }],
    },
  },
});

// Pause schedule temporarily
await handle.pause('Maintenance window');

// Trigger immediate execution
await handle.trigger({ overlap: ScheduleOverlapPolicy.ALLOW_ALL });

// Backfill missed executions
await handle.backfill([{
  startTime: new Date('2023-01-01'),
  endTime: new Date('2023-01-07'),
  overlap: ScheduleOverlapPolicy.SKIP,
}]);

/**
 * Options for creating schedules
 */
interface ScheduleOptions<A extends any[]> {
  /** Schedule identifier */
  scheduleId: string;
  /** Schedule specification */
  spec: ScheduleSpec;
  /** Action to perform when scheduled */
  action: ScheduleAction<A>;
  /** Schedule policies */
  policies?: SchedulePolicies;
  /** Initial schedule state */
  state?: ScheduleState;
  /** Memo for the schedule */
  memo?: Record<string, any>;
  /** Search attributes */
  searchAttributes?: SearchAttributes;
}

/**
 * Options for updating schedules
 */
interface ScheduleUpdateOptions<A extends any[]> {
  /** Updated schedule configuration */
  schedule: {
    spec?: ScheduleSpec;
    action?: ScheduleAction<A>;
    policies?: SchedulePolicies;
    state?: ScheduleState;
    memo?: Record<string, any>;
    searchAttributes?: SearchAttributes;
  };
}

/**
 * Options for listing schedules
 */
interface ListScheduleOptions {
  /** Maximum number of schedules to return */
  pageSize?: number;
  /** Namespace to search in */
  namespace?: string;
}

/**
 * Options for triggering schedules immediately
 */
interface TriggerImmediatelyOptions {
  /** Overlap policy for immediate trigger */
  overlap?: ScheduleOverlapPolicy;
}

/**
 * Complete schedule specification
 */
interface ScheduleSpec {
  /** Calendar-based scheduling */
  calendars?: CalendarSpec[];
  /** Interval-based scheduling */
  intervals?: IntervalSpec[];
  /** Cron expressions (alternative to calendars/intervals) */
  cronExpressions?: string[];
  /** Exclude certain times */
  excludeCalendars?: CalendarSpec[];
  /** Start time constraint */
  startTime?: Date;
  /** End time constraint */
  endTime?: Date;
  /** Jitter for randomizing execution times */
  jitter?: string | number;
  /** Timezone for calendar specs */
  timeZone?: string;
}

/**
 * Calendar-based schedule specification
 */
interface CalendarSpec {
  /** Seconds (0-59) */
  second?: number[];
  /** Minutes (0-59) */
  minute?: number[];
  /** Hours (0-23) */
  hour?: number[];
  /** Day of month (1-31) */
  dayOfMonth?: number[];
  /** Month (1-12) */
  month?: number[];
  /** Year */
  year?: number[];
  /** Day of week (0=Sunday, 6=Saturday) */
  dayOfWeek?: number[];
  /** Additional comment */
  comment?: string;
}

/**
 * Interval-based schedule specification
 */
interface IntervalSpec {
  /** Interval between executions */
  every: string | number;
  /** Offset from interval boundary */
  offset?: string | number;
}

/**
 * Description version of ScheduleSpec
 */
type ScheduleSpecDescription = {
  calendars?: CalendarSpecDescription[];
  intervals?: IntervalSpecDescription[];
  cronExpressions?: string[];
  excludeCalendars?: CalendarSpecDescription[];
  startTime?: string;
  endTime?: string;
  jitter?: string;
  timeZone?: string;
};

/**
 * Action to perform when schedule triggers
 */
type ScheduleAction<A extends any[]> = {
  type: 'startWorkflow';
  workflowType: string;
  args: A;
  taskQueue: string;
  workflowExecutionTimeout?: string | number;
  workflowRunTimeout?: string | number;
  workflowTaskTimeout?: string | number;
  retry?: RetryPolicy;
  memo?: Record<string, unknown>;
  searchAttributes?: SearchAttributes;
};

/**
 * Schedule execution policies
 */
interface SchedulePolicies {
  /** Policy for handling overlapping executions */
  overlap?: ScheduleOverlapPolicy;
  /** Policy for handling catchup after pause */
  catchupWindow?: string | number;
  /** Pause on workflow failure */
  pauseOnFailure?: boolean;
}

/**
 * Schedule state configuration
 */
interface ScheduleState {
  /** Optional note about the schedule */
  note?: string;
  /** Whether schedule is paused */
  paused?: boolean;
  /** Remaining actions before auto-pause */
  limitedActions?: number;
  /** Remaining runs before completion */
  remainingActions?: number;
}

/**
 * Constants for schedule overlap policies
 */
const ScheduleOverlapPolicy = {
  /** Skip execution if workflow is running */
  SKIP: 'SKIP',
  /** Buffer executions to run after current completes */
  BUFFER_ONE: 'BUFFER_ONE',
  /** Buffer all missed executions */
  BUFFER_ALL: 'BUFFER_ALL',
  /** Cancel running workflow and start new one */
  CANCEL_OTHER: 'CANCEL_OTHER',
  /** Terminate running workflow and start new one */
  TERMINATE_OTHER: 'TERMINATE_OTHER',
  /** Allow multiple concurrent executions */
  ALLOW_ALL: 'ALLOW_ALL',
} as const;

type ScheduleOverlapPolicy = typeof ScheduleOverlapPolicy[keyof typeof ScheduleOverlapPolicy];

/**
 * Schedule summary from list operations
 */
interface ScheduleSummary {
  /** Schedule identifier */
  scheduleId: string;
  /** Schedule information */
  info: ScheduleInfo;
  /** Memo associated with schedule */
  memo?: Memo;
  /** Search attributes */
  searchAttributes?: SearchAttributes;
}

/**
 * Detailed schedule description
 */
type ScheduleDescription = {
  /** Schedule identifier */
  scheduleId: string;
  /** Current schedule configuration */
  schedule: {
    spec: ScheduleSpecDescription;
    action: ScheduleActionDescription;
    policies: SchedulePolicies;
    state: ScheduleState;
  };
  /** Schedule runtime information */
  info: ScheduleInfo;
  /** Memo associated with schedule */
  memo?: Memo;
  /** Search attributes */
  searchAttributes?: SearchAttributes;
};

/**
 * Schedule runtime information
 */
interface ScheduleInfo {
  /** Number of actions taken */
  numActions: number;
  /** Number of actions skipped */
  numActionsMissedCatchupWindow: number;
  /** Number of actions skipped due to overlap */
  numActionsSkippedOverlap: number;
  /** Running workflow executions started by this schedule */
  runningWorkflows: WorkflowExecution[];
  /** Recent actions taken */
  recentActions: ScheduleActionResult[];
  /** Next scheduled action times */
  nextActionTimes: Date[];
  /** When schedule was created */
  createTime: Date;
  /** When schedule was last updated */
  updateTime: Date;
}

/**
 * Result of schedule execution
 */
interface ScheduleExecutionResult {
  /** Scheduled action time */
  scheduledTime: Date;
  /** Actual action time */
  actualTime: Date;
  /** Started workflow execution */
  startWorkflowResult?: WorkflowExecution;
}

/**
 * Schedule list entry
 */
interface ScheduleListEntry extends ScheduleSummary {
  /** Additional metadata */
  searchAttributes?: SearchAttributes;
}

/**
 * Backfill operation specification
 */
interface Backfill {
  /** Start time for backfill period */
  startTime: Date;
  /** End time for backfill period */
  endTime: Date;
  /** Overlap policy for backfill executions */
  overlap?: ScheduleOverlapPolicy;
}

// Backfill a schedule for the past week
await handle.backfill([
  {
    startTime: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // 7 days ago
    endTime: new Date(),
    overlap: ScheduleOverlapPolicy.SKIP,
  }
]);