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
| Latest Releases | Conformance to spec version |
|---|---|
| v1.0.0 | v0.6 |
| v2.0.0 | v0.7 |
| v3.0.0 | v0.8 |
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 testNote: Version 4.0.0 has not been released yet.
npm i @serverlessworkflow/sdk-typescriptnpm i @severlessworkflow/sdk-typescriptimport { 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();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.
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);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));
}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.