HyperState
The easiest way to understand HyperState is by example. If you you did not see the Tic-Tac-Toe example, then please review it now, as we are going to use this to demonstrate how to use the
Hyperstack::State::Observable module.In our original Tic-Tac-Toe implementation the state of the game was stored in the
DisplayGame component. State was updated by "bubbling up" events from lower level components up to DisplayGame where the event handler updated the state.This is a nice simple approach but suffers from two issues:
- Each level of lower level components must be responsible for bubbling up the events to the higher component.
- The
DisplayGamecomponent is responsible for both managing state and displaying the game.
As our applications become larger we will want a way to keep each component's interface isolated and not dependent on the overall architecture, and to insure good separation of concerns.
The
Hyperstack::State::Observable module allows us to put the game's state into a separate class which can be accessed from any component: No more need to bubble up events, and no more cluttering up our DisplayGame component with state management and details of the game's data structure.Here is the game state and associated methods moved out of the
DisplayGame component into its own class:class Game
include Hyperstack::State::Observable
def initialize
@history = [[]]
@step = 0
end
observer :player do
@step.even? ? :X : :O
end
observer :current do
@history[@step]
end
state_reader :history
WINNING_COMBOS = [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]]
def current_winner?
WINNING_COMBOS.each do |a, b, c|
return current[a] if current[a] && current[a] == current[b] && current[a] == current[c]
end
false
end
mutator :handle_click! do |id|
board = history[@step]
return if current_winner? || board[id]
board = board.dup
board[id] = player
@history = history[0..@step] + [board]
@step += 1
end
mutator(:jump_to!) { |step| @step = step }
end
Let's go over the each of the differences from the code that was in the
DisplayGame component.class Game
include Hyperstack::State::Observable
Game is now in its own class and includes Hyperstack::State::Observable. This adds a number of methods to Game that allows our class to become a reactive store. When Game interacts with other stores and components they will be updated as the state of Game changes. def initialize
@history = [[]]
@step = 0
end
In the original implementation we initialized the two state variables
@history and @step in the before_mount callback. The same initialization is now in the initialize method which will be called when a new instance of the game is created. This will still be done in the DisplayGame before_mount callback (see below.) observer :player do
@step.even? ? :X : :O
end
observer :current do
@history[@step]
end
In the original implementation we had instance methods
player and current. Now that Game is a separate class we define these methods using observer.The
observer method creates a method that is the inverse of mutator. While mutate (and mutator) indicate that state has been changed observe and observer indicate that state has been accessed outside the class. attr_reader :history
Just as we have
mutate, mutator, and state_writer, we have observe, observer, and state_reader. WINNING_COMBOS = [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]]
def current_winner?
WINNING_COMBOS.each do |a, b, c|
return current[a] if current[a] && current[a] == current[b] && current[a] == current[c]
end
false
end
We don't need any changes to
current_winner?. It accesses the internal state through the current method so there is no need to explicitly make current_winner? an observer (but we could, without affecting anything.) mutator :handle_click! do |id|
board = history[@step]
return if current_winner? || board[id]
board = board.dup
board[id] = player
@history = history[0..@step] + [board]
@step += 1
end
mutator(:jump_to!) { |step| @step = step }
end
Finally we need no changes to the
handle_click! and jump_to! mutators either.class DisplayGame < HyperComponent
before_mount { @game = Game.new }
def moves
return unless @game.history.length > 1
@game.history.length.times do |move|
LI(key: move) { move.zero? ? "Go to game start" : "Go to move ##{move}" }
.on(:click) { @game.jump_to!(move) }
end
end
def status
if (winner = @game.current_winner?)
"Winner: #{winner}"
else
"Next player: #{@game.player}"
end
end
render(DIV, class: :game) do
DIV(class: :game_board) do
DisplayCurrentBoard(game: @game)
end
DIV(class: :game_info) do
DIV { status }
OL { moves }
end
end
end
The
DisplayGame before_mount callback is still responsible for initializing the game, but it no longer needs to be aware of the internals of the game's state. It simply calls Game.new and stores the result in the @game instance variable. For the rest of the component's code we call the appropriate method on @game.We will need to pass the entire game to
DisplayBoard (we will see why shortly) so we will rename it to DisplayCurrentBoard.As we will see
DisplayCurrentBoard will be responsible for directly notifying the game that a user has clicked, so we do not need to handle any events coming back from DisplayCurrentBoard.class DisplayCurrentBoard < HyperComponent
param :game
def draw_square(id)
BUTTON(class: :square, id: id) { game.current[id] }
.on(:click) { game.handle_click!(id) }
end
render(DIV) do
(0..6).step(3) do |row|
DIV(class: :board_row) do
(row..row + 2).each { |id| draw_square(id) }
end
end
end
end
The
DisplayCurrentBoard component receives the entire game, and it will access the current board, using the current method, and will directly notify the game when a user clicks using the handle_click! method.By having
DisplayCurrentBoard directly deal with user actions, we simplify both components as they do not have to communicate back upwards via events. Instead we communicate through the central game store.Rather than sending params down to lower level components, and having the components bubble up events, we have created a Flux Loop. The
Game store holds the state, the top level component reads the state and sends it down to lower level components, those components update the Game state causing the top level component to re-rerender.This structure greatly simplifies the structure and understanding of our components, and keeps each component functionally isolated.
Furthermore algorithms such as
current_winner? now are neatly abstracted out into their own class.If we are sure we will only want one game board, we could define
Game with class methods like this:class Game
include Hyperstack::State::Observable
class << self
def initialize
@history = [[]]
@step = 0
end
observer :player do
@step.even? ? :X : :O
end
observer :current do
@history[@step]
end
state_reader :history
WINNING_COMBOS = [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]]
def current_winner?
WINNING_COMBOS.each do |a, b, c|
return current[a] if current[a] && current[a] == current[b] && current[a] == current[c]
end
false
end
mutator :handle_click! do |id|
board = history[@step]
return if current_winner? || board[id]
board = board.dup
board[id] = player
@history = history[0..@step] + [board]
@step += 1
end
mutator(:jump_to!) { |step| @step = step }
end
end
class DisplayBoard < HyperComponent
param :board
def draw_square(id)
BUTTON(class: :square, id: id) { board[id] }
.on(:click) { Game.handle_click!(id) }
end
render(DIV) do
(0..6).step(3) do |row|
DIV(class: :board_row) do
(row..row + 2).each { |id| draw_square(id) }
end
end
end
end
class DisplayGame < HyperComponent
def moves
return unless Game.history.length > 1
Game.history.length.times do |move|
LI(key: move) { move.zero? ? "Go to game start" : "Go to move ##{move}" }
.on(:click) { Game.jump_to!(move) }
end
end
def status
if (winner = Game.current_winner?)
"Winner: #{winner}"
else
"Next player: #{Game.player}"
end
end
render(DIV, class: :game) do
DIV(class: :game_board) do
DisplayBoard(board: Game.current)
end
DIV(class: :game_info) do
DIV { status }
OL { moves }
end
end
end
Now instead of creating an instance and passing it around we call the class level methods on
Game throughout.The
Hyperstack::State::Observable module will call any class level initialize methods in the class or subclasses before the first component mounts.Note that with this approach we can go back to passing just the current board to
DisplayBoard as DisplayBoard can directly access Game.handle_click! since there is only one game.To summarize: a store is simply a Ruby object or class that using the
observe and mutate methods marks when its internal data has been observed by some other class, or when its internal data has changed.When components render they observe stores throughout the system, and when those stores mutate the components will rerender.
You as the programmer need only to remember that public methods that read internal state must at some point during their execution declare this using
observe, observer, state_reader or state_accessor methods. Likewise a method that changes internal state must declare this using mutate, mutator, state_writer or state_accessor methods.If your store's methods access other stores, you do not need worry about their state, only your own. On the other hand keep in mind that the built in Ruby Array and Hash classes are not stores, so when you modify or read an Array or a Hash its up to you to use the appropriate
mutate or observe method.Typically in a large system you will have one or more central stores, and what you end up passing as parameters are either instances of those stores, or some other kind of index into the store. If there is only one store (as in the case of our Game), you need not pass any parameters at all.
We can rewrite the previous iteration of
DisplayBoard to demonstrate this:class DisplaySquare
param :id
render
BUTTON(class: :square, id: id) { Game.current[id] }
.on(:click) { Game.handle_click(id) }
end
end
class DisplayBoard < HyperComponent
render(DIV) do
(0..6).step(3) do |row|
DIV(class: :board_row) do
(row..row + 2).each { |id| DisplaySquare(id: id) }
end
end
end
end
Here
DisplayBoard no longer takes any parameter (and could be renamed again to DisplayCurrentBoard) and now a new component - DisplaySquare - takes the id of the square to display, but the game or the current board are never passed as parameters; there is no need to as they are implicit.Whether to pass (or not pass) a store class, an instance of a store, or some other index into the store is a design decision that depends on lots of factors, mainly how you see your application evolving over time.
All the observable methods can be used either at the class or instance level.
The
observe method takes any number of arguments and/or a block. The last argument evaluated or the value of the block is returned.The arguments and block are evaluated then the object's state will be observed.
If the block exits with a return or break, the state will not be observed.
# evaluate and return a value
observe @history[@step]
# evaluate a block and return its value
observe do
@history[@step]
end
The
observer method defines a new method with an implicit observe:observer :foo do |x, y, z|
...
end
is equivilent to
def foo(x, y, z)
observe do
...
end
end
Again if the block exits with a
return or break the state will not be observed.The
state_reader method declares one or more state accessors with an implicit state observation:state_reader :bar, :baz
is equivilent to
def bar
observe @bar
end
def baz
observe @baz
end
The
mutate method takes any number of arguments and/or a block. The last argument evaluated or the value of the block is returned.The arguments and block are evaluated then the object's state will be mutated.
If the block exits with a return or break, the state will not be mutated.
# evaluate and return a value
mutate @history[@step]
# evaluate a block and return its value
mutate do
@history[@step]
end
The
mutator method defines a new method with an implicit mutate:mutator :foo do |x, y, z|
...
end
is equivilent to
def foo(x, y, z)
mutate do
...
end
end
Again if the block exits with a
return or break the state will not be mutated.The
state_writer method declares one or more state accessors with an implicit state mutation:state_reader :bar, :baz
is equivilent to
def bar=(x)
mutate @bar = x
end
def baz=(x)
observe @baz = x
end
The
toggle method reverses the polarity of a instance variable:toggle(:foo)
is equivilent to
mutate @foo = !@foo
Combines
state_reader and state_writer methods.state_accessor :foo, :bar
is equivilent to
state_reader :foo, :bar
state_writer :foo, :bar
The standard
HyperComponent base class includes Hyperstack::State::Observable so any HyperComponent has access to all of the above methods. A component also always observes itself so you never need to use observe within a component unless the state will be accessed outside the component. However once you start doing that you would be better off to move the state into a separate store.In addition components also act as the Observers in the system. What this means is that the current component that is running its render method is recording all stores that callobserve, when a store mutates, then all the components that recorded observations will be rerendered.
Last modified 2yr ago