<commit_before># Succession
Succession is a tool for creating dynamic function chains. It is similar to `lodash`'s `flow`
or `ramda`'s `pipe` with one important exception, namely that you can *force functions to run
at the very start or very end of the chain no matter where the handler is added.*

## Usage

```js

import chain from 'succession';

const plusTwo = n => n + 2;
const timesTwo = n => n * 2;
const divideTwo = n => n / 2;

const calculate = chain(
  plusTwo,
  timesTwo,
  divideTwo,
  plusTwo
)
// ((((10 + 2) * 2) / 2) + 2) = 14
console.log(calculate(10)); // 14

```

### Nesting

Nesting also works as expected

```js
// ...
const calculate = chain(
  plusTwo,
  chain(
    timesTwo,
    divideTwo
  ),
  plusTwo
)

console.log(calculate(10)); // 14
```

### Force functions to the start or end

Here is the important part: **You can then force a handler to the end of the chain from the sub chain.**

```js
// ...
const addUnits = n => `${n} seconds`;

const innerChain = chain(
  timesTwo,
  divideTwo
).last(addUnits);

const calculate = chain(
  plusTwo,
  innerChain,
  plusTwo
)

console.log(calculate(10)); // "14 seconds"
```

Or ensure a handler starts the chain

```js
const calculate = chain(
  plusTwo,
  chain(
    timesTwo,
    divideTwo
  ).first(() => 10),
  plusTwo
)

console.log(calculate('foo')); // 14
```
---

## So why would you want to do this?

Here is an example of a chain that is configuring an express server.

```js
import express from 'express';
import path from 'path';
import chain from 'succession';

const initApp = (app = express()) => {
  return app;
}

const serveStaticFiles = (app) => {
  app.use('/static', express.static(path.join(__dirname, 'static')));<commit_msg>Update docs to provide titles<commit_after># Succession
Succession is a tool for creating dynamic function chains. It is similar to `lodash`'s `flow`
or `ramda`'s `pipe` with one important exception, namely that you can *force functions to run
at the very start or very end of the chain no matter where the handler is added.*

## Usage

```js

import chain from 'succession';

const plusTwo = n => n + 2;
const timesTwo = n => n * 2;
const divideTwo = n => n / 2;

const calculate = chain(
  plusTwo,
  timesTwo,
  divideTwo,
  plusTwo
)
// ((((10 + 2) * 2) / 2) + 2) = 14
console.log(calculate(10)); // 14

```

### Nesting

Nesting also works as expected

```js
// ...
const calculate = chain(
  plusTwo,
  chain(
    timesTwo,
    divideTwo
  ),
  plusTwo
)

console.log(calculate(10)); // 14
```

### Force functions to the start or end

Here is the important part: **You can then force a handler to the end of the chain from the sub chain.**

```js
// ...
const addUnits = n => `${n} seconds`;

const innerChain = chain(
  timesTwo,
  divideTwo
).last(addUnits);

const calculate = chain(
  plusTwo,
  innerChain,
  plusTwo
)

console.log(calculate(10)); // "14 seconds"
```

Or ensure a handler starts the chain

```js
const calculate = chain(
  plusTwo,
  chain(
    timesTwo,
    divideTwo
  ).first(() => 10),
  plusTwo
)

console.log(calculate('foo')); // 14
```

## So why would you want to do this?

Here is an example of a chain that is configuring an express server.

```js
import express from 'express';
import path from 'path';
import chain from 'succession';

const initApp = (app = express()) => {
  return app;
}

const serveStaticFiles = (app) => {
  app.use('/static', express.static(path.join(__dirname, 'static')));
{'fraction_non_alphanumeric': 0.13770207852193994, 'fraction_numerical': 0.01558891454965358, 'mean_word_length': 3.4825355756791723, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2667445', 'n_tokens_mistral': 1192, 'n_tokens_neox': 1134, 'n_words': 437}