---
category: tutorial
title: state
layout: post
---

The `state` type, is a container which encapsulates a stateful function. It basically allows you to compose functions,
like you can do with the `f` type, except with it any function can access an additional "variable" besides its
input argument(s) - the state. 

<!--more-->



To use the `state` monad constructor, you can require it using node:
		
		var state = require("../library/state")


Where the `../` is the location of the module.

In the context of this type a state is represented by a function that accepts a state 
and returns a list which contains a value and a new state. So for example:

	state((val) => [val+1, val])

Creates a new stateful computation which increments the input argument and then saves it in the state.



`of(value)`
----
Accepts a value and wraps in a state container



		const state5 = state().of(5)


Note that the following code does not put `5` in the state.
Rather it creates a function which returns `5` and does not interact with the state. 



`map(funk)`
----
Executes `funk` with the encapsulated value as an argument, and wraps the result in a new `state` object, 
without accessing the state


***



One of the main benefits of the `state` types is that it allows you to mix pure functions with unpure ones, 
In the same way that promises allow us to mix asychronous functions with synchronous ones.
Map allows us to apply any function on our value and to consume the result in another function.

	var myState = state(5)
		.map((val) => val+1)
		.map((val) => {
			assert.equal(val, 6)
			return val * 2
		})
		.map((val) => assert.equal(val, 12))
		.run()





`phatMap(funk)`
----
Same as `map`, except that if `funk` returns a new state object it merges the two states into one.
Thus `flatMap` simulates manipulation of mutable state.
***




For example, here is a function that 

	var myState = state("value")
		//Write the value in the state
		.phatMap( value => state( _ => ["new "+value , "initial "+value]) )

		//manipulate the value
		.phatMap( val => val.toUpperCase().split("").join("-") )
		
		//We can access the state at any time.
		.phatMap( val => state(st => {
			assert.equal( val, "N-E-W- -V-A-L-U-E")
			assert.equal( st, "initial value")
		})).run()




`save() / load()`
----
Shorthands for the most common state operations: 
- `save` copies the currently encapsulated value into the state
- `load` just returns the current state
***





	var myState = state(5)
	.phatMap( (val) => val+1 ) //6
	.saveKey("st1")
	
	.phatMap( (val) => val*2 )//12
	.saveKey("st2")
	
	.load()
	.map( (state) => {
		assert.equal(state.st1, 6)
		assert.equal(state.st2, 12)
	}).run()



under the hood
--------------
Let's see how the type is implemented












`of` just uses the constructor and does not touch the state.

	//a -> m a
	of:function(input){
		return state((prevState) => [input, prevState])
	},

`map` is done by applying the function to the value and keeping the state unchanged.

	//m a -> ( a -> b ) -> m b
	map:function(funk){
		return state( this._runState.map(([input, prevState]) => [funk(input), prevState]))
	},
	
`flat` does the following:
1. Runs the code that we loaded in the monad so, far (using the `run` function).
2. Saves the new state object and the value which is kept by the functions so far.
3. After doing that, it arranges those two components (the object and the value) into a yet another
state object, which runs the mutator function of the first object, with the state that we have so, far



	//m (m x) -> m x
	flat:function(){
		//Extract state mutator and value 
		const [stateObj, currentState] = this.run()
		//Compose the mutator and the value
		return state(() => stateObj._runState(currentState) )
	},
	tryFlat:function(){

		//Extract current state 
		const [stateObj, currentState] = this.run()
		
		//Check if it is really a state
		if(stateObj.constructor === state){
			return state(() => stateObj._runState(currentState) )
		}else{
			return state(() => [stateObj, currentState])
		}
	},

We have the `run` function which computes the state:

	run:function(){
		return this._runState()
	},
And the `save` and `load` functions are exactly what one would expect

	load:function(){
		return this.flatMap( (value) => state( (state) => [state, state] ) )
	},
	save:function(){
		return this.flatMap( (value) => state( (state) => [value, value] ) )
	},
	loadKey:function(key){
		return this.flatMap( (value) => state( (state) => [state[key], state] ) )
	},
	saveKey:function(key){
		const write = (obj, key, val) => {
			obj = typeof obj === "object" ?  obj : {}
			obj[key] = val
			return obj
		}
		return this.flatMap( (value) => state( (state) => [value, write(state, key, value)] ) )
	},
	toString:function(){
		return JSON.stringify(this.run())
	}
	
})

In case you are interested, here is how the state constructor is implemented

	const state = function(run){
		if(typeof run !== "function"){ return stateProto.of(run) }
		const obj = Object.create(stateProto)
		obj._runState = f(run,1)
		obj.constructor = state
		obj.prototype = stateProto
		Object.freeze(obj)
		return obj
	}