@dontirun/state-machine-semaphore 0.0.1 → 0.1.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 (6) hide show
  1. package/.jsii +151 -92
  2. package/API.md +183 -63
  3. package/README.md +28 -34
  4. package/lib/index.d.ts +40 -19
  5. package/lib/index.js +79 -69
  6. package/package.json +1 -1
package/API.md CHANGED
@@ -2,43 +2,41 @@
2
2
 
3
3
  ## Constructs <a name="Constructs" id="Constructs"></a>
4
4
 
5
- ### SemaphoreGenerator <a name="SemaphoreGenerator" id="@dontirun/state-machine-semaphore.SemaphoreGenerator"></a>
5
+ ### Semaphore <a name="Semaphore" id="@dontirun/state-machine-semaphore.Semaphore"></a>
6
6
 
7
- Sets up up the DynamoDB table that stores the State Machine semaphores.
8
-
9
- Call `generateSemaphoredJob` to generate semaphored jobs.
7
+ Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions.
10
8
 
11
- #### Initializers <a name="Initializers" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer"></a>
9
+ #### Initializers <a name="Initializers" id="@dontirun/state-machine-semaphore.Semaphore.Initializer"></a>
12
10
 
13
11
  ```typescript
14
- import { SemaphoreGenerator } from '@dontirun/state-machine-semaphore'
12
+ import { Semaphore } from '@dontirun/state-machine-semaphore'
15
13
 
16
- new SemaphoreGenerator(scope: Construct, id: string, props?: SemaphoreGeneratorProps)
14
+ new Semaphore(scope: Construct, id: string, props: SemaphoreProps)
17
15
  ```
18
16
 
19
17
  | **Name** | **Type** | **Description** |
20
18
  | --- | --- | --- |
21
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
22
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
23
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.props">props</a></code> | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGeneratorProps">SemaphoreGeneratorProps</a></code> | *No description.* |
19
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
20
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
21
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.props">props</a></code> | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps">SemaphoreProps</a></code> | *No description.* |
24
22
 
25
23
  ---
26
24
 
27
- ##### `scope`<sup>Required</sup> <a name="scope" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.scope"></a>
25
+ ##### `scope`<sup>Required</sup> <a name="scope" id="@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.scope"></a>
28
26
 
29
27
  - *Type:* constructs.Construct
30
28
 
31
29
  ---
32
30
 
33
- ##### `id`<sup>Required</sup> <a name="id" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.id"></a>
31
+ ##### `id`<sup>Required</sup> <a name="id" id="@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.id"></a>
34
32
 
35
33
  - *Type:* string
36
34
 
37
35
  ---
38
36
 
39
- ##### `props`<sup>Optional</sup> <a name="props" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.Initializer.parameter.props"></a>
37
+ ##### `props`<sup>Required</sup> <a name="props" id="@dontirun/state-machine-semaphore.Semaphore.Initializer.parameter.props"></a>
40
38
 
41
- - *Type:* <a href="#@dontirun/state-machine-semaphore.SemaphoreGeneratorProps">SemaphoreGeneratorProps</a>
39
+ - *Type:* <a href="#@dontirun/state-machine-semaphore.SemaphoreProps">SemaphoreProps</a>
42
40
 
43
41
  ---
44
42
 
@@ -46,12 +44,14 @@ new SemaphoreGenerator(scope: Construct, id: string, props?: SemaphoreGeneratorP
46
44
 
47
45
  | **Name** | **Description** |
48
46
  | --- | --- |
49
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.toString">toString</a></code> | Returns a string representation of this construct. |
50
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob">generateSemaphoredJob</a></code> | Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions. |
47
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.toString">toString</a></code> | Returns a string representation of this construct. |
48
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.next">next</a></code> | Continue normal execution with the given state. |
49
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.prefixStates">prefixStates</a></code> | Prefix the IDs of all states in this state machine fragment. |
50
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.toSingleState">toSingleState</a></code> | Wrap all states in this state machine fragment up into a single state. |
51
51
 
52
52
  ---
53
53
 
54
- ##### `toString` <a name="toString" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.toString"></a>
54
+ ##### `toString` <a name="toString" id="@dontirun/state-machine-semaphore.Semaphore.toString"></a>
55
55
 
56
56
  ```typescript
57
57
  public toString(): string
@@ -59,63 +59,60 @@ public toString(): string
59
59
 
60
60
  Returns a string representation of this construct.
61
61
 
62
- ##### `generateSemaphoredJob` <a name="generateSemaphoredJob" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob"></a>
62
+ ##### `next` <a name="next" id="@dontirun/state-machine-semaphore.Semaphore.next"></a>
63
63
 
64
64
  ```typescript
65
- public generateSemaphoredJob(lockName: string, limit: number, job: IChainNextable, nextState: State, reuseLock?: boolean, comments?: boolean): StateMachineFragment
65
+ public next(next: IChainable): Chain
66
66
  ```
67
67
 
68
- Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions.
69
-
70
- ###### `lockName`<sup>Required</sup> <a name="lockName" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.lockName"></a>
68
+ Continue normal execution with the given state.
71
69
 
72
- - *Type:* string
70
+ ###### `next`<sup>Required</sup> <a name="next" id="@dontirun/state-machine-semaphore.Semaphore.next.parameter.next"></a>
73
71
 
74
- The name of the semaphore.
72
+ - *Type:* aws-cdk-lib.aws_stepfunctions.IChainable
75
73
 
76
74
  ---
77
75
 
78
- ###### `limit`<sup>Required</sup> <a name="limit" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.limit"></a>
79
-
80
- - *Type:* number
81
-
82
- The maximum number of concurrent executions for the given lock.
83
-
84
- ---
76
+ ##### `prefixStates` <a name="prefixStates" id="@dontirun/state-machine-semaphore.Semaphore.prefixStates"></a>
85
77
 
86
- ###### `job`<sup>Required</sup> <a name="job" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.job"></a>
78
+ ```typescript
79
+ public prefixStates(prefix?: string): StateMachineFragment
80
+ ```
87
81
 
88
- - *Type:* <a href="#@dontirun/state-machine-semaphore.IChainNextable">IChainNextable</a>
82
+ Prefix the IDs of all states in this state machine fragment.
89
83
 
90
- The job (or chained jobs) to be semaphored.
84
+ Use this to avoid multiple copies of the state machine all having the
85
+ same state IDs.
91
86
 
92
- ---
87
+ ###### `prefix`<sup>Optional</sup> <a name="prefix" id="@dontirun/state-machine-semaphore.Semaphore.prefixStates.parameter.prefix"></a>
93
88
 
94
- ###### `nextState`<sup>Required</sup> <a name="nextState" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.nextState"></a>
89
+ - *Type:* string
95
90
 
96
- - *Type:* aws-cdk-lib.aws_stepfunctions.State
91
+ The prefix to add.
97
92
 
98
- The State to go to after the semaphored job completes.
93
+ Will use construct ID by default.
99
94
 
100
95
  ---
101
96
 
102
- ###### `reuseLock`<sup>Optional</sup> <a name="reuseLock" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.reuseLock"></a>
103
-
104
- - *Type:* boolean
105
-
106
- Explicility allow the reuse of a named lock from a previously generated job.
97
+ ##### `toSingleState` <a name="toSingleState" id="@dontirun/state-machine-semaphore.Semaphore.toSingleState"></a>
107
98
 
108
- Throws an error if a different `limit` is specified. Default: false.
99
+ ```typescript
100
+ public toSingleState(options?: SingleStateOptions): Parallel
101
+ ```
109
102
 
110
- ---
103
+ Wrap all states in this state machine fragment up into a single state.
111
104
 
112
- ###### `comments`<sup>Optional</sup> <a name="comments" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.generateSemaphoredJob.parameter.comments"></a>
105
+ This can be used to add retry or error handling onto this state
106
+ machine fragment.
113
107
 
114
- - *Type:* boolean
108
+ Be aware that this changes the result of the inner state machine
109
+ to be an array with the result of the state machine in it. Adjust
110
+ your paths accordingly. For example, change 'outputPath' to
111
+ '$[0]'.
115
112
 
116
- Adds detailed comments to lock related states.
113
+ ###### `options`<sup>Optional</sup> <a name="options" id="@dontirun/state-machine-semaphore.Semaphore.toSingleState.parameter.options"></a>
117
114
 
118
- Significantly increases CloudFormation template size. Default: false.
115
+ - *Type:* aws-cdk-lib.aws_stepfunctions.SingleStateOptions
119
116
 
120
117
  ---
121
118
 
@@ -123,21 +120,21 @@ Significantly increases CloudFormation template size. Default: false.
123
120
 
124
121
  | **Name** | **Description** |
125
122
  | --- | --- |
126
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
123
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
127
124
 
128
125
  ---
129
126
 
130
- ##### ~~`isConstruct`~~ <a name="isConstruct" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.isConstruct"></a>
127
+ ##### ~~`isConstruct`~~ <a name="isConstruct" id="@dontirun/state-machine-semaphore.Semaphore.isConstruct"></a>
131
128
 
132
129
  ```typescript
133
- import { SemaphoreGenerator } from '@dontirun/state-machine-semaphore'
130
+ import { Semaphore } from '@dontirun/state-machine-semaphore'
134
131
 
135
- SemaphoreGenerator.isConstruct(x: any)
132
+ Semaphore.isConstruct(x: any)
136
133
  ```
137
134
 
138
135
  Checks if `x` is a construct.
139
136
 
140
- ###### `x`<sup>Required</sup> <a name="x" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.isConstruct.parameter.x"></a>
137
+ ###### `x`<sup>Required</sup> <a name="x" id="@dontirun/state-machine-semaphore.Semaphore.isConstruct.parameter.x"></a>
141
138
 
142
139
  - *Type:* any
143
140
 
@@ -149,11 +146,14 @@ Any object.
149
146
 
150
147
  | **Name** | **Type** | **Description** |
151
148
  | --- | --- | --- |
152
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGenerator.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
149
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
150
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.property.endStates">endStates</a></code> | <code>aws-cdk-lib.aws_stepfunctions.INextable[]</code> | The states to chain onto if this fragment is used. |
151
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.property.id">id</a></code> | <code>string</code> | Descriptive identifier for this chainable. |
152
+ | <code><a href="#@dontirun/state-machine-semaphore.Semaphore.property.startState">startState</a></code> | <code>aws-cdk-lib.aws_stepfunctions.State</code> | The start state of this state machine fragment. |
153
153
 
154
154
  ---
155
155
 
156
- ##### `node`<sup>Required</sup> <a name="node" id="@dontirun/state-machine-semaphore.SemaphoreGenerator.property.node"></a>
156
+ ##### `node`<sup>Required</sup> <a name="node" id="@dontirun/state-machine-semaphore.Semaphore.property.node"></a>
157
157
 
158
158
  ```typescript
159
159
  public readonly node: Node;
@@ -165,30 +165,148 @@ The tree node.
165
165
 
166
166
  ---
167
167
 
168
+ ##### `endStates`<sup>Required</sup> <a name="endStates" id="@dontirun/state-machine-semaphore.Semaphore.property.endStates"></a>
169
+
170
+ ```typescript
171
+ public readonly endStates: INextable[];
172
+ ```
173
+
174
+ - *Type:* aws-cdk-lib.aws_stepfunctions.INextable[]
175
+
176
+ The states to chain onto if this fragment is used.
177
+
178
+ ---
179
+
180
+ ##### `id`<sup>Required</sup> <a name="id" id="@dontirun/state-machine-semaphore.Semaphore.property.id"></a>
181
+
182
+ ```typescript
183
+ public readonly id: string;
184
+ ```
185
+
186
+ - *Type:* string
187
+
188
+ Descriptive identifier for this chainable.
189
+
190
+ ---
191
+
192
+ ##### `startState`<sup>Required</sup> <a name="startState" id="@dontirun/state-machine-semaphore.Semaphore.property.startState"></a>
193
+
194
+ ```typescript
195
+ public readonly startState: State;
196
+ ```
197
+
198
+ - *Type:* aws-cdk-lib.aws_stepfunctions.State
199
+
200
+ The start state of this state machine fragment.
201
+
202
+ ---
203
+
168
204
 
169
205
  ## Structs <a name="Structs" id="Structs"></a>
170
206
 
171
- ### SemaphoreGeneratorProps <a name="SemaphoreGeneratorProps" id="@dontirun/state-machine-semaphore.SemaphoreGeneratorProps"></a>
207
+ ### SemaphoreProps <a name="SemaphoreProps" id="@dontirun/state-machine-semaphore.SemaphoreProps"></a>
172
208
 
173
- Interface for creating a SemaphoreGenerator.
209
+ Interface for creating a Semaphore.
174
210
 
175
- #### Initializer <a name="Initializer" id="@dontirun/state-machine-semaphore.SemaphoreGeneratorProps.Initializer"></a>
211
+ #### Initializer <a name="Initializer" id="@dontirun/state-machine-semaphore.SemaphoreProps.Initializer"></a>
176
212
 
177
213
  ```typescript
178
- import { SemaphoreGeneratorProps } from '@dontirun/state-machine-semaphore'
214
+ import { SemaphoreProps } from '@dontirun/state-machine-semaphore'
179
215
 
180
- const semaphoreGeneratorProps: SemaphoreGeneratorProps = { ... }
216
+ const semaphoreProps: SemaphoreProps = { ... }
181
217
  ```
182
218
 
183
219
  #### Properties <a name="Properties" id="Properties"></a>
184
220
 
185
221
  | **Name** | **Type** | **Description** |
186
222
  | --- | --- | --- |
187
- | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreGeneratorProps.property.tableReadWriteCapacity">tableReadWriteCapacity</a></code> | <code><a href="#@dontirun/state-machine-semaphore.TableReadWriteCapacity">TableReadWriteCapacity</a></code> | Optionally set the DynamoDB table to have a specific read/write capacity with PROVISIONED billing. |
223
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.job">job</a></code> | <code><a href="#@dontirun/state-machine-semaphore.IChainNextable">IChainNextable</a></code> | The job (or chained jobs) to be semaphored. |
224
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.limit">limit</a></code> | <code>number</code> | The maximum number of concurrent executions for the given lock. |
225
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.lockName">lockName</a></code> | <code>string</code> | The name of the semaphore. |
226
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.nextState">nextState</a></code> | <code>aws-cdk-lib.aws_stepfunctions.State</code> | The State to go to after the semaphored job completes. |
227
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.comments">comments</a></code> | <code>boolean</code> | Add detailed comments to lock related states. |
228
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.reuseLock">reuseLock</a></code> | <code>boolean</code> | Explicility allow the reuse of a named lock from a previously generated job. |
229
+ | <code><a href="#@dontirun/state-machine-semaphore.SemaphoreProps.property.tableReadWriteCapacity">tableReadWriteCapacity</a></code> | <code><a href="#@dontirun/state-machine-semaphore.TableReadWriteCapacity">TableReadWriteCapacity</a></code> | Optionally set the DynamoDB table to have a specific read/write capacity with PROVISIONED billing. |
188
230
 
189
231
  ---
190
232
 
191
- ##### `tableReadWriteCapacity`<sup>Optional</sup> <a name="tableReadWriteCapacity" id="@dontirun/state-machine-semaphore.SemaphoreGeneratorProps.property.tableReadWriteCapacity"></a>
233
+ ##### `job`<sup>Required</sup> <a name="job" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.job"></a>
234
+
235
+ ```typescript
236
+ public readonly job: IChainNextable;
237
+ ```
238
+
239
+ - *Type:* <a href="#@dontirun/state-machine-semaphore.IChainNextable">IChainNextable</a>
240
+
241
+ The job (or chained jobs) to be semaphored.
242
+
243
+ ---
244
+
245
+ ##### `limit`<sup>Required</sup> <a name="limit" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.limit"></a>
246
+
247
+ ```typescript
248
+ public readonly limit: number;
249
+ ```
250
+
251
+ - *Type:* number
252
+
253
+ The maximum number of concurrent executions for the given lock.
254
+
255
+ ---
256
+
257
+ ##### `lockName`<sup>Required</sup> <a name="lockName" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.lockName"></a>
258
+
259
+ ```typescript
260
+ public readonly lockName: string;
261
+ ```
262
+
263
+ - *Type:* string
264
+
265
+ The name of the semaphore.
266
+
267
+ ---
268
+
269
+ ##### `nextState`<sup>Required</sup> <a name="nextState" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.nextState"></a>
270
+
271
+ ```typescript
272
+ public readonly nextState: State;
273
+ ```
274
+
275
+ - *Type:* aws-cdk-lib.aws_stepfunctions.State
276
+
277
+ The State to go to after the semaphored job completes.
278
+
279
+ ---
280
+
281
+ ##### `comments`<sup>Optional</sup> <a name="comments" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.comments"></a>
282
+
283
+ ```typescript
284
+ public readonly comments: boolean;
285
+ ```
286
+
287
+ - *Type:* boolean
288
+
289
+ Add detailed comments to lock related states.
290
+
291
+ Significantly increases CloudFormation template size. Default: false.
292
+
293
+ ---
294
+
295
+ ##### `reuseLock`<sup>Optional</sup> <a name="reuseLock" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.reuseLock"></a>
296
+
297
+ ```typescript
298
+ public readonly reuseLock: boolean;
299
+ ```
300
+
301
+ - *Type:* boolean
302
+
303
+ Explicility allow the reuse of a named lock from a previously generated job.
304
+
305
+ Throws an error if a different `limit` is specified. Default: false.
306
+
307
+ ---
308
+
309
+ ##### `tableReadWriteCapacity`<sup>Optional</sup> <a name="tableReadWriteCapacity" id="@dontirun/state-machine-semaphore.SemaphoreProps.property.tableReadWriteCapacity"></a>
192
310
 
193
311
  ```typescript
194
312
  public readonly tableReadWriteCapacity: TableReadWriteCapacity;
@@ -199,6 +317,8 @@ public readonly tableReadWriteCapacity: TableReadWriteCapacity;
199
317
 
200
318
  Optionally set the DynamoDB table to have a specific read/write capacity with PROVISIONED billing.
201
319
 
320
+ Note: This property can only be set on the first instantiation of a `Semaphore` per stack
321
+
202
322
  ---
203
323
 
204
324
  ### TableReadWriteCapacity <a name="TableReadWriteCapacity" id="@dontirun/state-machine-semaphore.TableReadWriteCapacity"></a>
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @dontirun/state-machine-semaphore
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/donti/state-machine-semaphore.svg)](https://www.npmjs.com/package/@donti%2Fstate-machine-semaphore)
3
+ [![npm version](https://img.shields.io/npm/v/@dontirun/state-machine-semaphore.svg)](https://img.shields.io/npm/v/@dontirun/state-machine-semaphore)
4
4
  [![PyPI version](https://img.shields.io/pypi/v/state-machine-semaphore.svg)](https://pypi.org/project/state-machine-semaphore)
5
5
  [![NuGet version](https://img.shields.io/nuget/v/Dontirun.StateMachineSemaphore)](https://www.nuget.org/packages/Dontirun.StateMachineSemaphore)
6
6
 
@@ -14,13 +14,9 @@ This construct is based off of [Justin Callison's](https://github.com/JustinCall
14
14
 
15
15
  ### Example 1) A state machine with a controlled job
16
16
 
17
- <table>
18
- <tr>
19
- <th>Code</th>
20
- <th>Definition</th>
21
- </tr>
22
- <tr>
23
- <td>
17
+ <details>
18
+
19
+ <summary>Click to see code</summary>
24
20
 
25
21
  ```typescript
26
22
  import { Function } from 'aws-cdk-lib/aws-lambda';
@@ -28,7 +24,7 @@ import { Duration, Stack, StackProps } from 'aws-cdk-lib';
28
24
  import { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';
29
25
  import { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';
30
26
  import { Construct } from 'constructs';
31
- import { SemaphoreGenerator } from '@dontirun/state-machine-semaphore';
27
+ import { Semaphore } from '@dontirun/state-machine-semaphore';
32
28
 
33
29
 
34
30
  export class CdkTestStack extends Stack {
@@ -43,9 +39,8 @@ export class CdkTestStack extends Stack {
43
39
 
44
40
  const afterContestedJob = new Succeed(this, 'Succeed');
45
41
 
46
- const generator = new SemaphoreGenerator(this, 'SemaphoreGenerator');
47
- const stateMachineFragment = generator.generateSemaphoredJob('life', 42, contestedJob, afterContestedJob);
48
-
42
+ const stateMachineFragment = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: afterContestedJob });
43
+
49
44
  new StateMachine(this, 'StateMachine', {
50
45
  definition: stateMachineFragment,
51
46
  });
@@ -53,23 +48,22 @@ export class CdkTestStack extends Stack {
53
48
  }
54
49
  ```
55
50
 
56
- </td>
57
- <td>
51
+ </details>
52
+
53
+
54
+ <details>
55
+
56
+ <summary>Click to see the state machine definition</summary>
58
57
 
59
58
  ![Example 1 Definition](./images/Example1_Graph_Edit.png)
60
- </td>
61
- </tr>
62
- </table>
59
+ </details>
60
+
63
61
 
64
62
  ### Example 2) A state machine with multiple semaphores
65
63
 
66
- <table>
67
- <tr>
68
- <th>Code</th>
69
- <th>Definition</th>
70
- </tr>
71
- <tr>
72
- <td>
64
+ <details>
65
+
66
+ <summary>Click to see code</summary>
73
67
 
74
68
  ```typescript
75
69
  import { Function } from 'aws-cdk-lib/aws-lambda';
@@ -77,7 +71,7 @@ import { Duration, Stack, StackProps } from 'aws-cdk-lib';
77
71
  import { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';
78
72
  import { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';
79
73
  import { Construct } from 'constructs';
80
- import { SemaphoreGenerator } from '@dontirun/state-machine-semaphore';
74
+ import { Semaphore } from '@dontirun/state-machine-semaphore';
81
75
 
82
76
 
83
77
  export class CdkTestStack extends Stack {
@@ -95,24 +89,24 @@ export class CdkTestStack extends Stack {
95
89
  })
96
90
  const afterContestedJob2 = new Succeed(this, 'Succeed');
97
91
 
98
- const generator = new SemaphoreGenerator(this, 'SemaphoreGenerator');
99
- const stateMachineFragment = generator.generateSemaphoredJob('life', 42, contestedJob, notContestedJob);
100
- const stateMachineFragment2 = generator.generateSemaphoredJob('liberty', 7, contestedJob2, afterContestedJob2);
92
+ const definition = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: notContestedJob })
93
+ .next(new Semaphore(stack, 'Semaphore2', { lockName: 'liberty', limit: 7, job: contestedJob2, nextState: afterContestedJob2 }));
101
94
 
102
95
  new StateMachine(this, 'StateMachine', {
103
- definition: stateMachineFragment.next(stateMachineFragment2),
96
+ definition: definition,
104
97
  });
105
98
  }
106
99
  }
107
100
  ```
108
101
 
109
- </td>
110
- <td>
102
+ </details>
103
+
104
+ <details>
105
+
106
+ <summary>Click to see the state machine definition</summary>
111
107
 
112
108
  ![Example 2 Definition](./images/Example2_Graph_Edit.png)
113
- </td>
114
- </tr>
115
- </table>
109
+ </details>
116
110
 
117
111
  ## API Reference
118
112
 
package/lib/index.d.ts CHANGED
@@ -1,11 +1,36 @@
1
1
  import { StateMachineFragment, State, IChainable, INextable } from 'aws-cdk-lib/aws-stepfunctions';
2
2
  import { Construct } from 'constructs';
3
3
  /**
4
- * Interface for creating a SemaphoreGenerator
4
+ * Interface for creating a Semaphore
5
5
  */
6
- export interface SemaphoreGeneratorProps {
6
+ export interface SemaphoreProps {
7
+ /**
8
+ * The name of the semaphore.
9
+ */
10
+ readonly lockName: string;
11
+ /**
12
+ * The maximum number of concurrent executions for the given lock.
13
+ */
14
+ readonly limit: number;
15
+ /**
16
+ * The job (or chained jobs) to be semaphored.
17
+ */
18
+ readonly job: IChainNextable;
19
+ /**
20
+ * The State to go to after the semaphored job completes.
21
+ */
22
+ readonly nextState: State;
23
+ /**
24
+ * Explicility allow the reuse of a named lock from a previously generated job. Throws an error if a different `limit` is specified. Default: false.
25
+ */
26
+ readonly reuseLock?: boolean;
27
+ /**
28
+ * Add detailed comments to lock related states. Significantly increases CloudFormation template size. Default: false.
29
+ */
30
+ readonly comments?: boolean;
7
31
  /**
8
32
  * Optionally set the DynamoDB table to have a specific read/write capacity with PROVISIONED billing.
33
+ * Note: This property can only be set on the first instantiation of a `Semaphore` per stack
9
34
  * @default PAY_PER_REQUEST
10
35
  */
11
36
  readonly tableReadWriteCapacity?: TableReadWriteCapacity;
@@ -20,28 +45,24 @@ export interface TableReadWriteCapacity {
20
45
  export interface IChainNextable extends IChainable, INextable {
21
46
  }
22
47
  /**
23
- * Sets up up the DynamoDB table that stores the State Machine semaphores.
24
- * Call `generateSemaphoredJob` to generate semaphored jobs.
48
+ * Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions.
25
49
  */
26
- export declare class SemaphoreGenerator extends Construct {
50
+ export declare class Semaphore extends StateMachineFragment {
27
51
  /**
28
- * The DynamoDB table used to store semaphores.
52
+ * The names and associated concurrency limits and number of uses of the sempahores.
29
53
  */
30
- private semaphoreTable;
54
+ private static semaphoreTracker;
31
55
  /**
32
- * The names and associated concurrency limits and number of uses of the sempahores.
56
+ * The DynamoDB table used to store semaphores.
33
57
  */
34
- private semaphoreTracker;
35
- constructor(scope: Construct, id: string, props?: SemaphoreGeneratorProps);
58
+ private semaphoreTable;
36
59
  /**
37
- * Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions.
38
- * @param lockName The name of the semaphore.
39
- * @param limit The maximum number of concurrent executions for the given lock.
40
- * @param job The job (or chained jobs) to be semaphored.
41
- * @param nextState The State to go to after the semaphored job completes.
42
- * @param reuseLock Explicility allow the reuse of a named lock from a previously generated job. Throws an error if a different `limit` is specified. Default: false.
43
- * @param comments Adds detailed comments to lock related states. Significantly increases CloudFormation template size. Default: false.
44
- * @returns A StateMachineFragment that can chained to other states in the State Machine.
60
+ * The DynamoDB table used to store semaphores.
45
61
  */
46
- generateSemaphoredJob(lockName: string, limit: number, job: IChainNextable, nextState: State, reuseLock?: boolean, comments?: boolean): StateMachineFragment;
62
+ private tableName;
63
+ readonly startState: State;
64
+ readonly endStates: INextable[];
65
+ constructor(scope: Construct, id: string, props: SemaphoreProps);
66
+ private setUpMap;
67
+ private ensureTable;
47
68
  }