<commit_before># NuclearJS

A framework to decouple app state and UI.

**Define a Core, which describes how a piece of your application state behaves**

```js
var Immutable = require('immutable')
var Nuclear = require('nuclear-js')
var __id = 1;

var todoItems = Nuclear.createCore({
  getInitialState: function() {
    return Immutable.Vector()
  },

  initialize: function() {
    // setup what events this part of the state reacts to

    this.on('addItem', function(state, payload){
      // a handler function is passed the current state
      // and returns a new state
      // push a new item record
      return state.push(Immutable.Map({
        id: __id++,
        title: payload.title,
        isCompleted: false
      }))
    })

    this.on('removeItem', function(state, payload){
      // returns a vector of all items except ones matching payload.id
      return state.filter(function(item) {
        return item.get('id') !== payload.id
      }).toVector()
    })

    this.on('completeItem', function(state, payload) {
      // marks an the item matching payload.is as `isCompleted`
      return state.map(function(item) {
        if (item.get('id') === payload.id) {
          return item.set('isCompleted', true)
        }
        return item
      }).toVector()
    })
  }
})
```

**Register that core as a key on the app state map**

```js
var Nuclear = require('nuclear-js')
var todoItems = require('./todo-items')

var reactor = Nuclear.createReactor()
// bind the todoItems state to the 'items' key in our app state
reactor.defineState('items', todoItems)

// start the reactor
reactor.initialize()

console.log(reactor.get('items'))
// Vector []

// Mutate state by dispatching actions into the reactor
reactor.dispatch('addItem', {
  title: 'hey',
})

console.log(reactor.get('items'))
// Vector [ Map { id: 1, title: 'hey', isCompleted: false }]
```

**Define Computed State**

One of the major sources of complexity in front end development is needed to have your 
application state in a different format to properly display it in the UI. Keeping stateful
instances of your application objects in the UI where it doesn't belong leads to headache.

NuclearJS solves this by allowing you to define computed properties on your app state.  Since
data structure in NuclearJS are immutable, these computeds are lazy and only get evaluated when
another part of the system needs to consume the value.

This allows your to describe the entire logic of your system in a performant manner.

**Lets add another Core to our system**

```js
var Nuclear = require('nuclear-js')
var todoItems = require('./todo-items')

var reactor = Nuclear.createReactor()
// bind the todoItems state to the 'items' key in our app state
reactor.defineState('items', todoItems)

reactor.defineState('filterValue', Nuclear.createCore({
  getInitialState: function() {
    return 'all'
  },

  initialize: function() {
    this.on('changeFilter', function(state, filterValue) {
      // return the new state of `filterValue`
      return filterValue
    })
  },
}))

// A getter defines some array of dependencies (app state keyPaths or other Getters)
// and a compute function that is passed the values of the deps
var shownItems = Nuclear.Getter({
  deps: ['items', 'filterValue'],
  compute: function(items, fitlerValue) {
    var filterFns = {
      'all': function(item) {
        return true
      },
      'active': function(item) {
        return !item.get('isCompleted')
      },
      'completed': function(item) {
        return item.get('isCompleted')
      },
    }
    var filterFn = filterFns[filterValue] || filterFns['all']

    return items.filter(filterFn).toVector()
  }
})

reactor.defineComputed('shownItems', shownItems)

// start the reactor
reactor.initialize()
```

**[Plans for 0.4](./NEXT.md)**

#### TL;DR

- **Flux-like** - One-way data flow, state can only be read, and actions are the only things
that are allowed to change the state of the system

- **Self-managing state** - State objects (**cores**) react to messages passed to them, they are the only ones
that know how to react to that message.  Cores do not know about any

- **UI Agnostic** - Completely abstract all business logic and state into **Cores** and **Actions**.  This makes
the UI layer simply a representation of the state and binds UI events to Nuclear Actions


#### The following prinicples drive its development

- **Immutability** - A means for safety, predictability and performance.

- **Implement functionally** - This reduces state, improves testability and allows composability.

- **Keep state minimal** - build a framework that encourages state of an application to be represented
in the simplest form possible.  Use computeds to transform pure state into something consummable by the
UI layer

- **Convenience APIs** - Provide a framework API that makes building UIs on top of Nuclear seamless and beautiful.

**more documentation coming soon**<commit_msg>Update readme example<commit_after># NuclearJS

One-way, immutable state modelling.

**Example: Modeling the state of a shopping cart**

Require Library Dependencies

```js
var Immutable = require('immutable')
var Nuclear = require('nuclear-js')
```

Model the state the shopping cart as `ReactiveState`

```js
var itemList = Nuclear.ReactiveState({
  getInitialState: function() {
    return Immutable.List()
  },

  initialize: function() {
    this.on('addItem', function(state, item) {
      // the current state of the itemList is passed
      // to this handler function whenever addItem message
      return state.push(Immutable.Map(item))
    })
  }
})

var taxPercent = Nuclear.ReactiveState({
  getInitialState: function() {
    return 0
  },

  initialize: function() {
    this.on('setTaxPercent', function(state, percent) {
      return percent
    })
  }
})

```

`subtotal`, `tax` and `total` are all computable from `items` and `taxPercent`

```js
var subtotal = Nuclear.Computed(
  // dependencies
  ['items'],
  // this function is called whenever any dependency
  //is updated with the dependency's value
  function(items) {
    return items.reduce(function(total, item) {
      total + item.get('price')
    }, 0)
  }
)

var tax = Nuclear.Computed(
  // computeds can have other computeds as dependencies
  [subtotal, 'taxPercent'],
  function(subtotal, taxPercent) {
    return (subtotal * (taxPercent / 100))
  }
)

var total = Nuclear.Computed(
  [subtotal, tax],
  function(subtotal, tax) {
    return subtotal + tax
  }
)
```

Putting it all together.

```js
var shoppingCart = Nuclear.Reactor({
  // define the system state as a mapping of
  // keys to ReactiveState or Computeds
  state: {
    items: itemList,
    taxPercent: taxPercent,
    subtotal: subtotal,
    tax: tax,
    total: total,
  }
})

shoppingCart.initialize()

shoppingCart.get('total') // 0
shoppingCart.get('items') // Vector []

shoppingCart.dispatch('addItem', {
  name: 'sandwhich',
  price: 10
})

shoppingCart.get('items') // Vector [ Map { name: 'sandwhich' price: 10 }]
shoppingCart.get('subtotal') // 10
shoppingCart.get('tax') // 0
shoppingCart.get('total') // 10

shoppingCart.dispatch('setTaxPercent', 5)

shoppingCart.get('subtotal') // 10
shoppingCart.get('tax') // 0.5
shoppingCart.get('total') // 10.5
```

#### TL;DR

- **Flux-like** - One-way data flow, state can only be read, and actions are the only things
that are allowed to change the state of the system

- **Self-managing state** - State objects (**cores**) react to messages passed to them, they are the only ones
that know how to react to that message.  Cores do not know about any

- **UI Agnostic** - Completely abstract all business logic and state into **Cores** and **Actions**.  This makes
the UI layer simply a representation of the state and binds UI events to Nuclear Actions


#### The following prinicples drive its development

- **Immutability** - A means for safety, predictability and performance.

- **Implement functionally** - This reduces state, improves testability and allows composability.

- **Keep state minimal** - build a framework that encourages state of an application to be represented
in the simplest form possible.  Use computeds to transform pure state into something consummable by the
UI layer

- **UI Interchangable** - NuclearJS should compliment, not replace existing UI frameworks as a way to model state.

**more documentation coming soon**
{'fraction_non_alphanumeric': 0.1107944424652654, 'fraction_numerical': 0.003206270039187745, 'mean_word_length': 3.6274725274725275, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, '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': '5898357', 'n_tokens_mistral': 2484, 'n_tokens_neox': 2354, 'n_words': 934}