Documentation · Releases

Features

• 📦 no dependencies and no runtime-specific dependencies (besides ES6 + Promises)
• 🪶 minimal core with (xkb; see the sizes table)
• 🧠 very easy to use API
• 🧩 highly extensible from the ground up
• 📝 use declarative workflows and enrich them with custom functionality

Table of Contents

• Installation
  • Using Package Managers and Platforms
  • Using a CDN
  • Entry Points
• Usage
  • Minimal Example
  • Extensions
  • Events
• Covered environments
• File sizes
• Contribution and Development
  • Tools / stack
  • Development scripts
• Security
• License

Installation

Using Package Managers and Platforms

Our goal is to make Tinyflow usable anyhwere JavaScript is running. The following table shows some options to install Tinyflow's core package, the most minimal deliverable:

| name | command | tested | |------------|-------------------------------------------------------------|--------| | npm | npm install @tinyflow/core | | | yarn | yarn add @tinyflow/core | | deno (npm) | import { Tinyflow } from "npm:@tinyflow/core"; | | deno (cdn) | import { Tinyflow } from "https://esm.sh/@tinyflow/core"; | | bun | bun install @tinyflow/core |

Using a CDN

• unpkg
• jsdelivr
• cdnjs
• esm.sh
• jspm
• github (not for production!)

Entry Points

Tonyflow packages offer multiple entry point files, suited for different environments. Nowadays, you might want to stick with ESM but we also provide cjs, es5 and iife versions of the build, including sourcemaps and a minified version, too.

They're all placed in the respective package's /dist folder and committed to this repository.

Usage

Internally there are two classes, Workflow and Step that act for the whole engine. If you only want the core package then you will have to manage them manually.

Depending on your use-case, this might be exactly what you want or not want. If you want a more comfortable solution (suitable for beginners), you might also want to install @tinyflow/instances.

Minimal Example

If you want to have the most minimal size, then you will have to manage everything on your own. Here is an example for that:

import { Workflow } from '@tinyflow/core'

// create a new workflow
const workflow = new Workflow({
  name: 'checkout-cart',
  steps: {
    visit: {},
    paymentOptions: {},
    complete: {}
  }
})

// listen to workflow events
workflow.on('started', () => console.debug('workflow started'))
workflow.on('step', () => console.debug('new step is mounted', workflow.current))
workflow.on('error', ({ error }) => console.error(error))
workflow.on('end', () => {
  workflow.off() // remove all events
  console.debug('workflow ended with data', workflow.data)
})

workflow.start()

// ... at some point in your code
// update the current step's data
workflow.current.update({ some: 'data' })

// or complete the current step, causing
// workflow to move to the next step or end
workflow.current.complete()

Extensions

The real power of Tinyflow is it's ability to easily extend functionality. For this, there are two main methods (in fact, the Tinyflow object in core contains only them):

Tinyflow.extend - Extend Tinyflow and it's very internals

As a very simple example, we can create an id function that uses the Browser's crypto API to generate uuids:

const restoreId = Tinyflow.extend(internals => {
  const original = internals.id
  internals.id = () => window.crypto.randomUUID()
  
  // calling this method will rstore the default id generation
  return () => {
    internals.id = original
  }
})

const wf = new Workflow({ name: 'foo', steps: { one: {} }})
wf.id // "54b281b4-6ee1-4747-97a5-46543f71f359"

// call he restore function if your extension 
// should exist only for a limited time
restoreId()

As you can see, all internals remain scoped within that function (unless you intend to do fancy stuff...).

Tinyflow.use - Create a workflow runtime extension that executes, before a workflow or step startes

As a very simple example for this one, we can create a simple

More Examples

We have more examples ready in our documentation's examples section. Some of them can be executed directly in the browser or using node/deno/bun.

New Core Extensions

Some extensions might not be ready to be published yet. They are currently located the in the /next folder. If you think you have a good idea for a core extension, then please open an issue and choose the issue template for extensions.

Events

The core package brings two main classes that emit several events during the engine execution.

Workflow Class Events

| Name | Info | Data | |-----------|----------------------------------------------------------------------------------------------------------|------| | started | fired when the workflow has started, after all extensions were executed without error | | step | fired when a new step has entered | the workflow's data property will contain the data from the previous step at this point | end | fired when the workflow ended; read the workflow state to know whether it ended by complete or by cancel | the workflow's data property will contain all steps data | error | fired when an error has been caught |

Step Class Events

| Name | Info | Data | |----------|--------------------------------------------------------------------------------------------------|------| | started | fired when the step has started, after all extensions were executed without error | | update | fired when a step has received new data via update | the data will contain the latest updated data | end | fired when the step ended; read the it's state to know whether it ended by complete or by cancel | the step's data property will contain all steps final data | error | fired when an error has been caught |

Covered environments

Our goal is to Tinyflow executable in as many environments as possible. The following list shows, what's currently covered:

| Environment | latest versions | known issues | |--------------------|-----------------|--------------| | Node.js | | | | Deno | | | | Bun | | | | Cloudflare workers | | |

| Browser | tested versions | known issues | |-----------------|-----------------|--------------| | Chrome | | | | Safari | | | | Safari (iOS) | | | | Firefox | | | | Opera | | | | Android Webview | | | | ... | | |

You can help out with testing for these environments, so we can maximize the compatibility overall.

File sizes

Tinyflow comes with a minimal core but also provides extensions out-of-the-box. At the same time we build Tinyflow for multiple outputs.

The following table shows the size of the various builds, available in their respective /dist folders. Note, that this overview shows only the sizes for the minified versions of each, excluding sourcemaps.

| package | mjs | cjs | es5 | iife | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|------| | @tinyflow/core | | | | | @tinyflow/instances | | | |

Contribution and Development

We provide an extensive contribution guideline and a code of conduct to help you in making your contribution a success!

Tools / stack

• 🗪 Babel for transpiling
• 🪄 Standard for linting
• ⚗️ Mocha and Chai for testing
• 🔍 c8 for code coverage
• 📚 JSDoc for documentation and jsdoc-to-markdown to create docs as markdown files
• ⚡ GitHub actions for continuous integration
• 📦 Rollup for bundling

All tools are defined as dev-dependencies!

Development scripts

We provide a default set of dev-tools via npm scripts. Run a script via

$ npm run <command>

where <command> is one of the following available commands:

| command | description | output | |-----------------|---------------------------------------------------|------------| | lint | runs the linter in read-mode | | | lint:fix | runs the linter; fixes minor issues automatically | | | test | runs the tests once | | | test:watch | runs the tests; re-runs them on code changes | | | test:coverage | runs the tests once and creates a coverage report | coverage | | docs | creates API documentation | docs | | build | builds the bundles for several target platforms | dist | | build:full | runs build and docs | see above |

Security

Please read our security policy to get to know which versions are covered.

License

MIT, see license file