grand_central 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db799a36024cf51a5bb7f773c960004e73e46f14
-  data.tar.gz: 834c42bf7db774cd5e0f5a98ae401875d82cb71f
+  metadata.gz: bd1b1c7c87a6efc6be8b3d4a31696e63030ddf63
+  data.tar.gz: 5102d9ab68fff6598986b688fe109827ec42b621
 SHA512:
-  metadata.gz: c4f09955fcecc0f4df052ecb182867995f6f3cd0b1998c4e743f32041a8b83083717261fac6cb4ac3f0f3bdb2daf293a421a471ea2b1950c7612f5a57efea097
-  data.tar.gz: b86b2ef1799904b35ead134b2100dbbcd2167800addcec339b442c8812f52236cf9ccf50fcba3f914e870f2f40ecfe0d360e50765161ead5c4fcfd875f43eb18
+  metadata.gz: 45c960f0d712c8f9d7e1ae80a44f6f323687d755ae7ccedcf3b3607cd64f45e64cbe1a828c59c9e22f54102def1f2b58ece490187093a23f14996e77e4eaebbd
+  data.tar.gz: 8ef41c15f98fe3eb3b9abe8ddb97db82156385491be383750c40944e896c2d2af756e617a79b8b4edbd4af4db706c48ac71616dcf7bb8bcdeb8cc61643d8025b

data/README.md

@@ -2,7 +2,7 @@
 
 GrandCentral is a state-management and action-dispatching library for Opal apps. It was created with [Clearwater](https://github.com/clearwater-rb/clearwater) apps in mind, but there's no reason you couldn't use it with other types of Opal apps.
 
-GrandCentral is based on ideas similar to [Redux](http://rackt.github.io/redux/). You have a central store that holds all your state. This state is updated via a reducer block when you dispatch actions to the store.
+GrandCentral is based on ideas similar to [Redux](http://rackt.github.io/redux/). You have a central store that holds all your state. This state is updated via a handler block when you dispatch actions to the store.
 
 ## Installation
 
@@ -22,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-First, you'll need a store. You'll need to seed it with initial state and give it a reducer function:
+First, you'll need a store. You'll need to seed it with initial state and give it a handler block:
 
 ```ruby
 require 'grand_central'
@@ -69,7 +69,7 @@ module Actions
 end
 ```
 
-Then your reducer can use these actions to update the state more easily:
+Then your handler can use these actions to update the state more easily:
 
 ```ruby
 store = GrandCentral::Store.new(todos: []) do |state, action|
@@ -111,6 +111,78 @@ end
 
 Notice the `unless old_state.equal?(new_state)` clause. This is one of the reasons we recommend you update state by returning a new value instead of mutating it in-place. It allows you to do cache invalidation in O(1) time.
 
+## Models
+
+We can use the `GrandCentral::Model` base class to store our objects:
+
+```ruby
+class Person < GrandCentral::Model
+  attributes(
+    :id,
+    :name,
+    :location,
+  )
+end
+```
+
+This will set up a `Person` class we can instantiate with a hash of attributes:
+
+```ruby
+jamie = Person.new(name: 'Jamie')
+```
+
+### Immutable Models
+
+The attributes of a model cannot be modified once set. That is, there's no way to say `person.name = 'Foo'`. If you need to change the attributes of a model, there's a method called `update` that returns a new instance of the model with the specified attributes:
+
+```ruby
+jamie = Person.new(name: 'Jamie')
+updated_jamie = jamie.update(location: 'Baltimore')
+
+jamie.location         # => nil
+updated_jamie.location # => "Baltimore"
+```
+
+This allows you to use the `update` method in your store's handler without mutating the original reference:
+
+```ruby
+store = GrandCentral::Store.new(person) do |person, action|
+  case action
+  when ChangeLocation
+    person.update(location: action.location)
+  else person
+  end
+end
+```
+
+This keeps each version of your app state intact if you need to roll back to a previous version. In fact, the app state itself can be a `GrandCentral::Model`:
+
+```ruby
+class AppState < GrandCentral::Model
+  attributes(
+    :todos,
+    :people,
+  )
+end
+
+initial_state = AppState.new(
+  todos: [],
+  people: [],
+)
+
+store = GrandCentral::Store.new(initial_state) do |state, action|
+  case action
+  when AddPerson
+    state.update(people: state.people + [action.person])
+  when DeleteTodo
+    state.update(todos: state.todos - [action.todo])
+
+  else
+    state
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/grand_central.rb

@@ -1,6 +1,7 @@
 require "grand_central/version"
 require "grand_central/store"
 require "grand_central/action"
+require "grand_central/model"
 
 module GrandCentral
 end

data/lib/grand_central/model.rb

@@ -0,0 +1,31 @@
+require 'set'
+
+module GrandCentral
+  class Model
+    def self.attributes *attrs
+      @attributes ||= Set.new
+      if attrs.any?
+        @attributes += attrs
+        attr_reader *attrs
+      end
+
+      @attributes
+    end
+
+    def initialize attributes={}
+      self.class.attributes.each do |attr|
+        instance_variable_set "@#{attr}", attributes[attr]
+      end
+    end
+
+    def update attributes={}
+      self.class.new(to_h.merge(attributes))
+    end
+
+    def to_h
+      self.class.attributes.each_with_object({}) do |attr, hash|
+        hash[attr] = send(attr)
+      end
+    end
+  end
+end

data/lib/grand_central/version.rb

@@ -1,3 +1,3 @@
 module GrandCentral
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grand_central
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jamie Gaskins
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-12 00:00:00.000000000 Z
+date: 2016-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -71,6 +71,7 @@ files:
 - grand_central.gemspec
 - lib/grand_central.rb
 - lib/grand_central/action.rb
+- lib/grand_central/model.rb
 - lib/grand_central/store.rb
 - lib/grand_central/version.rb
 - lib/grand_central/versioned_store.rb
@@ -93,8 +94,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: State and action management for Opal apps
 test_files: []
+has_rdoc: