feat: bring workflows (wip)

.github/workflows/canary.yaml

@@ -791,6 +791,32 @@ jobs:
           command: npm i -g winglang --loglevel verbose
           timeout_minutes: 3
       - name: Install dependencies
+        run: npm install --include=dev
+        working-directory: websockets
+      - name: Test
+        run: wing test
+        working-directory: websockets
+  canary-workflows:
+    name: Test workflows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          sparse-checkout: workflows
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org
+      - name: Install winglang
+        run: npm i -g winglang
+      - name: Install dependencies
+        run: npm install --include=dev
+        working-directory: workflows
+      - name: Test
+        run: wing test
+        working-directory: workflows
         uses: nick-fields/retry@v3
         with:
           max_attempts: 3

.github/workflows/pull-request-lint.yaml

@@ -49,6 +49,7 @@ jobs:
             tsoa
             vite
             websockets
+            workflows
           subjectPattern: ^[^A-Z][^:]+[^.]$
           subjectPatternError: Subject must start with a lowercase, should not include ':'
             and should not end with a period

.github/workflows/workflows-pull.yaml

@@ -0,0 +1,29 @@
+name: workflows-pull
+on:
+  pull_request:
+    paths:
+      - workflows/**
+jobs:
+  build-workflows:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          sparse-checkout: workflows
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org
+      - name: Install winglang
+        run: npm i -g winglang
+      - name: Install dependencies
+        run: npm install --include=dev
+        working-directory: workflows
+      - name: Test
+        run: wing test
+        working-directory: workflows
+      - name: Pack
+        run: wing pack
+        working-directory: workflows

.github/workflows/workflows-release.yaml

@@ -0,0 +1,54 @@
+name: workflows-release
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - workflows/**
+      - "!workflows/package-lock.json"
+jobs:
+  build-workflows:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          sparse-checkout: workflows
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org
+      - name: Install winglang
+        run: npm i -g winglang
+      - name: Install dependencies
+        run: npm install --include=dev
+        working-directory: workflows
+      - name: Test
+        run: wing test
+        working-directory: workflows
+      - name: Pack
+        run: wing pack
+        working-directory: workflows
+      - name: Get package version
+        run: echo WINGLIB_VERSION=$(node -p "require('./package.json').version") >>
+          "$GITHUB_ENV"
+        working-directory: workflows
+      - name: Publish
+        run: npm publish --access=public --registry https://registry.npmjs.org --tag
+          latest *.tgz
+        working-directory: workflows
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Tag commit
+        uses: tvdias/github-tagger@v0.0.1
+        with:
+          repo-token: ${{ secrets.PROJEN_GITHUB_TOKEN }}
+          tag: workflows-v${{ env.WINGLIB_VERSION }}
+      - name: GitHub release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: workflows v${{ env.WINGLIB_VERSION }}
+          tag_name: workflows-v${{ env.WINGLIB_VERSION }}
+          files: "*.tgz"
+          token: ${{ secrets.PROJEN_GITHUB_TOKEN }}

.mergify.yml

@@ -107,6 +107,9 @@ pull_request_rules:
       - -check-failure=build-websockets
       - -check-pending=build-websockets
       - -check-stale=build-websockets
+      - -check-failure=build-workflows
+      - -check-pending=build-workflows
+      - -check-stale=build-workflows
   - name: requires manual merge
     conditions:
       - files=.mergify.yml
@@ -198,6 +201,9 @@ pull_request_rules:
       - -check-failure=build-websockets
       - -check-pending=build-websockets
       - -check-stale=build-websockets
+      - -check-failure=build-workflows
+      - -check-pending=build-workflows
+      - -check-stale=build-workflows
     actions:
       comment:
         message: Thank you for contributing! Your pull request contains mergify

README.md

@@ -37,6 +37,7 @@ publishing them for you.
 | [tsoa](./tsoa) | [@winglibs/tsoa](https://www.npmjs.com/package/@winglibs/tsoa) | sim |
 | [vite](./vite) | [@winglibs/vite](https://www.npmjs.com/package/@winglibs/vite) | sim, tf-aws |
 | [websockets](./websockets) | [@winglibs/websockets](https://www.npmjs.com/package/@winglibs/websockets) | awscdk, sim, tf-aws |
+| [workflows](./workflows) | [@winglibs/workflows](https://www.npmjs.com/package/@winglibs/workflows) | sim |
 
 _Generated with `mkrepo.sh`. To update the list of supported platforms for a winglib, please update the "wing" section in its package.json file._
 

workflows/.gitignore

@@ -0,0 +1,2 @@
+target/
+node_modules/

workflows/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Wing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workflows/README.md

@@ -0,0 +1,87 @@
+# Workflows
+
+> MATURITY: experimental and not finished yet
+
+A durable workflows library for Wing.
+
+## Prerequisites
+
+* [winglang](https://winglang.io).
+
+## Installation
+
+```sh
+npm i @winglibs/workflows
+```
+
+## Usage
+
+```js
+bring workflows;
+
+let wf = new workflows.Workflow([
+  // steps... 
+]);'
+```
+
+We currently support two types of steps:
+
+1. `workflow.steps.execute()` - runs an inflight closure sequentially
+2. `workflow.steps.check()` - runs an inflight predicate and branches based on the result (true/false)
+
+## Preflight API
+
+* `onSuccess(cb: inflight (Json?): void)` - calls `cb` when the workflow finishes successfully.
+* `onError(cb: inflight (Json?): void)` - calls `cb` when one of the workflow steps throws an error.
+
+## Inflight API
+
+* `inflight start(ctx: Json?)` - starts the workflow with an initial context.
+* `inflight join(opts: util.WaitUntilProps?)` - waits until the workflow is complete. If an error is thrown, this method will throw.
+* `inflight status(): Status` - returns the current status of the workflow.
+* `inflight ctx(): Json` - returns the current context value.
+* `inflight error(): Error?` - returns the last error (or `nil`).
+
+## `execute` Step
+
+The `execute` step executes an inflight closure in a sequence.
+
+```js
+bring workflows;
+
+let w = new workflows.Workflow([
+  workflows.steps.execute("say hello", inflight (ctx) => {
+    log("hello, {ctx.get("name").asStr()}!");
+    return {
+      boom: 1234,
+    }
+  });
+]);
+
+test "main" {
+  w.start({ name: "world" });
+  let result = w.join();
+  log("result is: {result}");
+  // prints: { name: "world", boom: 1234 }
+}
+```
+
+The `ctx` argument is a `Json` object which is propagated throughout the workflow. Each execute step
+accepts the last context as input and returns a new JSON object that is *merged* with the input.
+
+## `check` Step
+
+TODO DOCS
+
+## Backends
+
+### AWS
+
+When compiling to `tf-aws`, workflows are deployed to AWS Step Functions:
+
+![](./docs/sfn.png)
+
+
+## License
+
+This library is licensed under the [MIT License](./LICENSE).

workflows/api.w

@@ -0,0 +1,80 @@
+bring util;
+
+pub interface IWorkflow {
+  onSuccess(cb: inflight (Json?): void): void;
+  onError(cb: inflight (Error): void): void;
+
+  inflight start(ctx: Json?): void;
+  inflight status(): Status;
+  inflight ctx(): Json;
+  inflight error(): Error?;
+  inflight join(opts: util.WaitUntilProps?): Json;
+
+}
+
+pub enum Status {
+  NOT_STARTED,
+  IN_PROGRESS,
+  ERROR,
+  DONE
+}
+
+pub interface Handler {
+  inflight handle(input: Json): Json?;
+}
+
+pub interface Predicate {
+  inflight handle(input: Json): bool;
+}
+
+pub struct Branches {
+  ifTrue: Array<Step>;
+  ifFalse: Array<Step>?;
+}
+
+pub enum StepType {
+  EXECUTE,
+  CHECK,
+}
+
+pub struct Step {
+  type: StepType;
+  name: str;
+}
+
+pub struct CheckStep extends Step {
+  predicate: Predicate;
+  branches: Branches;
+}
+
+pub struct ExecuteStep extends Step {
+  handler: Handler;
+}
+
+pub struct WorkflowOptions {
+  debug: bool?;
+}
+
+pub struct Error {
+  message: str;
+  stack: Array<str>;
+}
+
+pub class steps {
+  pub static execute(name: str, handler: Handler): Step {
+    return ExecuteStep {
+      type: StepType.EXECUTE,
+      name: name,
+      handler: handler,
+    };
+  }
+
+  pub static check(name: str, predicate: Predicate, branches: Branches): Step {
+    return CheckStep {
+      type: StepType.CHECK,
+      name: name,
+      branches: branches,
+      predicate: predicate,
+    };
+  }
+}

workflows/boom.main.w

@@ -0,0 +1,20 @@
+bring "./workflow.w" as w;
+bring "./api.w" as api;
+bring cloud;
+
+let m = new w.Workflow([
+  api.steps.execute("say hello", inflight (ctx) => {
+    log("hello {ctx.get("name")}!");
+  }),
+
+  api.steps.check("is name 5",
+    inflight (ctx) => {
+      return false;
+    },
+    ifTrue: [
+    ],
+    ifFalse: [
+    ],
+  )
+]);
+