Awesome
Serverless Workflow Specification - Typescript SDK
Provides the Typescript API/SPI for the Serverless Workflow Specification
With the SDK you can:
- Parse workflow JSON and YAML definitions
- Programmatically build workflow definitions
- Validate workflow definitions
Status
Latest Releases | Conformance to spec version |
---|---|
v1.0.0 | v0.6 |
v2.0.0 | v0.7 |
v3.0.0 | v0.8 |
Getting Started
Building locally
To build the project and run tests locally:
git clone https://github.com/serverlessworkflow/sdk-typescript.git
cd sdk-typescript
npm install && npm run build && npm run test
How to use
Install
Version >= 4.0.0
Note: Version 4.0.0 has not been released yet.
npm i @serverlessworkflow/sdk-typescript
Version < 4.0.0
npm i @severlessworkflow/sdk-typescript
Create Workflow using builder API
import { workflowBuilder, injectstateBuilder, Specification } from '@serverlessworkflow/sdk-typescript';
const workflow: Specification.Workflow = workflowBuilder()
.id("helloworld")
.specVersion("0.8")
.version("1.0")
.name("Hello World Workflow")
.description("Inject Hello World")
.start("Hello State")
.states([
injectstateBuilder()
.name("Hello State")
.data({
"result": "Hello World!"
})
.build()
])
.build();
Create Workflow from JSON/YAML source
import { Specification, Workflow } from '@serverlessworkflow/sdk-typescript';
const source = `id: helloworld
version: '1.0'
specVerion: '0.8'
name: Hello World Workflow
description: Inject Hello World
start: Hello State
states:
- type: inject
name: Hello State
data:
result: Hello World!
end: true`
const workflow: Specification.Workflow = Workflow.fromSource(source);
Where source
can be in both JSON or YAML format.
Parse a Workflow instance to JSON/YAML
Having the following workflow instance:
import { workflowBuilder, injectstateBuilder, Specification } from '@serverlessworkflow/sdk-typescript';
const workflow: Specification.Workflow = workflowBuilder()
.id("helloworld")
.version("1.0")
.specVersion("0.8")
.name("Hello World Workflow")
.description("Inject Hello World")
.start("Hello State")
.states([
injectstateBuilder()
.name("Hello State")
.data({
"result": "Hello World!"
})
.end(true)
.build()
])
.build();
You can convert it to its string representation in JSON or YAML format
by using the static methods Workflow.toJson
or Workflow.toYaml
respectively:
import {Specification, workflowBuilder} from "@severlessworkflow/sdk-typescript";
const workflow: Specification.Workflow = workflowBuilder()
//...
.build()
const workflowAsJson: string = Specification.Workflow.toJson(workflow);
import {Specification, workflowBuilder} from "@severlessworkflow/sdk-typescript";
const workflow: Specification.Workflow = workflowBuilder()
//...
.build()
const workflowAsYaml: string = Specification.Workflow.toYaml(workflow);
Validate workflow definitions
The sdk provides a way to validate if a workflow object is compliant with the serverlessworkflow specification.
WorkflowValidator
class provides a validation method:
validate(): boolean
import {WorkflowValidator, Specification} from '@serverlessworkflow/sdk-typescript';
import {Workflow} from "./workflow";
const workflow = {
id: 'helloworld',
version: '1.0',
specVersion: '0.3',
name: 'Hello World Workflow',
description: 'Inject Hello World',
start: 'Hello State',
states: [
{
type: 'inject',
name: 'Hello State',
end: true,
data: {
result: "Hello World!"
}
}
]
};
const workflowValidator: WorkflowValidator = new WorkflowValidator(Workflow.fromSource(JSON.stringify(workflow)));
if (!workflowValidator.isValid) {
workflowValidator.errors.forEach(error => console.error((error as ValidationError).message));
}
You can also validate parts of a workflow using validators
:
import { ValidateFunction } from 'ajv';
import { validators, Specification } from '@serverlessworkflow/sdk-typescript';
const injectionState: Specification.Injectstate = workflow.states[0];
const injectionStateValidator: ValidateFunction<Specification.Injectstate> = validators.get('Injectstate');
if (!injectionStateValidator(injectionState)) {
injectionStateValidator.errors.forEach(error => console.error(error.message));
}
Generate workflow diagram
It is possible to generate the workflow diagram with Mermaid
const workflow = workflowBuilder()
.id("helloworld")
....
.build();
const mermaidSourceCode = new MermaidDiagram(workflow).sourceCode();
Here you can see a full example that uses mermaid in the browser to generate the workflow diagram.