@celljs/retry 4.6.1 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.en.md +196 -0
  2. package/package.json +2 -2
package/README.en.md ADDED
@@ -0,0 +1,196 @@
1
+ # Cell - Retry Component
2
+
3
+ This project provides retry support for Cell applications. It is used in Cell AI and other applications.
4
+
5
+ The NPM package for this library is:
6
+
7
+ ```bash
8
+ @celljs/retry
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ This section provides a quick introduction on how to get started with Cell Retry.
14
+
15
+ ### Example
16
+
17
+ The following example shows how to use Cell Retry:
18
+
19
+ ```typescript
20
+
21
+ @Component()
22
+ export class Service {
23
+ @Autowired(RetryOperations)
24
+ protected retryOperations: RetryOperations;
25
+
26
+ service(): void {
27
+ this.retryOperations.execute(async () => {
28
+ // do something
29
+ },
30
+ {
31
+ maxAttempts: 3,
32
+ timeout: 1000,
33
+ recoveryCallback: async () => {
34
+ // recovery logic here
35
+ }
36
+ });
37
+ }
38
+ }
39
+ ```
40
+
41
+ This example retries at most three times after the first attempt (`maxAttempts` is the number of retries, not including the first, so at most four executions total). If still unsuccessful, it calls `recoveryCallback`, whose return value becomes the result of `execute`. With no recovery callback or if it also fails, `execute` throws `RetryError` with `cause` being the last error. The `execute` method has various options to include or exclude error types, limit retry attempts, and set backoff strategies.
42
+
43
+ ## Installation
44
+
45
+ ```bash
46
+ npm install @celljs/retry
47
+ ```
48
+
49
+ ## Features and API
50
+
51
+ This section discusses the features of Cell Retry and shows how to use its API.
52
+
53
+ ### Using `RetryOperations`
54
+
55
+ To make processing more robust and less prone to failure, sometimes automatically retrying failed operations can succeed on subsequent attempts. Errors suitable for this approach are typically transient. For example, remote calls to web services or RMI services that fail due to network problems or database deadlocks (such as `DeadLockLoserError`) may resolve in a short time. To automatically retry such operations, Cell Retry provides the `RetryOperations` strategy. The `RetryOperations` interface is defined as follows:
56
+
57
+ ```typescript
58
+ /**
59
+ * RetryOperations interface represents the operation to retry tasks with different options.
60
+ */
61
+ export interface RetryOperations {
62
+ /**
63
+ * Execute a callback function with the given options.
64
+ *
65
+ * @template T - The return type of the callback function.
66
+ * @param {RetryCallback<T>} callback - The callback function to execute.
67
+ * @param {RetryOptions<T>} options - Options for the retry task.
68
+ * @returns {Promise<T>} - The result of the callback function
69
+ * @throws {RetryError} - An error occurred during retrying.
70
+ * @example
71
+ * const result = await retryOperations.execute(async () => {
72
+ * // do something
73
+ * }, { maxAttempts: 3, timeout: 1000 });
74
+ * console.log(result);
75
+ * @example
76
+ * const result = await retryOperations.execute(async () => {
77
+ * // do something
78
+ * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000 } });
79
+ * console.log(result);
80
+ * @example
81
+ * const result = await retryOperations.execute(async () => {
82
+ * // do something
83
+ * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2 } });
84
+ * console.log(result);
85
+ * @example
86
+ * const result = await retryOperations.execute(async () => {
87
+ * // do something
88
+ * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2, random: true } });
89
+ * console.log(result);
90
+ * @example
91
+ * const result = await retryOperations.execute(async () => {
92
+ * // do something
93
+ * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2, random: true, maxDelay: 5000 } });
94
+ * console.log(result);
95
+ */
96
+ execute<T>(callback: RetryCallback<T>, options?: RetryOptions<T>): Promise<T>;
97
+ }
98
+ ```
99
+
100
+ A basic callback function is a simple interface that allows you to insert some business logic for retry:
101
+
102
+ ```typescript
103
+ export interface RetryCallback<T> {
104
+ (): Promise<T>;
105
+ }
106
+ ```
107
+
108
+ The callback function will be attempted, and if it fails (throws an error), it will retry until it succeeds or the implementation decides to stop.
109
+
110
+ The following example shows how to use it:
111
+
112
+ ```typescript
113
+ @Component()
114
+ export class Service {
115
+ @Autowired(RetryOperations)
116
+ protected retryOperations: RetryOperations;
117
+
118
+ service(): void {
119
+ this.retryOperations.execute(async () => {
120
+ // do something
121
+ },
122
+ {
123
+ maxAttempts: 3,
124
+ timeout: 1000,
125
+ backOffOptions: {
126
+ delay: 1000,
127
+ multiplier: 2,
128
+ random: true,
129
+ maxDelay: 5000
130
+ },
131
+ });
132
+ }
133
+ }
134
+ ```
135
+
136
+ In the example above, we execute the `service` method with at most three retries. The `execute` method has various options to include or exclude error types, limit retry attempts, and set backoff strategies.
137
+
138
+ ### Using `RetryContext`
139
+
140
+ The method parameter of `RetryCallback` is a `RetryContext`. Many callbacks ignore the context. However, if needed, you can use it as a property bag to store data during iterations. It also has some useful properties, such as `retryCount`.
141
+
142
+ ### Using `RecoveryCallback`
143
+
144
+ When retries are exhausted, `RetryOperations` can pass control to a different callback function: `RecoveryCallback`. To use this feature, the client can pass the callback function together to the same method, as shown in the example below:
145
+
146
+ ```typescript
147
+ @Component()
148
+ export class Service {
149
+ @Autowired(RetryOperations)
150
+ protected retryOperations: RetryOperations;
151
+
152
+ service(): void {
153
+ this.retryOperations.execute(async () => {
154
+ // do something
155
+ },
156
+ {
157
+ maxAttempts: 3,
158
+ timeout: 1000,
159
+ recoveryCallback: async () => {
160
+ // recovery logic here
161
+ }
162
+ });
163
+ }
164
+ }
165
+ ```
166
+
167
+ If the business logic does not succeed before the template decides to stop, the client has a chance to do some alternative processing through the recovery callback function.
168
+
169
+ ## Retry Strategies
170
+
171
+ Inside `RetryOperations`, the retry or failure decision in the `execute` method is determined by `RetryPolicy`. `RetryOperations` is responsible for creating `RetryContext` and passing it to `RetryCallback` on each attempt. After the callback fails, `RetryOperations` must call `RetryPolicy` to ask it to update the state (stored in `RetryContext`). Then it asks the policy whether another attempt can be made. If another attempt cannot be made (for example, a limit is reached or a timeout is detected), the policy is also responsible for identifying the exhausted state, but not for handling the exception. `RetryOperations` throws the original exception, which is `RetryError` in this case.
172
+ > *Tip:* Failure is inherently either retryable or not retryable—if the same exception is always thrown from business logic, retrying it is useless. Therefore, you should not retry on all exception types. Instead, try to focus only on exceptions you expect to be retryable. For business logic, more aggressive retrying usually will not hurt, but it is wasteful because if failure is deterministic, you are wasting time retrying something you know is fatal.
173
+
174
+ Cell Retry provides a generic `RetryPolicy` implementation. This implementation provides options for the maximum number of retries, timeouts, exception types, and more to control retry behavior.
175
+
176
+ ## Backoff Strategies
177
+
178
+ When retrying after a temporary failure, waiting a while before trying again is usually helpful, because (usually) the failure is caused by something that can only be resolved by waiting. If `RetryCallback` fails, `RetryOperations` can pause execution according to `BackoffPolicy`. The following listing shows the definition of the `BackoffPolicy` interface:
179
+
180
+ ```typescript
181
+ export interface BackOffPolicy {
182
+ start(ctx: RetryContext): Promise<BackOffContext>;
183
+ backOff(ctx: BackOffContext): Promise<void>;
184
+ }
185
+ ```
186
+
187
+ `BackoffPolicy` can be freely implemented in any way to backoff. The policies provided by Cell Retry all use `timeout`. A common use case is exponentially increasing wait periods for backoff to avoid two retries entering lockstep and both failing (a lesson learned from Ethernet). Cell Retry also provides a version with a randomized delay strategy, which is useful for avoiding resonance between related failures in complex systems.
188
+
189
+ The default `BackOffPolicy` calculates the wait time in milliseconds between two attempts based on `backOffOptions`:
190
+
191
+ | Option | Wait Time |
192
+ | --- | --- |
193
+ | `backOffOptions` not set | no wait |
194
+ | only `delay` (default 100) | wait `delay` each time |
195
+ | `multiplier` | Multiply by `multiplier` each time (if `random: true`, randomly pick between the previous and previous multiplied by `multiplier`). Does not exceed `maxDelay`; if `maxDelay` is not set, the limit is 30000 (`DEFAULT_MAX_DELAY`). |
196
+ | `maxDelay` with `multiplier` not set | Randomly pick between `delay` and `maxDelay`. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celljs/retry",
3
- "version": "4.6.1",
3
+ "version": "4.7.0",
4
4
  "description": "",
5
5
  "keywords": [
6
6
  "cell-component"
@@ -31,7 +31,7 @@
31
31
  "watch": "tsc -b -w --preserveWatchOutput"
32
32
  },
33
33
  "dependencies": {
34
- "@celljs/core": "4.6.1"
34
+ "@celljs/core": "4.7.0"
35
35
  },
36
36
  "publishConfig": {
37
37
  "access": "public"