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