hyper-store 1.0.alpha1.8 → 1.0.0.lap28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04e678fd3317d566b6d5fc37af2e9f47a114248160c490e510439c52da2c6b7a
-  data.tar.gz: e8a5ed58f90b3b7bf97aaa755a701b512da9177b53dc195f22a3885b78b54627
+  metadata.gz: 61561ae2ef17af35227e0a5c5227512567e0f3006be750477727e71fd3008e2d
+  data.tar.gz: ac9c2a5d2f4f7193ae73b78fd9f30a00ca5b73ac11c85f765b78792473983872
 SHA512:
-  metadata.gz: 6da5e72a5da18eb0042e8f806cb2dcd8b5c799c8cba8e6fbed39bb80ac96a9d8bc311daa1b65de7fa185d74e983f9d47aec2d6b0bdb8e5fcc2e9a560c31bcf87
-  data.tar.gz: 66b4f2c22194ff8888bfcb72df94523828fce8fbf1a804e64d60f6f3ecea3a0fa1180dfe7d402e6e046cf01645b204754fd2fbd523874dd36eb8618d0f1ddd76
+  metadata.gz: 7003f127e4551440f30587ac10207f54fd5d06a39162f327e5963cc9bcd79c9aeafa200e0040c531a875040fd4fc5ca42fc9968e18c6ee331cbdc871046c466f
+  data.tar.gz: 6aa28c8d48442ecc0f24264a6ea966c09e8b81b5e2b5ff57e03c724b30691b765c51f9df1a73fe84268a252df811e2dffe8ce25adb69169fe687b486e57465e0

data/.gitignore

@@ -11,6 +11,7 @@ capybara-*.html
 **.orig
 rerun.txt
 pickle-email-*.html
+Gemfile.lock
 
 # TODO Comment out these rules if you are OK with secrets being uploaded to the repo
 config/initializers/secret_token.rb
@@ -50,7 +51,3 @@ bower.json
 
 # ignore IDE files
 .idea
-
-# ignore Gemfile.locks https://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/
-/spec/test_app/Gemfile.lock
-/Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,107 @@
+Style/BlockDelimiters:
+  EnforcedStyle: line_count_based
+  SupportedStyles:
+    # The `line_count_based` style enforces braces around single line blocks and
+    # do..end around multi-line blocks.
+    - line_count_based
+    # The `semantic` style enforces braces around functional blocks, where the
+    # primary purpose of the block is to return a value and do..end for
+    # procedural blocks, where the primary purpose of the block is its
+    # side-effects.
+    #
+    # This looks at the usage of a block's method to determine its type (e.g. is
+    # the result of a `map` assigned to a variable or passed to another
+    # method) but exceptions are permitted in the `ProceduralMethods`,
+    # `FunctionalMethods` and `IgnoredMethods` sections below.
+    - semantic
+    # The `braces_for_chaining` style enforces braces around single line blocks
+    # and do..end around multi-line blocks, except for multi-line blocks whose
+    # return value is being chained with another method (in which case braces
+    # are enforced).
+    - braces_for_chaining
+  ProceduralMethods:
+    # Methods that are known to be procedural in nature but look functional from
+    # their usage, e.g.
+    #
+    #   time = Benchmark.realtime do
+    #     foo.bar
+    #   end
+    #
+    # Here, the return value of the block is discarded but the return value of
+    # `Benchmark.realtime` is used.
+    - benchmark
+    - bm
+    - bmbm
+    - create
+    - each_with_object
+    - measure
+    - new
+    - realtime
+    - tap
+    - with_object
+  FunctionalMethods:
+    # Methods that are known to be functional in nature but look procedural from
+    # their usage, e.g.
+    #
+    #   let(:foo) { Foo.new }
+    #
+    # Here, the return value of `Foo.new` is used to define a `foo` helper but
+    # doesn't appear to be used from the return value of `let`.
+    - let
+    - let!
+    - subject
+    - watch
+  IgnoredMethods:
+    # Methods that can be either procedural or functional and cannot be
+    # categorised from their usage alone, e.g.
+    #
+    #   foo = lambda do |x|
+    #     puts "Hello, #{x}"
+    #   end
+    #
+    #   foo = lambda do |x|
+    #     x * 100
+    #   end
+    #
+    # Here, it is impossible to tell from the return value of `lambda` whether
+    # the inner block's return value is significant.
+    - lambda
+    - proc
+    - it
+
+Style/Documentation:
+  Description: 'Document classes and non-namespace modules.'
+  Enabled: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+# Multi-line method chaining should be done with trailing dots.
+Style/DotPosition:
+  EnforcedStyle: leading
+  SupportedStyles:
+    - leading
+    - trailing
+
+Style/FrozenStringLiteralComment:
+  Description: >-
+                 Add the frozen_string_literal comment to the top of files
+                 to help transition from Ruby 2.3.0 to Ruby 3.0.
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Description: 'Avoid multi-line chains of blocks.'
+  StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#single-line-blocks'
+  Enabled: false
+
+Style/MutableConstant:
+  Description: 'Do not assign mutable objects to constants.'
+  Enabled: false
+
+Metrics/AbcSize:
+  # The ABC size is a calculated magnitude, so this number can be a Fixnum or
+  # a Float.
+  Max: 20
+
+Metrics/LineLength:
+  Max: 100

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at mitch@catprint.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/DOCS.md

@@ -0,0 +1,312 @@
+# Hyperloop Stores
+
+Hyperloop **Stores** are implemented in the **HyperStore Gem**.
+
+Stores are where the state of your Application lives. Anything but a completely static web page will have dynamic states that change because of user inputs, the passage of time, or other external events.
+
+```ruby
+class UserStore < Hyperloop::Store
+  state :current, scope: :class, reader: true
+
+  def self.set_current! user
+    mutate.current user
+  end
+end
+
+# to access the store
+UserStore.set_current! user
+UserStore.current_user
+```
+
+**Stores are Ruby classes that keep the dynamic parts of the state in special state variables**
+
++ `Hyperloop::Store::Mixin` can be mixed in to any class to turn it into a Flux Store.
++ You can also create Stores by subclassing `Hyperloop::Store`.
++ Stores are built out of *reactive state variables*.
++ Components that *read* a Store's state will **automatically** update when the state changes.
++ All of your **shared** reactive state should be Stores - *The Store is the Truth*!
++ Stores can *receive* **dispatches** from *Operations*
+
+## Reading and Mutating States
+
+A Store will have one or more *Reactive State Variables* or *State* for short.  States are read using the `state` method, and are changed using the `mutate` method.
+
+`state.items` reads the current value of the state named `items`.  Hyperloop tracks all reads of state, and mutating those states will trigger a re-render of any Components depending on the current value.
+
+`mutate.items` returns the current value of the state named `items`, but also tells Hyperloop that the value is changing, and that any Components depending on the current value will have to be re-rendered.
+
+The one thing you must remember to do is use `mutate` if you intend to update the internal value of a state.  For example if the state contains a hash, and you are updating the Hash's internal value you would use `mutate` otherwise the change will go unrecorded.
+
+#### Initializing States
+
+To assign a new value to a state use the `mutate` method and pass a parameter to the state:
+
+```ruby
+mutate.items(Hash.new { |h, k| h[k] = 0 })
+```
+
+#### Reading States
+
+To read the current value of a state use the `state` method:
+
+```ruby
+state.items # returns current value of items
+```
+
+Typically a store will have quite a few reader (aka getter) methods that hide the details of the state, allowing the Store's implementation to change, without effecting the interface.
+
+#### Mutating States
+
+Often states hold data structures like arrays, hashes, sets, or other Ruby classes, which may be *mutated*.  For example when you push a new value onto an array you will mutate it.  The *value* of the array does not change, but its *contents* does.  If you are accessing a state with the intent to change its content then use the `mutate` method:
+
+```ruby
+mutate.items[item] = value
+```
+
+### Instances and Classes
+
+Stores are often singleton classes.  In an application there is one 'cart' for example.
+
+However sometimes you will want to create a class where each instance is a Store.  This is straight forward because if a state is read or mutated in an instance method, then you will be referring to that instance's copy of the state.
+
+```ruby
+# Each UserStream provides a stream of unique user profiles.
+# Each instance has a single HyperStore state variable called user
+# user will contain a single hash representing the user profile.
+class UserStream < Hyperloop::Store
+
+  # get another user
+
+  def get_another!
+    mutate.user UserStream._select_random_user
+  end
+
+  # extract various attributes from the user hash
+
+  def user_name
+    state.user[:login]
+  end
+
+  def user_url
+    state.user[:html_url]
+  end
+
+  def avatar
+    state.user[:avatar_url]
+  end
+
+  def initialize
+    get_another!
+  end
+
+  def self._select_random_user
+    # _select_random_user provides a stream of unique user profiles.
+    # It will either return a user profile hash, or a promise of one
+    # to come.
+
+    # The cache of users to choose from does not have to be an state
+    # variable, so we use plain instance variables.
+    return @users.delete_at(rand(@users.length)) unless @users.blank?
+    # execute the GetMoreUsers Operation to grab another batch of users
+    # if we are not already waiting on a promise
+    @promise = GetMoreUsers.then do |response|
+      @users = response.json
+    end if @promise.nil? || @promise.resolved?
+    # wait for the promise to resolve then try again
+    @promise.then { _select_random_user }
+  end
+end
+
+class GetMoreUsers < HyperOperation
+  def execute
+    HTTP.get("https://api.github.com/users?since=#{rand(500)}")
+  end
+end
+```
+Stores that have multiple instances will typically have instance methods that directly mutate the store.  We recommend you end these methods with an exclamation (!) to make it clear you are exposing a mutator.
+
+### States and Promises
+
+The above example is greatly simplified because if a promise is assigned to a state it will not mutate  *until the promise resolves*.  Combining this with instance Stores gives a powerful way to encapsulate system behavior.
+
+### Explicitly Declaring States
+
+States like instance variables are created when they are first referenced.
+
+As a convenience you may also explicitly declare states.  This reduces code noise, and improves readability.
+
+```ruby
+class Cart < Hyperloop::Store
+  state items: Hash.new { |h, k| h[k] = 0 }, scope: :class, reader: true
+end
+```
+
+This *declares* the `items` state as a class state variable, will initialize it with the hash on `Hyperloop::Boot`, and provides a reader method.
+That is 6 lines of code for the price of 1, plus now the intention of `items` is clearly defined.
+
+The `state` declaration has the following flavors, depending on how the state is to be initialized:
+
+```ruby
+  state :items, ... other options ... # items will be initialized to nil
+  state items: [1, 2, 3], ... other options ... # items will be initialized to the array [1, 2, 3]
+  state :items, ... other options ... do
+    ... compute initial value ...
+    ... context will be either the class an ...
+    ... instance depending on the scope ...
+  end
+```
+
+Other options to the `state` declaration are:
+
++ `scope:` either `:class`, `:instance`, `:shared`.  Details below!
++ `reader:` either `true`, or a symbol used to declare a reader (getter) method.
++ `initializer:` either a Proc or a Symbol (indicating a method), to be used to initialize the state.
+
+The value of the `scope` option determines where the state resides.
+
++ A class state has one instance per class and is directly accessible in class methods, and indirectly in instances using `self.class.state`.
++ An instance state has a different copy in each instance of the class, and is not accessible by class methods.
++ A shared state is like a class state, but is also directly accessible in instances.
+
+The default value for `scope:` depends on where the state is declared:
+
+```ruby
+  state :items # declares an instance state variable, each instance gets its own state
+  class << self
+    state :items # declares a class instance state variable
+  end
+```
+
+In the above example there is one class instance state named `items` and an additional state variable also called
+items for each instance.
+
+The `shared` option just makes it easier to access a class state from instances.
+
+```ruby
+class MyStore < Hyperloop::Store
+  state :shared_state, scope: :shared
+  state :class_state, scope: :class
+  state :instance_state # scope: :instance is default here
+
+  def instance_method
+    # shared state makes class states easy to access
+    state.shared_state
+    # without shared state class_state is still accessible
+    # with more typing
+    self.class.class_state
+    # each instance gets its own copy of instance states
+    state.instance_state
+    # attempt to access a declared state variable out of context
+    # results in an error!
+    state.class_state # exception!
+  end
+
+  def self.class_method
+    # this is the same state as was referenced in instance_method
+    state.shared_state
+    # and so is this
+    state.class_state
+    # and this will raise an exception
+    state.instance_state
+  end
+```
+
+Class state variables are initialized by an implicit `Hyperloop::Application::Boot` receiver.  If an initial value is directly provided (not via a proc, method or block) then the value will be `dup`ed when the second and following Boot dispatches are received.  The proc, method or block initializers will run in the context of the class, and the state variable will be available.  For example:
+
+```ruby
+state :boot_counter, scope: :shared do
+  (state.boot_counter || 0)+1
+end
+
+# more practically perhaps:
+
+state :my_state, scope: :shared do
+  state.my_state || [] # don't re-initialize me on reboots
+end
+```
+
+Instance variables are initialized when instances of the Store are created.  Each initialization will `dup` the initial value unless supplied by a proc, method or block.
+
+This initialization behavior will work in most cases but for more control simply leave off any initializer, and write your own.
+
+**Note for class states there is a subtle difference between saying:**
+
+```ruby
+state my_state: nil, scope: :shared # or :class
+# and
+state :my_state, scope: :shared # or :class
+
+```
+
+In the first case `my_state` will be re-initialized to nil on every boot, in the second case it will not.
+
+## Receiving Operation Dispatches
+
+Stores can receive Operation dispatches using the receive method.
+
+Here is a simple shopping cart Store that receives Add, Remove and Empty Operations:
+
+```ruby
+class Cart < Hyperloop::Store
+  # First we will define the two Operations.
+  # Because these are closely associated with the Cart
+  # we will name space them inside the cart.
+  class Add < HyperOperation
+    param :item
+    param :qty, type: Integer, min: 1
+  end
+  class Remove < HyperOperation
+    param :item
+    param :qty, type: Integer, nils: true, min: 1
+  end
+  class Empty < HyperOperation
+  end
+
+  # The cart's state is represented as a hash, items are the keys, qty is the value
+  # initialize the hash by receiving the system Hyperloop::Application::Boot or Empty dispatches
+
+  receives Hyperloop::Application::Boot, Empty do
+    mutate.items(Hash.new { |h, k| h[k] = 0 })
+  end
+
+  # The stores getter (or reader) method
+
+  def self.items
+    state.items
+  end
+
+  def self.empty?
+    state.items.empty?
+  end
+
+  receives Add do
+    # notice we use mutate.items since we are modifying the hash
+    mutate.items[params.item] += params.qty
+  end
+
+  receives Remove do
+    mutate.items[params.item] -= params.qty
+    # remove any items with zero qty from the cart
+    mutate.items.delete(params.item) if state.items[params.item] < 1
+  end
+end
+```
+
+This example demonstrates the two ingredients of a Store:
+
++ Receiving Operation Dispatches and
++ Reading, and Mutating *states*.
+
+These are explained in detail below.
+
+The `receive` method takes an list of Operations, and either a symbol (indicating a class method to call), a proc, or a block.
+
+When the dispatch is received the method, proc, or block will be run within the context of the Store's class (not an instance.)  In addition the `params` method from the Operation will be available to access the Operations parameters.
+
+The *Flux* paradigm promotes only mutating state inside of receivers.
+
+Hyperloop is less opinionated.  You may also add mutator methods to your class.  Our recommendation is that you append an exclamation (!) to methods that mutate state.
+
+Note that it is reasonable to have several receivers for the same Operation.  This allows subclassing, mixins, and separation of concerns.
+
+Note also that the Ruby scoping rules make it very reasonable to define the Operations to be received by a Store inside the Store's scope.  This does not change the semantics of either the Store or the Operation, but simply keeps the name space organized.