`typescript
const ScrollPosDisplay = () => {
scrollPos.forEach((pos) => console.log(pos))
// ...
}
`

Now this side-effect will continue executing after your component is unmounted. To fix this, you can scope it to component lifecycle like this:

`typescript
import { unmountEvent } from "harmaja"

const ScrollPosDisplay = () => {
scrollPos
.pipe(L.applyScope(componentScope()))
.forEach((pos) => console.log(pos))
// ...
}
`

And you're good to go! See the full example at examples/side-effects.

$3

When you apply componentScope() to an observable as above,

When you create stateful Properties or Atoms (i.e. ones that are based on Properties but add some local state, such as filter),
you need to specify a Scope that defines the lifetime of this Property/Atom.

Harmaja componentScope is very suitable, as it will activate the Property on component mount and deactivate on unmount.
The gotcha here is that when running the component constructor, the stateful Property is not in scope yet
(component is not mounted, and we should not activate before mount, or we get a resource leak).

So, you can subscribe to stateful Properties in the constructor, but you cannot get their value yet.
If you do, the get() call will throw an error saying "not in scope yet".

Examples

Part of my process has been validating my work with some examples I've previously used for the comparison of different React state management solutions. Here I quickly list some examples, but I beg you to read the full story below, which will visit each of these examples in a problem context instead of just throwing a bucket of code in your face.

- Todo App with Unidirectional data flow: examples/todoapp. I've added some annotations. In this example, application state is reduced from different events (add/remove/complete todo item).

- Todo App with Atoms: examples/todoapp-atoms. It's rather less verbose, because with Atoms, you can decompose and manipulate substate directly using atom.set instead using events and reducers.

- Finally a bit more involved example featuring a "CRM": examples/consultants. It features some harder problems like dealing with asynchronous (and randomly failing!) server calls as well as edit/save/cancel.

Examples covered also in the chapters below, with some context.

Unidirectional data flow

Unidirectional data flow, popularized by Redux, is a leading state management pattern in web frontends today. In short, it means that you have a (usually essentially) global data _store_ or stores that represent pretty much the entire application state. Changes to this state are not effected directly by UI components but instead by dispacthing _events_ or _actions_ which then are processed by _reducers_ and applied to the global state. The state is treated as an immutable object and every time the reducers applies a new change to state, it effectively creates an entire new state object.

In Typescript, you could represent these concepts in the context of a Todo App like this:

`typescript
type Item = {}
type Event = { type: "add"; item: Item } | { type: "remove"; item: Item }
type State = { items: Item[] }
type Reducer = (currentState: State, event: Event) => State
interface Store {
dispatch(event: Event)
subscribe(observer: (event: Event) => void)
}
`

In this scenario, UI components will subscribe to changes in the Store and dispatch events to effect state changes. The store will apply its Reducer to incoming events and the notify the observer components on updated state.

The benefits are (to many, nowadays) obvious. These come from the top of my mind.

- Reasoning about state changes is straightforward, as only reducers change state. You can statically backtrack all possible causes of a change to a particular part of application state.
- The immutable global state object makes persisting and restoring application state easier, and makes it possible to create and audit trail of all events and state history. It also makes it easier to pass the application state for browser-side hydration after a server-side render.
- Generally, reasoning about application logic is easier if there is a pattern, instead of a patchwork of ad hoc solutions

Implementations such as Redux allow components to _react_ to a select part of global state (instead of all changes) to avoid expensive updates. With React hooks, you can conveniently just useSelector(state => pick interesting parts) and you're done.

It's not a silver bullet though. Especially when using a single global store with React / Redux

- There is no solution for local or scoped state. Sometimes you need scoped state that applies, for instance, to the checkout process of your web store. Or to widely used components such as an address selector. Or for storing pending changes to, say, user preferences before applying them to the global state.
- This leads to either using React local state or some "corner" of the global state for these transient pieces of state
- Refactoring state from local to global is tedious and error-prone because you use an entirely different mechanism for each
- You cannot encapsulate functionalities (store checkout) into self-sustaining components because they are dependent on reducers which lively somewhere else completely

Other interesting examples of Unidirectional data flow include Elm and Cycle.js.

Unidirectional data flow with Harmaja

In Harmaja, you can implement Unidirectional data flow too. Sticking with the Todo App example, you define your events as _buses_:

`typescript
import * as L from "lonna"

type AppEvent = { action: "add"; name: string } | { action: "remove"; id: Id }
const appEvents = L.bus()
`

The bus objects allow you to dispatch an event by calling their push method. From the events, the application state can be reduced using L.scan like thus:

`typescript
const initialItems: TodoItem[] = []
function reducer(items: TodoItem[], event: AppEvent): TodoItem[] {
switch (event.action) {
case "add":
return items.concat(todoItem(event.name))
case "remove":
return items.filter((i) => i.id !== event.id)
}
}
const allItems = appEvents.pipe(L.scan(initialItems, reducer, L.globalScope))
`

The L.globalScope parameter is used to specify the lifetime of the allItems property, i.e. how long it will be kept up-to-date. When using globalScope the property updates will never stop.
When creating statetul Properties within Harmaja components, you can also use componentScope() from import { componentScope } from "harmaja", to stop updates after the components has been unmounted.

You can, if you like, then encapsulate all this into something like

`typescript
interface TodoStore {
dispatch: (action: AppEvent) => void
items: L.Property
}
`

...so you have an encapsulation of this piece of application state, and you can pass this store to your UI components.

You can also define the buses and the derived state properties in your components if you want to have scoped state.
There is no such thing as _react context_ in Harmaja, so everything is either passed explicitly or defined in a global scope, at least for now.

The globalScope parameter above indicates the lifetime for the constructure reactive Property, and a global lifetime in this
case means that the value will be kept up-to-date indefinitely. If you declare state in a component, you should use componentScope() instead to
prevent resource leak. You can import { componentScope } from "harmaja".

From store to view

In unidirectional data flow setups, there's always a way to reflect the store state in your UI. For instance,

- In react-redux you can use the useSelector hook for extracting the parts of global state your component needs
- In Elm and Cycle.js the whole state is always rendered from the root and you trust the framework to be effient in VDOM diffing

Pretty soon after React started gaining popularity, my colleagues at Reaktor (and I later) started using a "Bacon megablob" architecture where events and the "store" are
defined exactly as in the previous chapter, using Buses and a state Property. Thanks to React's relatively good performance with VDOM and diffing,
it's in most cases a viable choice. Sometimes though, it may prove too heavy to render everything everytime. If you have a "furry" (wide and deeply nested) data model,
doing a full render on every keystroke just might not work. This has caused pain and various optimizations (often involving local state) have been written.

However, it may make more sense to adopt the useSelector-like approach and instead of rendering the whole VDOM on all changes,
listen to relevant changes in your components and render on change. I wrote about one React Hooks based approach on the
Reaktor blog earlierly.

Now if we consider the case of Harmaja, the situation is different from any React based approaches. First of all, Harmaja doesn't have VDOM diffing or Hooks. But the
fact that you can pass reactive properties as props fits the bill very nicely, so in the case of a TodoItem view, you can

`tsx
import { React, mount } from "../.."

const ItemView = ({ item }: { item: L.Property }) => {
return (

{L.view(item, (i) => i.name)}

)
}
`

The first big difference to Redux is that instead of asking for stuff from the global state in your component implementation, you actually require the relevant data
in the function signature (how revolutionary!). This rather obviously makes the component easier to reason about, use in different context, test and so on. So just from
the function signature you can easily decuce that this component will render a TodoItem and reflect any changes that are effected to that particular TodoItem (because
the input is a reactive property).

In the implementation, the L.view is used to get a Property which
then can be directly embedded into the resulting DOM,
because Harmaja natively renders Properties. When the value of name changes, the updated value will be applied to DOM.

Think: _you can pick a part of your Store and use it as a Store_. This removes the need for the component to _know where the data is_ in the global store.
In react-redux all components that actually _react_ to store changes, need to know the "location" of their data in the store to be able to get it using useSelector.
In contrast using the Property abstraction you can easily map out the data from the store and give a handle to your components.

Another big difference is that store data and local data are the same. No separate mechanism for dealing with local state. Instead, you can declare more Properties in
your component constructors as you go, to flexibly define data stores at different application layers. Which arguably makes it easier to make changes too, as you don't
need to change the mechanism when moving from local to global. More on this topic below.

Anyway, let's put the Todo App together right now! To simplify a bit, if were were just rendering the first TodoItem (There's a chapter on array rendering down there), the root element of the application could look like this:

`tsx
const App = () => {
const firstItem: Property = L.view(allItems, (items) => items[0])
return
}
`

Then you can mount it and it'll start reacting to changes in the store:

`tsx
mount(, document.getElementById("root")!)
`

Although I prefer components that get all of their required inputs in their constructor (this is called dependency injection), there's nothing to prevent you from
accessing global "stores" from your components as well.

See the full Todo App example here.

Composable read and write

So it's easy to _decompose_ data for viewing so that you can _compose_ your application out of components.
But what about writes? Do they compose too? It would certainly be nice not to have to worry about every single
detail in the high level "main reducer". Instead I find it an attractive idea to deal on a higher abstraction level.

Let's try! It's intuitive to start with this:

`typescript
updateTodoItem: L.Bus()
todoItems: L.Property // impl redacted
`

So instead of having to care about all the possible modifications to items on this level, there's a single updateTodoItem event that can be used to perform any update.

As shown earlierly, decomposition works nicely as you can call L.view(item, i => i.someField) to get views into its components parts.
Now let's revisit ItemView from the previous section and add a onUpdate callback.

`tsx
import { React, mount } from "../.."

const ItemView = ({
item,
onChange,
}: {
item: L.Property
onChange: (i: TodoItem) => void
}) => {
const onNameChange = (newName: string) => {
/ wat /
}
return (

text={L.view(item, (i) => i.name)}
onChange={onNameChange}
/>

)
}

const TextInput = ({
value,
onChange,
}: {
text: L.Property
onChange: (s: string) => void
}) => {
return (
onChange(e.currentTarget.value)} />
)
}
`

I added an simple TextInput component that renders the given Property into an input element and calls
its onChange listener. Yes, with Harmaja, you can embed reactive properties into DOM element props just like that.
Now the question is, how to implement onNameChange, as well as the myriad similar functions you may need in your
more complex applications.

The tricky thing is that in the onNameChange function you don't really have the current full TodoItem at hand.
Instead you have a Property which does not provide a method for extracting its current value.
The reason for this omission is that reactive properties are meant to be used in a reactive manner, i.e. by subscribing
to them. If you don't subscribe, the property isn't necessarily kept up to date with its underlying data source.

Yet, in this case we _know_ that the property has a value and is active (the TextInput is subscribing to it to reflect
changes). So we can use a little hack, which is the getCurrentValue function used by Harmaja under the hood for
being able to render observables synchronously, and which it generously exports as well. So we can do this:

`typescript
const onNameChange = (newName: string) => {
onChange({ ...getCurrentValue(item), name: newName })
}
`

So it's fully doable: you can use a higher level of abstraction in the top-level reducer and deal with individual field
updates in "mid-level" components such as the ItemView.

Yet, it's far from elegant especially if you've ever worked with Atoms and Lenses with Calmm.js. Read on.

Welcome to the Atom Age

So you're into decomposing read-write access into data. This is where atoms come handy.
An Atom simply represents a two-way interface to data by extending Property and adding
a set: (newValue: A) method for changing the value. Let's try it by changing our TextInput to

`tsx
import { Atom, atom } from "lonna"
const TextInput = ({ value }: { text: Atom }) => {
return (
text.set(e.currentTarget.value)} />
)
}
`

This is the full implementation. Because Atom encapsulates both the view to the data (by being a Property)
and the callback for data update (through the set method), it can often be the sole prop an "editor" component needs.
To create an Atom in our unidirectional data flow context, we can construct an "dependent atom" from a Property and a set function
like so:

`tsx
const ItemView = ({
item,
onChange,
}: {
item: L.Property
onChange: (i: TodoItem) => void
}) => {
const itemAtom: Atom = atom(item, onChange)
return (



)
}
`

And that's also the full implementation! I hope this demonstrates the power of the Atom abstraction. The view method there is particularly interesting (I redacted methods and the support for array keys for brevity):

`typescript
export interface Atom extends L.Property {
set(newValue: A): this
get(): A
}

function view(a: Atom, key: K): Atom
`

The same view method that you can use to get a read-only views into Properties, can be used to create another atom that gives read-write access to one field of ther TodoItem and done this in a type-safe manner (compiler errors in case you misspelled a field name).

Finally, we have an abstraction that makes read-write data decomposition a breeze! Adding more editable fields is no longer a chore. And all this still with unidirectional data flow, immutable data and type-safety.

The view method is actually based on the Lenses that's a concept been used in the functional programming world for quite a while. Yet, I haven't heard much talk about using Lenses in web application state management except for Calmm.js and before that the Bacon.Model library. I could rant about lenses all night long but for now, I'll show you the Atom-specific signatures of the view method:

`typescript
export function view(
a: Atom,
key: K
): K extends number ? Atom : Atom
export function view(a: Atom, lens: L.Lens): Atom
`

It reveals two things. First, it supports numbers for accessing array elements. But most importantly, you can create a view to an
Atom with an arbitrary Lens. Which a really simple abstraction:

`typescript
export interface Lens {
get(root: A): B
set(root: A, newValue: B): A
}
`

But let's move on.

Local state

So far, it's all been about Unidirectional Data Flow when there's a single source of truth which is a single reactive Property
that's reduced from one or more events streams. Yet sometimes it makes sense to use some local state too.
That's when standalone Atoms come into play.

To use our ItemView as a standalone component you can change it to use the Atom interface just like the lower level TextInput component:

`tsx
const ItemView = ({ item }: { item: Atom }) => {
return (



)
}
`

and use it in your App like this:

`tsx
const App = () => {
const item: Atom = atom({
id: 1,
name: "do stuff",
completed: false,
})
return
}
`

See, I created an independent Atom in the App component. It's practically local state to App now. Remember that in Harmaja, just like with Calmm.js,
component functions are to be treated like constructors. This means that the local variables created in the function
will live as long as the component is mounted, and can thus be used for local state (unlike in React where they would be re-ininitialized on every VDOM render).

That's all there is to local state in Harmaja, really. State can be defined globally, or in any level of the component tree. When you
use Atoms, you can define them locally or accept them as props. You can even add a fallback:

`typescript
const ItemView = ({ item }: { item: Atom = atom(emptyTodoItem) }) => {
///
}
`

This component could be used with an external atom (often a view into a larger chunk of app state) or without it, in which case
it would have it's private state.

And it's turtles all the way down by the way. You can define your full application state as an Atom and them view your way into details.
An example of fully Atom-based application state can be seen at examples/todoapp-atoms.

Arrays

Efficient and convenient way of working with arrays of data is a necessary step to success. When
there's a substantial number of items (say 1000) of some substantial complexity, performance is not trivial
anymore.

React VDOM diffing will get its users to some point, but when that's not enough, you'll need to
make sure that frequent operations (change to a single item, append new item, depends on use case) do not force
the full array VDOM to be re-rendered. This is fully possible with, for instance, react-redux: just make sure the
component that renders the array doesn't re-render unless array size changes.

In Harmaja, there's no VDOM diffing so relying on that is not an option. Therefore, a perfomant and ergonomic array view is key. So, I've included a ListView component for just that.

Imagine again you're building a Todo App again (who isnt'!) and you have the same data model that was introduced in the
"Unidirectional data flow" chapter above. To recap, it's this.

`typescript
type TodoItem = {
name: string
id: number
completed: boolean
}
const addItemBus = new L.Bus()
const removeItemBus = new L.Bus()
const allItems: L.Property = L.update(
globalScope,
[],
[addItemBus, (items, item) => items.concat(item)],
[removeItemBus, (items, item) => items.filter((i) => i.id !== item.id)]
)
`

$3

To render the TodoItems represented by the allItems property you can use ListView thus:

`tsx
; observable={allItems}
renderObservable={(item: L.Property) => }
getKey={(a: TodoItem) => a.id}
/>

const ItemView = ({ item }: { item: L.Property }) => {
// implement view for individual item
}
`

What ListView does here is that it observes allItems for changes and renders each item using the ItemView component.
When the list of items changes (something is replaced, added or removed) it uses the given getKey function to determine
whether to replace individual item views. With the given getKey implementation it replaces views only when the id field doesn't match,
i.e. the view no longer represents the same item. Each item view gets a Property so that they can update when the content
in that particular TodoItem is changed. See full implementation in examples/todoapp.

$3

ListView also supports read-write access using Atom. So if you have

`typescript
const allItems: Atom = atom([])
`

You can have read-write access to the items by using ListView thus:

`tsx
atom={items}
renderAtom={(item, removeItem) => {
return (