<commit_before><h1 align="center">DerivableJS</h1>
<h3 align="center">State made simple → Effects made easy</h3>

[![npm version](https://badge.fury.io/js/derivable.svg)](http://badge.fury.io/js/derivable) [![Build Status](https://travis-ci.org/ds300/derivablejs.svg?branch=new-algo)](https://travis-ci.org/ds300/derivablejs) [![Coverage Status](https://coveralls.io/repos/github/ds300/derivablejs/badge.svg?branch=new-algo)](https://coveralls.io/github/ds300/derivablejs?branch=new-algo) [![Join the chat at https://gitter.im/ds300/derivablejs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ds300/derivablejs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Empowered by Futurice's open source sponsorship program](https://img.shields.io/badge/sponsored%20by-chilicorn-ff69b4.svg)](http://futurice.com/blog/sponsoring-free-time-open-source-activities?utm_source=github&utm_medium=spice&utm_campaign=derivablejs)
---

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Derivables are an Observable-like momoizing state container with superpowers. Think [MobX](https://github.com/mobxjs/mobx) distilled to a potent essence, served with extra performance and a garnish of innovative ideas about how to manage side effects.

- [Rationale](#rationale)
  - [Types of State](#types-of-state)
  - [Observables to the rescue?](#observables-to-the-rescue)
  - [Derivables to the actual rescue!](#derivables-to-the-actual-rescue)
- [What even is a Derivable?](#what-even-is-a-derivable)
- [Reactors](#reactors)
- [Usage](#usage)
      - [With React](#with-react)
      - [With Redux](#with-redux)
      - [Debugging](#debugging)
      - [Examples (very wip)](#examples-very-wip)
      - [Browser](#browser)
      - [Equality Woes](#equality-woes)
- [Contributing](#contributing)
- [Thanks](#thanks)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## State made simple

This is a bold claim, I'll grant you. To be more specific, Derivables make 'derived' state simple, assuming that you already know how to make 'atomic' state simple.

Let me explain just what the heck I'm talking about here.

### Derived and Atomic state

We tend not to think about it much, but there are a few different kinds of application state:

- **Constant state** is defined at compile/init time. It never changes for the lifetime of an application and is therefore of no relevance here.

- **Stack state** is created on and bound to a runtime call stack. e.g. loop variables and intermediate results.

Programming languages tend to have nice support for managing stack state, and nobody ever complains about it being especially hard (maybe one exception is Forth, which literally provides a stack for managing state).

  Functional programming languages turn the simplicity up a notch here by enabling or enforcing the use of pure functions and immutable data, which are effective tools to restrict the means of updating stack state. Enforcing languages like Haskell actually disallow the direct mutation of stack state (except via black magic).

Some applications need only these two kinds of state, being essentially just functions themselves. e.g. compilers, audio/video transcoders, etc. But the vast majority of applications we use do this other thing where they have internal state which can be modified by external events. They are susceptible to *incursions of control* which carry some piece of data—explicitly or otherwise—through a new call stack, normally causing internal state changes and/or side effects. This internal, changing state can be further categorized:

- **Atomic state** is dependent only on things which have happened in the past to cause incursions of control into the system, e.g. clicking the 'increment' button in a counter app causes the 'count' piece of atomic state to change. If you use Redux, your whole store is atomic state. Other examples of atomic state in a web browser: mouse position, window size, and page scroll offset. On the backend: session data, DB cache, ...

  Modern practices from the FP world are also making atomic state fairly simple to manage. Immutable data and pure functions combine well with things like software transactional memory, the actor model, atomic references, event sourcing, and so on. Again, these are *restrictive* tools for shrinking the set of ways in which state may be updated with the intention of increasing Reasonaboutability™.

- **Derived state** is directly dependent only on the *current* value of other bits of atomic or derived state. To illustrate:

  - Whether or not an input form is valid is dependent on the values currently held in the form's fields.
  - The number of idle users an IRC channel is dependent on the list of all currently-connected users.
  - The pixel width of a div whose width is specified in percent is dependent on the current pixel width of its parent, etc.

  Derived state is often also stack state, in that we recompute it on-demand every time it is needed. This is a nicely simple way to go about things because it means that derived state is always consistent with the atomic state it depends upon (possibly indirectly). Unfortunately, doing this can create undesirable or untenable extra load for our poor CPUs and RAM sticks. It can also be difficult to keep things DRY because different concerns might require slightly different permutations or combinations of the same derived state.

  We therefore sometimes coerce derived state into atomic state by doing one of two things:

   - Updating the derived state manually at the same time as its dependencies. This leaves dependency relationships implicit, requiring the programmer to know about them when making changes (basically impossible for non-savants working on real systems). This also makes it extremely difficult to maintain separation of concerns in business logic because state dependency relationships freely and rightly cross domains.

   - Artificially creating new events to notify others of state changes. This solves the separation of concerns problem, but can still get hellaciously messy for the following reason: event listeners are no longer allowed to assume that they are at the root of a new incursion of control. And yet they do. And yes it matters. A lot.
<commit_msg>fix indentation<commit_after><h1 align="center">DerivableJS</h1>
<h3 align="center">State made simple → Effects made easy</h3>

[![npm version](https://badge.fury.io/js/derivable.svg)](http://badge.fury.io/js/derivable) [![Build Status](https://travis-ci.org/ds300/derivablejs.svg?branch=new-algo)](https://travis-ci.org/ds300/derivablejs) [![Coverage Status](https://coveralls.io/repos/github/ds300/derivablejs/badge.svg?branch=new-algo)](https://coveralls.io/github/ds300/derivablejs?branch=new-algo) [![Join the chat at https://gitter.im/ds300/derivablejs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ds300/derivablejs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Empowered by Futurice's open source sponsorship program](https://img.shields.io/badge/sponsored%20by-chilicorn-ff69b4.svg)](http://futurice.com/blog/sponsoring-free-time-open-source-activities?utm_source=github&utm_medium=spice&utm_campaign=derivablejs)
---

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Derivables are an Observable-like momoizing state container with superpowers. Think [MobX](https://github.com/mobxjs/mobx) distilled to a potent essence, served with extra performance and a garnish of innovative ideas about how to manage side effects.

- [Rationale](#rationale)
  - [Types of State](#types-of-state)
  - [Observables to the rescue?](#observables-to-the-rescue)
  - [Derivables to the actual rescue!](#derivables-to-the-actual-rescue)
- [What even is a Derivable?](#what-even-is-a-derivable)
- [Reactors](#reactors)
- [Usage](#usage)
      - [With React](#with-react)
      - [With Redux](#with-redux)
      - [Debugging](#debugging)
      - [Examples (very wip)](#examples-very-wip)
      - [Browser](#browser)
      - [Equality Woes](#equality-woes)
- [Contributing](#contributing)
- [Thanks](#thanks)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## State made simple

This is a bold claim, I'll grant you. To be more specific, Derivables make 'derived' state simple, assuming that you already know how to make 'atomic' state simple.

Let me explain just what the heck I'm talking about here.

### Derived and Atomic state

We tend not to think about it much, but there are a few different kinds of application state:

- **Constant state** is defined at compile/init time. It never changes for the lifetime of an application and is therefore of no relevance here.

- **Stack state** is created on and bound to a runtime call stack. e.g. loop variables and intermediate results.

  Programming languages tend to have nice support for managing stack state, and nobody ever complains about it being especially hard (maybe one exception is Forth, which literally provides a stack for managing state).

  Functional programming languages turn the simplicity up a notch here by enabling or enforcing the use of pure functions and immutable data, which are effective tools to restrict the means of updating stack state. Enforcing languages like Haskell actually disallow the direct mutation of stack state (except via black magic).

Some applications need only these two kinds of state, being essentially just functions themselves. e.g. compilers, audio/video transcoders, etc. But the vast majority of applications we use do this other thing where they have internal state which can be modified by external events. They are susceptible to *incursions of control* which carry some piece of data—explicitly or otherwise—through a new call stack, normally causing internal state changes and/or side effects. This internal, changing state can be further categorized:

- **Atomic state** is dependent only on things which have happened in the past to cause incursions of control into the system, e.g. clicking the 'increment' button in a counter app causes the 'count' piece of atomic state to change. If you use Redux, your whole store is atomic state. Other examples of atomic state in a web browser: mouse position, window size, and page scroll offset. On the backend: session data, DB cache, ...

  Modern practices from the FP world are also making atomic state fairly simple to manage. Immutable data and pure functions combine well with things like software transactional memory, the actor model, atomic references, event sourcing, and so on. Again, these are *restrictive* tools for shrinking the set of ways in which state may be updated with the intention of increasing Reasonaboutability™.

- **Derived state** is directly dependent only on the *current* value of other bits of atomic or derived state. To illustrate:

  - Whether or not an input form is valid is dependent on the values currently held in the form's fields.
  - The number of idle users an IRC channel is dependent on the list of all currently-connected users.
  - The pixel width of a div whose width is specified in percent is dependent on the current pixel width of its parent, etc.

  Derived state is often also stack state, in that we recompute it on-demand every time it is needed. This is a nicely simple way to go about things because it means that derived state is always consistent with the atomic state it depends upon (possibly indirectly). Unfortunately, doing this can create undesirable or untenable extra load for our poor CPUs and RAM sticks. It can also be difficult to keep things DRY because different concerns might require slightly different permutations or combinations of the same derived state.

  We therefore sometimes coerce derived state into atomic state by doing one of two things:

   - Updating the derived state manually at the same time as its dependencies. This leaves dependency relationships implicit, requiring the programmer to know about them when making changes (basically impossible for non-savants working on real systems). This also makes it extremely difficult to maintain separation of concerns in business logic because state dependency relationships freely and rightly cross domains.

   - Artificially creating new events to notify others of state changes. This solves the separation of concerns problem, but can still get hellaciously messy for the following reason: event listeners are no longer allowed to assume that they are at the root of a new incursion of control. And yet they do. And yes it matters. A lot.

{'fraction_non_alphanumeric': 0.0750816104461371, 'fraction_numerical': 0.004508005596144878, 'mean_word_length': 4.6286089238845145, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 20, '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': '7162036', 'n_tokens_mistral': 3454, 'n_tokens_neox': 3216, 'n_words': 1647}