grand_central 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8abd6b12cae93650613a9f466eb975de3a9eb5aa
-  data.tar.gz: e2dc7159021c2338fe9cfdb5a98ec488a2653f57
+  metadata.gz: 6c0e9a7148ac9f9b9e5b20cc9274a586b9afe8e0
+  data.tar.gz: a7086f1e94374a7a9d80e8392387fcabde4fc414
 SHA512:
-  metadata.gz: baa7b094d514c66e172b7a3c00ab39da2d77d328c528099d7ee176319fdf3f837f392ec66d2698c6cf1ab906e789470d444d2773e2d9b9ecaf077f4e59a704fd
-  data.tar.gz: 99ef1e7ac694c4a171af3c46bbf6cce16322df55e69f3e0daa123000ee5716d01b15d392af5c9d2d1429413cad3bfff48b02c6689ba781c6c1790773b43ff34e
+  metadata.gz: 4a76db401fa74f3ea0d82f0ec85f191407098b8c8317c74fb5d08f6b91805d0e40f7140daec007e41d58a6cfd5b689d7fbadb99a82b645e843dd7cde791f91c1
+  data.tar.gz: dc22db5f648f0c447a60840bc397907c71000f384f9b18e5ba7d387168bd09169a66dee9782058866bb53d10b306ac52f523a35a2a896490536695dada069fe1

data/README.md

@@ -1,8 +1,8 @@
 # GrandCentral
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/grand_central`. To experiment with that code, run `bin/console` for an interactive prompt.
+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.
 
-TODO: Delete this and the text above, and describe your gem
+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.
 
 ## Installation
 
@@ -22,7 +22,94 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+First, you'll need a store. You'll need to seed it with initial state and give it a reducer function:
+
+```ruby
+require 'grand_central'
+
+store = GrandCentral::Store.new(a: 1, b: 2) do |state, action|
+  case action
+  when :a
+    # Notice we aren't updating the state in-place. We are returning a new
+    # value for it by passing a new value for the :a key
+    state.merge a: state[:a] + 1
+  when :b
+    state.merge b: state[:b] + 1
+  else # Always return the given state if you aren't updating it.
+    state
+  end
+end
+
+store.dispatch :a
+store.dispatch :b
+store.dispatch "You can dispatch anything you want, really"
+```
+
+### Actions
+
+The actions you dispatch to the store can be anything. We used symbols in the above example, but GrandCentral also provides a class called `GrandCentral::Action` to help you set up your actions:
+
+```ruby
+module Actions
+  include GrandCentral
+
+  # The :todo becomes a method on the action, similar to a Struct
+  AddTodo    = Action.with_attributes(:todo)
+  DeleteTodo = Action.with_attributes(:todo)
+  ToggleTodo = Action.with_attributes(:todo) do
+    # We don't want to toggle the Todo in place. We want a new instance of it.
+    def toggled_todo
+      Todo.new(
+        id: todo.id,
+        name: todo.name,
+        complete: !todo.complete?
+      )
+    end
+  end
+end
+```
+
+Then your reducer can use these actions to update the state more easily:
+
+```ruby
+store = GrandCentral::Store.new(todos: []) do |state, action|
+  case action
+  when Actions::AddTodo
+    state.merge todos: state[:todos] + [action.todo]
+  when Actions::DeleteTodo
+    state.merge todos: state[:todos] - [action.todo]
+  when Actions::ToggleTodo
+    state.merge todos: state[:todos].map { |todo|
+      # We want to replace the todo in the array
+      if todo.id == action.todo.id
+        action.todo
+      else
+        todo
+      end
+    }
+  else
+    state
+  end
+end
+```
+
+### Performing actions on dispatch
+
+You may want your application to do something in response to a dispatch. For example, in a Clearwater app, you might want to re-render the application when the store's state has changed:
+
+```ruby
+store = GrandCentral::Store.new(todos: []) do |state, action|
+  # ...
+end
+
+app = Clearwater::Application.new(component: Layout.new)
+
+store.on_dispatch do |old_state, new_state|
+  app.render unless old_state.equal?(new_state)
+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.
 
 ## Development
 
@@ -32,5 +119,5 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/grand_central. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/clearwater-rb/grand_central. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 

data/lib/grand_central/version.rb

@@ -1,3 +1,3 @@
 module GrandCentral
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/grand_central.rb

@@ -1,7 +1,10 @@
 require "grand_central/version"
 require "grand_central/store"
+require "grand_central/action"
 
 module GrandCentral
 end
 
-Opal.append_path File.expand_path('..', __FILE__)
+if RUBY_ENGINE != 'opal'
+  Opal.append_path File.expand_path('..', __FILE__)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grand_central
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jamie Gaskins
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-05 00:00:00.000000000 Z
+date: 2015-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal