1
declare module 'cloudflare:workflows' {
2
  /**
3
   * NonRetryableError allows for a user to throw a fatal error
4
   * that makes a Workflow instance fail immediately without triggering a retry
5
   */
6
  export class NonRetryableError extends Error {
7
    public constructor(message: string, name?: string);
8
  }
9
}
10
 
11
declare abstract class Workflow<PARAMS = unknown> {
12
  /**
13
   * Get a handle to an existing instance of the Workflow.
14
   * @param id Id for the instance of this Workflow
15
   * @returns A promise that resolves with a handle for the Instance
16
   */
17
  public get(id: string): Promise<WorkflowInstance>;
18
 
19
  /**
20
   * Create a new instance and return a handle to it. If a provided id exists, an error will be thrown.
21
   * @param options Options when creating an instance including id and params
22
   * @returns A promise that resolves with a handle for the Instance
23
   */
24
  public create(
25
    options?: WorkflowInstanceCreateOptions<PARAMS>
26
  ): Promise<WorkflowInstance>;
27
 
28
  /**
29
   * Create a batch of instances and return handle for all of them. If a provided id exists, an error will be thrown.
30
   * `createBatch` is limited at 100 instances at a time or when the RPC limit for the batch (1MiB) is reached.
31
   * @param batch List of Options when creating an instance including name and params
32
   * @returns A promise that resolves with a list of handles for the created instances.
33
   */
34
  public createBatch(
35
    batch: WorkflowInstanceCreateOptions<PARAMS>[]
36
  ): Promise<WorkflowInstance[]>;
37
}
38
 
39
type WorkflowDurationLabel =
40
  | 'second'
41
  | 'minute'
42
  | 'hour'
43
  | 'day'
44
  | 'week'
45
  | 'month'
46
  | 'year';
47
 
48
type WorkflowSleepDuration =
49
  | `${number} ${WorkflowDurationLabel}${'s' | ''}`
50
  | number;
51
 
52
type WorkflowRetentionDuration = WorkflowSleepDuration;
53
 
54
interface WorkflowInstanceCreateOptions<PARAMS = unknown> {
55
  /**
56
   * An id for your Workflow instance. Must be unique within the Workflow.
57
   */
58
  id?: string;
59
  /**
60
   * The event payload the Workflow instance is triggered with
61
   */
62
  params?: PARAMS;
63
  /**
64
   * The retention policy for Workflow instance.
65
   * Defaults to the maximum retention period available for the owner's account.
66
   */
67
  retention?: {
68
    successRetention?: WorkflowRetentionDuration,
69
    errorRetention?: WorkflowRetentionDuration,
70
  };
71
}
72
 
73
type InstanceStatus = {
74
  status:
75
    | 'queued' // means that instance is waiting to be started (see concurrency limits)
76
    | 'running'
77
    | 'paused'
78
    | 'errored'
79
    | 'terminated' // user terminated the instance while it was running
80
    | 'complete'
81
    | 'waiting' // instance is hibernating and waiting for sleep or event to finish
82
    | 'waitingForPause' // instance is finishing the current work to pause
83
    | 'unknown';
84
  error?: {
85
    name: string;
86
    message: string;
87
  };
88
  output?: unknown;
89
};
90
 
91
interface WorkflowError {
92
  code?: number;
93
  message: string;
94
}
95
 
96
interface WorkflowInstanceRestartOptions {
97
  /**
98
   * Restart from a specific step. If omitted, the instance restarts from the beginning.
99
   * The step must exist in the instance's execution history.
100
   */
101
  from?: {
102
    /**
103
     * The step name as defined in your workflow code.
104
     */
105
    name: string;
106
    /**
107
     * 1-indexed occurrence of this step name. Use when the same step name appears multiple times (e.g. in a loop).
108
     * @default 1
109
     */
110
    count?: number;
111
    /**
112
     * Step type filter. Use when different step types share the same name.
113
     */
114
    type?: 'do' | 'sleep' | 'waitForEvent';
115
  };
116
}
117
 
118
declare abstract class WorkflowInstance {
119
  public id: string;
120
 
121
  /**
122
   * Pause the instance.
123
   */
124
  public pause(): Promise<void>;
125
 
126
  /**
127
   * Resume the instance. If it is already running, an error will be thrown.
128
   */
129
  public resume(): Promise<void>;
130
 
131
  /**
132
   * Terminate the instance. If it is errored, terminated or complete, an error will be thrown.
133
   */
134
  public terminate(): Promise<void>;
135
 
136
  /**
137
   * Restart the instance. Optionally restart from a specific step, preserving
138
   * cached results for all steps before it.
139
   * @param options Options for the restart, including an optional step to restart from.
140
   */
141
  public restart(options?: WorkflowInstanceRestartOptions): Promise<void>;
142
 
143
  /**
144
   * Returns the current status of the instance.
145
   */
146
  public status(): Promise<InstanceStatus>;
147
 
148
  /**
149
   * Send an event to this instance.
150
   */
151
  public sendEvent({
152
    type,
153
    payload,
154
  }: {
155
    type: string;
156
    payload: unknown;
157
  }): Promise<void>;
158
}