+
+## Play with Examples at [codesandbox.io](https://codesandbox.io/s/github/johnlindquist/react-streams/tree/master/examples?module=%2Fhello%2Findex.js)
+
+`react-streams` provides four features:
+
+1. `` - Subscribes to a `source` prop and renders into `props.children`
+2. `plan(...operators)` - Creates a function that can `merge` with `source`. Invoke the function to update `source`
+3. `converge(source$, plan1, plan2, plan3, ...)` - Creates `sources` using the `merge` then `scan` pattern
+4. `` - Handles **_Advanced scenarios_** where you need a custom strategy to adapt to props changing (e.g., filtering props, combining prev/next props, etc). Using this will overwrite `source` because the `receiveProps` operator must return its own stream.
+
+## `` from a `source` with Operators
+
+The `` component will subscribe to what you pass into the `source` prop.
+The result will be passed into the "render prop" function of either `props.children`
+or `props.render`.
+
+Configure your `source` stream however you want. You can delay, debounce, startWith,
+etc, etc, etc.
+
+```js
+import React from "react"
+import { Stream } from "react-streams"
+import { delay, startWith } from "rxjs/operators"
+import { of } from "rxjs"
+
+const source$ = of({ message: "Hello" }).pipe(
+ delay(1000),
+ startWith({ message: "Wait..." })
+)
+
+export default () => (
+ {({ message }) =>
{message}
}
+)
+```
+
+## Configure a `` with Props (Ajax Demo)
+
+Use `props` to configure your `` by wrapping it with another `Component`.
+Then pass whatever props you want to use to the `` and make sure you
+pass `props.children` (or just `{...props}`) so the `` has something
+to render.
+
+```js
+import React from "react"
+import { Stream } from "react-streams"
+import { ajax } from "rxjs/ajax"
+import { pluck, switchMap } from "rxjs/operators"
+import { of } from "rxjs"
+
+// Get your own, free todos API 🙌 https://glitch.com/edit/#!/import/github/johnlindquist/todos-api
+const url = "https://dandelion-bonsai.glitch.me/todos"
+
+const Todo = ({ url, id, ...props }) => {
+ const todo$ = of({ url, id }).pipe(
+ switchMap(({ url, id }) => ajax(`${url}/${id}`)),
+ pluck("response")
+ )
+ //the `Stream` needs `props.children`, so I'm passing all the props
+ return
+}
+
+export default () => (
+
+ {({ text, id }) => (
+
+ {id}. {text}
+
+ )}
+
+)
+```
+
+## Make a `Plan`
+
+A `plan` creates a function you invoke to push values into the ``.
+Exactly like the "RxJS" `pipe`, a `plan` will group together operators to work on
+values in a sequence. Notice how `onChange` grabs the `target.value`, `delay`s 250 ms,
+and then pushes a message Object.
+
+`merge` together your `source` and your `plan`s, then `scan` them together.
+(We'll talk more about this pattern in the `converge` section.)
+
+Now you can invoke the `onChange` plan wherever you want to update the ``.
+
+```js
+import React from "react"
+import { Stream, plan } from "react-streams"
+import { merge, of } from "rxjs"
+import { delay, map, pluck, scan } from "rxjs/operators"
+
+const text$ = of({ message: "Hello" })
+
+const onChange = plan(
+ pluck("target", "value"),
+ delay(250),
+ map(message => ({ message }))
+)
+
+const state$ = merge(text$, onChange).pipe(
+ scan((state = {}, patch) => {
+ return { ...state, ...patch }
+ })
+)
+
+export default () => (
+
+ {({ message, onChange }) => (
+
+
+
{message}
+
+ )}
+
+)
+```
+
+## Merge `Plans` to Create a `source`
+
+This "counter" demo shows how many `plans` can work together to update a source.
+Pass them all into `merge` (or use the `converge` helper in the next Demo :))
+then invoke them when needed.
+
+The `merge` then `scan` pattern will wire them all together to keep your state
+in sync.
+
+```js
+import React from "react"
+import { Stream, plan } from "react-streams"
+import { merge, of } from "rxjs"
+import { map, scan } from "rxjs/operators"
+
+const Count = ({ start, ...props }) => {
+ const count$ = of({ count: start })
+ const onInc = plan(map(() => state => ({ count: state.count + 2 })))
+ const onDec = plan(map(() => state => ({ count: state.count - 2 })))
+ const onReset = plan(map(() => state => ({ count: 4 })))
+
+ const state$ = merge(count$, onInc, onDec, onReset).pipe(
+ scan((state = {}, updater) => updater(state))
+ )
+ return
+}
+
+export default () => (
+
+ {({ count, onInc, onDec, onReset }) => (
+
+
+
+ {count}
+
+
+
+
+ )}
+
+)
+```
+
+## Converge
+
+`converge` is a utility around the `merge` then `scan` pattern from the
+last two demos. With `converge`, your `plans` can return either a function or an
+object to update/patch the state as shown below.
+
+```js
+import React from "react"
+import { Stream, converge, plan } from "react-streams"
+import { of } from "rxjs"
+import { map, mapTo } from "rxjs/operators"
+
+const message$ = of({ message: "Hello" })
+const date = plan(
+ map(() => ({
+ message: new Date().toLocaleDateString()
+ }))
+)
+const bye = plan(mapTo({ message: "Bye" }))
+const yo = plan(mapTo({ message: "Yo" }))
+
+const state$ = converge(message$, date, bye, yo)
+
+export default () => (
+
+
+ {({ message }) => (
+
+
{message}
+
+
+
+
+ )}
+
+
+)
+```
+
+## Todos App (with Ajax)
+
+The `Todos` app below uses `plans` that talk to a backend. Each "add", "patch",
+and "delete" operation does a round-trip before coming back to update the UI.
+
+The `` demonstrates how `plans` can talk to each other. `onSubmit`
+can trigger an `onAddTodo` and `clearAfterAdd$` can listen for `onAddTodo` to
+push the next value.
+
+There are quite a few operators working together in `pipes` inside `plans`.
+`react-streams` strongly encourages creating reusable `pipes` of operators
+
+```js
+import React from "react"
+import { Stream, converge, plan } from "react-streams"
+import { from, pipe } from "rxjs"
+import { ajax } from "rxjs/ajax"
+import {
+ concatMap,
+ map,
+ mapTo,
+ pluck,
+ startWith,
+ tap,
+ withLatestFrom
+} from "rxjs/operators"
+
+const HEADERS = { "Content-Type": "application/json" }
+
+const renderAddTodoForm = ({ current, onChange, onSubmit }) => (
+
+)
+
+const AddTodoForm = ({ onAddTodo }) => {
+ const onChange = plan(pluck("target", "value"))
+ const current$ = from(onChange).pipe(
+ startWith(""),
+ map(current => ({ current }))
+ )
+
+ const onSubmit = plan(
+ tap(e => e.preventDefault()),
+ withLatestFrom(onChange, (_, text) => text)
+ )
+ from(onSubmit).subscribe(onAddTodo)
+
+ const clearAfterAdd$ = from(onAddTodo).pipe(mapTo({ current: "" }))
+
+ const state$ = converge(current$, clearAfterAdd$)
+
+ return (
+
+ )
+}
+
+const Todo = ({ todo, onToggleDone, onDeleteTodo }) => (
+
+ )
+ }}
+
+)
+```
+
+## Use `Context` for Global Streams
+
+Pass `source`s globally using React's `Context` api. As long as your `source` and
+`plans` converge, you can then pass them anywhere in your app to display or
+update values.
+
+```js
+import React, { createContext } from "react"
+import { Stream, converge, plan } from "react-streams"
+import { of } from "rxjs"
+import { mapTo } from "rxjs/operators"
+
+const message$ = of({ message: "Hello" })
+const bye = plan(mapTo({ message: "Bye" }))
+const yo = plan(mapTo({ message: "Yo" }))
+const source = converge(message$, bye, yo)
+
+const { Consumer } = createContext({ source, bye, yo })
+
+export default () => (
+
+
+ {({ source }) => (
+
+ {({ message }) =>
{message}
}
+
+ )}
+
+
+
+
+
+
+ {({ bye, yo }) => (
+
+
+
+
+ )}
+
+
+
+
+
+)
+```
+
+## `Converge` Multiple Sources
+
+You can `converge` as many sources and `plans` as you like. Just remember that
+`plans` will operate on the source at the level they are "converged"
+
+```js
+import React, { createContext } from "react"
+import { Stream, converge, plan } from "react-streams"
+import { of } from "rxjs"
+import { map, mapTo, pluck } from "rxjs/operators"
+
+const name$ = of({ name: "John" })
+const onUpdate = plan(pluck("target", "value"), map(name => () => ({ name })))
+
+const nameState$ = converge(name$, onUpdate)
+
+const count$ = of({ count: 5 })
+const onInc = plan(mapTo(({ count }) => ({ count: count + 1 })))
+const onDec = plan(mapTo(({ count }) => ({ count: count - 1 })))
+
+const countState$ = converge(count$, onInc, onDec)
+
+const source = converge(nameState$, countState$)
+
+const { Consumer } = createContext({ source, onUpdate, onInc, onDec })
+
+const NameAndCountStream = props => (
+ } />
+)
+
+const NameOnlyComponent = ({ name, onUpdate }) => (
+
+