@dontirun/state-machine-semaphore 0.0.1 → 0.1.2

package/.gitattributes

@@ -16,6 +16,7 @@
 /.projen/deps.json linguist-generated
 /.projen/files.json linguist-generated
 /.projen/tasks.json linguist-generated
+/API.md linguist-generated
 /LICENSE linguist-generated
 /package.json linguist-generated
 /tsconfig.dev.json linguist-generated

package/.jsii

@@ -2989,7 +2989,7 @@
   },
   "name": "@dontirun/state-machine-semaphore",
   "readme": {
-    "markdown": "# @dontirun/state-machine-semaphore\n\n[![npm version](https://img.shields.io/npm/v/donti/state-machine-semaphore.svg)](https://www.npmjs.com/package/@donti%2Fstate-machine-semaphore)\n[![PyPI version](https://img.shields.io/pypi/v/state-machine-semaphore.svg)](https://pypi.org/project/state-machine-semaphore)\n[![NuGet version](https://img.shields.io/nuget/v/Dontirun.StateMachineSemaphore)](https://www.nuget.org/packages/Dontirun.StateMachineSemaphore)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=%40dontirun%2Fstate-machine-semaphore)](https://constructs.dev/packages/@dontirun/state-machine-semaphore)\n\nAn [aws-cdk](https://github.com/aws/aws-cdk) construct that enables you to use AWS Step Functions to control concurrency in your distributed system. You can use this construct to distributed state machine semaphores to control concurrent invocations of contentious work.\n\nThis construct is based off of [Justin Callison's](https://github.com/JustinCallison) example [code](https://github.com/aws-samples/aws-stepfunctions-examples/blob/main/sam/app-control-concurrency-with-dynamodb/statemachines/dynamodb-semaphore.asl.json). Make sure to check out Justin's [blogpost](https://aws.amazon.com/blogs/compute/controlling-concurrency-in-distributed-systems-using-aws-step-functions/) to learn about how the system works.\n\n## Examples\n\n### Example 1) A state machine with a controlled job\n\n<table>\n<tr>\n<th>Code</th>\n<th>Definition</th>\n</tr>\n<tr>\n<td>\n\n```typescript\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { Duration, Stack, StackProps } from 'aws-cdk-lib';\nimport { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';\nimport { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';\nimport { Construct } from 'constructs';\nimport { SemaphoreGenerator } from '@dontirun/state-machine-semaphore';\n\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n\n    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),\n    }).next(new Wait(this, 'Wait', { time: WaitTime.duration(Duration.seconds(7)) }))\n      .next(new Wait(this, 'AnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }))\n      .next(new Wait(this, 'YetAnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }));\n\n    const afterContestedJob = new Succeed(this, 'Succeed');\n\n    const generator = new SemaphoreGenerator(this, 'SemaphoreGenerator');\n    const stateMachineFragment = generator.generateSemaphoredJob('life', 42, contestedJob, afterContestedJob);\n\n    new StateMachine(this, 'StateMachine', {\n      definition: stateMachineFragment,\n    });\n  }\n}\n```\n\n</td>\n<td>\n\n![Example 1 Definition](./images/Example1_Graph_Edit.png)\n</td>\n</tr>\n</table>\n\n### Example 2) A state machine with multiple semaphores\n\n<table>\n<tr>\n<th>Code</th>\n<th>Definition</th>\n</tr>\n<tr>\n<td>\n\n```typescript\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { Duration, Stack, StackProps } from 'aws-cdk-lib';\nimport { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';\nimport { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';\nimport { Construct } from 'constructs';\nimport { SemaphoreGenerator } from '@dontirun/state-machine-semaphore';\n\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n\n    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),\n    })\n    const notContestedJob = new LambdaInvoke(this, 'NotContestedJob', {\n      lambdaFunction: Function.fromFunctionName(this, 'NotContestedJobFunction', 'cooler-function'),\n    })\n    const contestedJob2 = new LambdaInvoke(this, 'ContestedJobPart2', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart2', 'coolest-function'),\n    })\n    const afterContestedJob2 = new Succeed(this, 'Succeed');\n\n    const generator = new SemaphoreGenerator(this, 'SemaphoreGenerator');\n    const stateMachineFragment = generator.generateSemaphoredJob('life', 42, contestedJob, notContestedJob);\n    const stateMachineFragment2 = generator.generateSemaphoredJob('liberty', 7, contestedJob2, afterContestedJob2);\n\n    new StateMachine(this, 'StateMachine', {\n      definition: stateMachineFragment.next(stateMachineFragment2),\n    });\n  }\n}\n```\n\n</td>\n<td>\n\n![Example 2 Definition](./images/Example2_Graph_Edit.png)\n</td>\n</tr>\n</table>\n\n## API Reference\n\nSee [API.md](./API.md).\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
+    "markdown": "# @dontirun/state-machine-semaphore\n\n[![npm version](https://img.shields.io/npm/v/@dontirun/state-machine-semaphore.svg)](https://img.shields.io/npm/v/@dontirun/state-machine-semaphore)\n[![PyPI version](https://img.shields.io/pypi/v/state-machine-semaphore.svg)](https://pypi.org/project/state-machine-semaphore)\n[![NuGet version](https://img.shields.io/nuget/v/Dontirun.StateMachineSemaphore)](https://www.nuget.org/packages/Dontirun.StateMachineSemaphore)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=%40dontirun%2Fstate-machine-semaphore)](https://constructs.dev/packages/@dontirun/state-machine-semaphore)\n\nAn [aws-cdk](https://github.com/aws/aws-cdk) construct that enables you to use AWS Step Functions to control concurrency in your distributed system. You can use this construct to distributed state machine semaphores to control concurrent invocations of contentious work.\n\nThis construct is based off of [Justin Callison's](https://github.com/JustinCallison) example [code](https://github.com/aws-samples/aws-stepfunctions-examples/blob/main/sam/app-control-concurrency-with-dynamodb/statemachines/dynamodb-semaphore.asl.json). Make sure to check out Justin's [blogpost](https://aws.amazon.com/blogs/compute/controlling-concurrency-in-distributed-systems-using-aws-step-functions/) to learn about how the system works.\n\n## Examples\n\n### Example 1) A state machine with a controlled job\n\n<details>\n\n<summary>Click to see code</summary>\n\n```typescript\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { Duration, Stack, StackProps } from 'aws-cdk-lib';\nimport { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';\nimport { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';\nimport { Construct } from 'constructs';\nimport { Semaphore } from '@dontirun/state-machine-semaphore';\n\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n\n    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),\n    }).next(new Wait(this, 'Wait', { time: WaitTime.duration(Duration.seconds(7)) }))\n      .next(new Wait(this, 'AnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }))\n      .next(new Wait(this, 'YetAnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }));\n\n    const afterContestedJob = new Succeed(this, 'Succeed');\n\n    const stateMachineFragment = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: afterContestedJob });\n\n    new StateMachine(this, 'StateMachine', {\n      definition: stateMachineFragment,\n    });\n  }\n}\n```\n\n</details>\n\n\n<details>\n\n<summary>Click to see the state machine definition</summary>\n\n![Example 1 Definition](./images/Example1_Graph_Edit.png)\n</details>\n\n\n### Example 2) A state machine with multiple semaphores\n\n<details>\n\n<summary>Click to see code</summary>\n\n```typescript\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { Duration, Stack, StackProps } from 'aws-cdk-lib';\nimport { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';\nimport { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';\nimport { Construct } from 'constructs';\nimport { Semaphore } from '@dontirun/state-machine-semaphore';\n\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n\n    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),\n    })\n    const notContestedJob = new LambdaInvoke(this, 'NotContestedJob', {\n      lambdaFunction: Function.fromFunctionName(this, 'NotContestedJobFunction', 'cooler-function'),\n    })\n    const contestedJob2 = new LambdaInvoke(this, 'ContestedJobPart2', {\n      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart2', 'coolest-function'),\n    })\n    const afterContestedJob2 = new Succeed(this, 'Succeed');\n\n    const definition = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: notContestedJob })\n      .next(new Semaphore(stack, 'Semaphore2', { lockName: 'liberty', limit: 7, job: contestedJob2, nextState: afterContestedJob2 }));\n\n    new StateMachine(this, 'StateMachine', {\n      definition: definition,\n    });\n  }\n}\n```\n\n</details>\n\n<details>\n\n<summary>Click to see the state machine definition</summary>\n\n![Example 2 Definition](./images/Example2_Graph_Edit.png)\n</details>\n\n## API Reference\n\nSee [API.md](./API.md).\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -3023,27 +3023,26 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/index.ts",
-        "line": 31
+        "line": 57
       },
       "name": "IChainNextable",
       "symbolId": "src/index:IChainNextable"
     },
-    "@dontirun/state-machine-semaphore.SemaphoreGenerator": {
+    "@dontirun/state-machine-semaphore.Semaphore": {
       "assembly": "@dontirun/state-machine-semaphore",
-      "base": "constructs.Construct",
+      "base": "aws-cdk-lib.aws_stepfunctions.StateMachineFragment",
       "docs": {
-        "remarks": "Call `generateSemaphoredJob` to generate semaphored jobs.",
         "stability": "stable",
-        "summary": "Sets up up the DynamoDB table that stores the State Machine semaphores."
+        "summary": "Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions."
       },
-      "fqn": "@dontirun/state-machine-semaphore.SemaphoreGenerator",
+      "fqn": "@dontirun/state-machine-semaphore.Semaphore",
       "initializer": {
         "docs": {
           "stability": "stable"
         },
         "locationInModule": {
           "filename": "src/index.ts",
-          "line": 49
+          "line": 83
         },
         "parameters": [
           {
@@ -3060,9 +3059,8 @@
           },
           {
             "name": "props",
-            "optional": true,
             "type": {
-              "fqn": "@dontirun/state-machine-semaphore.SemaphoreGeneratorProps"
+              "fqn": "@dontirun/state-machine-semaphore.SemaphoreProps"
             }
           }
         ]
@@ -3070,116 +3068,177 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/index.ts",
-        "line": 37
+        "line": 63
       },
-      "methods": [
+      "name": "Semaphore",
+      "properties": [
         {
           "docs": {
-            "returns": "A StateMachineFragment that can chained to other states in the State Machine.",
             "stability": "stable",
-            "summary": "Generates a semaphore for a StepFunction job (or chained set of jobs) to limit parallelism across executions."
+            "summary": "The states to chain onto if this fragment is used."
           },
+          "immutable": true,
           "locationInModule": {
             "filename": "src/index.ts",
-            "line": 73
+            "line": 80
           },
-          "name": "generateSemaphoredJob",
-          "parameters": [
-            {
-              "docs": {
-                "summary": "The name of the semaphore."
-              },
-              "name": "lockName",
-              "type": {
-                "primitive": "string"
-              }
-            },
-            {
-              "docs": {
-                "summary": "The maximum number of concurrent executions for the given lock."
-              },
-              "name": "limit",
-              "type": {
-                "primitive": "number"
-              }
-            },
-            {
-              "docs": {
-                "summary": "The job (or chained jobs) to be semaphored."
-              },
-              "name": "job",
-              "type": {
-                "fqn": "@dontirun/state-machine-semaphore.IChainNextable"
-              }
-            },
-            {
-              "docs": {
-                "summary": "The State to go to after the semaphored job completes."
-              },
-              "name": "nextState",
-              "type": {
-                "fqn": "aws-cdk-lib.aws_stepfunctions.State"
-              }
-            },
-            {
-              "docs": {
-                "remarks": "Throws an error if a different `limit` is specified. Default: false.",
-                "summary": "Explicility allow the reuse of a named lock from a previously generated job."
-              },
-              "name": "reuseLock",
-              "optional": true,
-              "type": {
-                "primitive": "boolean"
-              }
-            },
-            {
-              "docs": {
-                "remarks": "Significantly increases CloudFormation template size. Default: false.",
-                "summary": "Adds detailed comments to lock related states."
+          "name": "endStates",
+          "overrides": "aws-cdk-lib.aws_stepfunctions.StateMachineFragment",
+          "type": {
+            "collection": {
+              "elementtype": {
+                "fqn": "aws-cdk-lib.aws_stepfunctions.INextable"
               },
-              "name": "comments",
-              "optional": true,
-              "type": {
-                "primitive": "boolean"
-              }
-            }
-          ],
-          "returns": {
-            "type": {
-              "fqn": "aws-cdk-lib.aws_stepfunctions.StateMachineFragment"
+              "kind": "array"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "The start state of this state machine fragment."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 79
+          },
+          "name": "startState",
+          "overrides": "aws-cdk-lib.aws_stepfunctions.StateMachineFragment",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_stepfunctions.State"
+          }
         }
       ],
-      "name": "SemaphoreGenerator",
-      "symbolId": "src/index:SemaphoreGenerator"
+      "symbolId": "src/index:Semaphore"
     },
-    "@dontirun/state-machine-semaphore.SemaphoreGeneratorProps": {
+    "@dontirun/state-machine-semaphore.SemaphoreProps": {
       "assembly": "@dontirun/state-machine-semaphore",
       "datatype": true,
       "docs": {
         "stability": "stable",
-        "summary": "Interface for creating a SemaphoreGenerator."
+        "summary": "Interface for creating a Semaphore."
       },
-      "fqn": "@dontirun/state-machine-semaphore.SemaphoreGeneratorProps",
+      "fqn": "@dontirun/state-machine-semaphore.SemaphoreProps",
       "kind": "interface",
       "locationInModule": {
         "filename": "src/index.ts",
-        "line": 10
+        "line": 11
       },
-      "name": "SemaphoreGeneratorProps",
+      "name": "SemaphoreProps",
       "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The job (or chained jobs) to be semaphored."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 23
+          },
+          "name": "job",
+          "type": {
+            "fqn": "@dontirun/state-machine-semaphore.IChainNextable"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The maximum number of concurrent executions for the given lock."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 19
+          },
+          "name": "limit",
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The name of the semaphore."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 15
+          },
+          "name": "lockName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The State to go to after the semaphored job completes."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 27
+          },
+          "name": "nextState",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_stepfunctions.State"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Significantly increases CloudFormation template size. Default: false.",
+            "stability": "stable",
+            "summary": "Add detailed comments to lock related states."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 35
+          },
+          "name": "comments",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Throws an error if a different `limit` is specified. Default: false.",
+            "stability": "stable",
+            "summary": "Explicility allow the reuse of a named lock from a previously generated job."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/index.ts",
+            "line": 31
+          },
+          "name": "reuseLock",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
         {
           "abstract": true,
           "docs": {
             "default": "PAY_PER_REQUEST",
+            "remarks": "Note: This property can only be set on the first instantiation of a `Semaphore` per stack",
             "stability": "stable",
             "summary": "Optionally set the DynamoDB table to have a specific read/write capacity with PROVISIONED billing."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/index.ts",
-            "line": 15
+            "line": 41
           },
           "name": "tableReadWriteCapacity",
           "optional": true,
@@ -3188,7 +3247,7 @@
           }
         }
       ],
-      "symbolId": "src/index:SemaphoreGeneratorProps"
+      "symbolId": "src/index:SemaphoreProps"
     },
     "@dontirun/state-machine-semaphore.TableReadWriteCapacity": {
       "assembly": "@dontirun/state-machine-semaphore",
@@ -3201,7 +3260,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/index.ts",
-        "line": 21
+        "line": 47
       },
       "name": "TableReadWriteCapacity",
       "properties": [
@@ -3213,7 +3272,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/index.ts",
-            "line": 22
+            "line": 48
           },
           "name": "readCapacity",
           "type": {
@@ -3228,7 +3287,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/index.ts",
-            "line": 23
+            "line": 49
           },
           "name": "writeCapacity",
           "type": {
@@ -3239,6 +3298,6 @@
       "symbolId": "src/index:TableReadWriteCapacity"
     }
   },
-  "version": "0.0.1",
-  "fingerprint": "rtZDjzZsKq4BcpOi5+RDr3/GYKk2imgx9sRer+WXJ8s="
+  "version": "0.1.2",
+  "fingerprint": "p4nPFtVXcp81mfWyJDlagzlkE+ZU5HSugIVg4lM7fFQ="
 }