# worksmith

> A purely functional workflow engine

Latest version **1.0.0** (published 2019-02-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install worksmith
pnpm add worksmith
yarn add worksmith
bun add worksmith
```

## Health

**Score 5/100 (F)** — status: abandoned.

Warnings: low downloads; no types; no esm support; has vulnerabilities.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2019-02-26 |
| First published | 2015-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 110.9 KB |
| Known vulnerabilities | 1 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | GuideSmiths - PeterAronZentai |
| Maintainers | guidesmiths, peterzentai, peterzentai_gs |
| Keywords | workflow, tasks, parallel |

## Links

- npm: https://www.npmjs.com/package/worksmith
- Repository: https://github.com/guidesmiths/worksmith
- Issues: https://github.com/guidesmiths/worksmith/issues
- npm.io page: https://npm.io/package/worksmith

## Dependencies (6)

- [pg](https://npm.io/package/pg.md) ^4.3.0
- [async](https://npm.io/package/async.md) ^0.9.0
- [debug](https://npm.io/package/debug.md) ^2.1.3
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [xregexp](https://npm.io/package/xregexp.md) ^2.0.0
- [handlebars](https://npm.io/package/handlebars.md) ^4.1.0

## Recent versions

- 1.0.0 (latest) — 2019-02-26
- 0.2.10 — 2016-02-29
- 0.2.8 — 2015-08-18
- 0.2.5 — 2015-07-09
- 0.2.3 — 2015-07-08
- 0.2.2 — 2015-07-07
- 0.1.8 — 2015-06-23
- 0.1.6 — 2015-06-22
- 0.1.5 — 2015-06-08
- 0.1.4 — 2015-06-05
- 0.1.3 — 2015-06-03
- 0.1.2 — 2015-06-03
- 0.1.1 — 2015-06-03
- 0.1.0-0 — 2015-06-03
- 0.0.25 — 2015-06-01
- … 18 more at https://npm.io/package/worksmith/versions

## README

# worksmith
A seriously `functional` workflow library, that lets you build composable and configurable process definitions for various reasons.

```npm i worksmith --save```


For a step by step tutorial click [here](https://github.com/guidesmiths/worksmith/blob/master/TUTORIAL.md)

[Release notes](https://github.com/guidesmiths/worksmith/blob/master/ReleaseNotes.md)

##Worksmith activities / task types

Worksmith comes with an extensible task library built up from the `core` and the `extension modules`.

### Core activities
| group | activities | description |
| ----- | ---------- | ----------- |

  - Control flow:  ```sequence``` ,  ```parallel``` and ```warezSequence```
  - IO: ```log```,```sql/pg```
  - Tansformation: ```map```, ```regex```, ```set```
  - Extensibitly: ```code``` activity , create custom task types by creating files in the tasks folder

### Extension modules

| name | description |
| ---  | ----------- |
| worksmith_salesforce | Interact with salesforce in a workflow |
| worksmith_etcd | Use network based locking via etcd service |
| coming | soon |
| worksmith_postgres | Execute SQL statements as part of the workflow, supports transactions |
| worksmith_assert | An assertion library to be used conventional workflows or workflows built for testing |
| worksmith_fs | Read/write files from a workflow |

- with worksmith you can build a complex async process chain from functional steps (tasks) - yet keep the application easy to understand and each functional step easy to developer and maintain. forget ```if(err) return next(err)```
- workflow steps are unaware about each other - they communicate over a shared context. WorkSmith provides an intuitive expression syntax for working with the context in a workflow definitions



## usage

### A workflow definition:
This can be in a config file, or as part of your js code as a variable.

```javascript
{ "task": "sequence",
  "items": [
        {
            task:"log", message:"hello workflow"
        },
        {
            task: "map",
            ">insertParams": ["@req.params.id", 1, 1]
        },
        {
            task:"sql/pg",
            connection: "@connection",
            command:  "insert into order (order_id, version, type) \
                       values ($1, $2, $3) returning id",
            params:  "@insertParams",
            resultTo: "insertResult"
        },
        {...}
  ]
}
```

### The code:

```javascript

var worksmith = require('worksmith')

var workflow = worksmith('./workflow.json')


var context = {
    connection:"postgres://login:pw@host/db",
    other:"data"
}

workflow(context, function(err, result) {
    console.log("workflow completed, %", context.insertResult)
})


```

## How to create your own activity

worksmith lets you build your activities on a super easy way
Place the following code as ```"hello-world.js"``` in the ```tasks``` folder

```javascript
var utils = require('worksmith')
module.exports = function (node) {
    //use the node variable to access workflow params
    return function(context) {
    //use the context to access workflow execution state
        return function(done) {
        //set done when your acitivity finished its job
        //read and write data from the context
            console.log("Hello world", context.get(node.inParam))
            context.set("myresult","myvalue")
            done();
        }
    }

}
```
Now you can use it the same way as the core activities
```javascript
var wf = workflow( {"task":"hello-world", "inParam":"some thing"} );

var ctx = {"some":"value"};
wf(ctx, function(err) {
    console.log(ctx)
})
```

## List of core activities

### log
Write a log to the console
#### options
message

### delay
Waits a bit
#### options
duration

### insertDbRecord
Like the name suggests
#### options
table
data
connection
resultTo

### softDeleteDbRecord

### deleteDbRecord

### parallel
Execute sub tasks in parallel
#### options
items array

### sequence
Execute sub tasks in sequence
#### options
items array

### warezSequence
Define a sequence on a patching compatible way
#### options
items array


### set
Set variable on the workflow context
#### options
name
value

---
_Source: https://npm.io/package/worksmith · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._