rails_redhot 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5be8aff1e9314532378f476e76fe310b84bfe386abe0ba18c33ec60820696d24
-  data.tar.gz: f77470f8cec6b501c56fb0102e1b63242b0a11a4c453d4bbe3b3068b148b88fe
+  metadata.gz: 8f5c72d2cc5029c74afb124b5bbc728d007f4d635ad9569781cdd5b2fa3f6e25
+  data.tar.gz: eaca540b27f70101cefaee8d29e78ab843c12d873ee89bc382b28a0af963ee28
 SHA512:
-  metadata.gz: adbb2a15f3bcffe7b910b05217d5e564125915bd39710347b527a863462fb7bef50951358d0b2d31829994410abca865f88f183abe09e09e0aef8be56956a5bf
-  data.tar.gz: 922d4eac6e294a8f25ac027eca82c457115884758fc785289c79867785618aa0f7a788975e5f66fcb4139bfd819cca39b4b263d6d7d8df989a6cdc03bec8f97d
+  metadata.gz: 3029222021c8639cba0a7d60e9684e4571bbcd391c1a8884fdf2386b0a0c0b6b28afb4e85816a9f6f6f95d50a80825de754e2dc74939ca4511f0c6eb6c57fa3b
+  data.tar.gz: 6a27cf8634d4ccb20e833a79352ab810d2fe674c2e077a2a9c672d993657d7eb90a9ce2af7bbbd6e72981f03f11c22b4953c92e636bea25c6c2cabe1f8b70940

data/CHANGELOG.md

@@ -1,10 +1,28 @@
-# 0.0.2 - December 10, 2021
+# 0.2.0 - March 14, 2023
+
+- Demo application: Use Ruby 3.2.0, Rails 7.0.4.2
+- Added simplecov and improve testcoverage
+- Added reducer errors (ActiveModel::Errors), separate from the models own error object
+- Use deep_dup before dispatching an action to make sure the original action is never
+  modified by reducer methods. Use deep_symbolize_keys on an action for convenience
+- Added after_change callback
+
+# 0.1.1 - April 14, 2022
+
+- Fix calling flatten! multiple times erased initial state
+- Documentation updates
+- Demo application: Use Ruby 3.1.2, Rails 7.0.2
 
-[0.0.2]: https://github.com/easydatawarehousing/rails_redhot/compare/v0.0.1...v0.0.2
+# 0.1.0 - December 30, 2021
+
+- Documentation updates
+- Use Rails 7.0.0
+
+# 0.0.2 - December 10, 2021
 
 - Added testset
 - Polished demo application
 
 # 0.0.1 - November 16, 2021
 
-- Initial release, not pulished to rubygems
+- Initial release, not published to rubygems

data/README.md

@@ -1,34 +1,76 @@
 # RailsRedhot gem
-__REDux pattern for HOTwire == Redhot__  
+### __REDux pattern for HOTwire == Redhot__
 Single page applications using redux (react) are very popular.
 And with good reason, redux makes maintaining the current state of the app easy.
 For instance when building some kind of editor, every action of the user is added
 to the redux store. All actions can be reduced to the determine the current state of
 the editor. Views are rendered using the current state.  
-Or when building a search page for a webshop. Whenever the user selects a category
+Or when building a complex search page for a webshop. Whenever the user selects a category
 or price range to filter on this can be an action for the redux store. If the user
 hits the back button the last action can be deleted and the current state
 regenerated by reducing all remaining actions. The user only sees the last filter
 being reverted to what it was before.
 
+### What is redux?
+```
+It is a store containing a list of changes.
+All changes combined determine the current view state through one or more reducer functions.
+The current view state is also stored.
+If a new change arrives it only needs to be applied to the current view state.
+To undo a change apply all but the last action again to rebuild te view state.
+
+For example a view contains a number counting the likes for an article.
+There are two buttons: increase- and decrease the likes counter.
+Clicking on a button adds an action to the store.
+The action is passed on to all reducer functions,
+each function passes the new computed state on to the next function:
+- If the counter value is nil in the current state set it to zero
+- If the action was 'increase' then increment the counter value
+- If the action was 'decrease' then decrement the counter value
+- If the counter value is lower than zero set it to zero
+Save the new state in the store.
+Render the view showing the updated counter value.
+```
+
+### What are the advantages of redux?
+From the [redux website](https://redux.js.org/) (minus the part about plugins):
+```
+Predictable
+Redux helps you write applications that behave consistently,
+run in different environments (client, server, and native)
+and are easy to test.
+
+Centralized
+Centralizing your application's state and logic enables powerful capabilities
+like undo/redo, state persistence, and much more.
+
+Debuggable
+The Redux DevTools make it easy to trace when, where, why
+and how your application's state changed.
+Redux's architecture lets you log changes, use 'time-travel debugging'
+and even send complete error reports to a server.
+```
+
+### Remove complexity
 Sometimes the actions of the user in the frontend should be sent to a backend
 application. For instance when actions of multiple users should be kept in-sync.
-Often command-query-responsibility-separation (CQRS) is used for this purpose.
-These solutions can become very complex
+In react applications command-query-responsibility-separation (CQRS) is often
+used for this purpose. These solutions can become very complex
 ([example](https://medium.com/resolvejs/resolve-redux-backend-ebcfc79bbbea),
-scroll down a bit for a full example).
+scroll down a bit for a full architecture picture).
 
 The Hotwire (Html Over The Wire) approach does an excellent job of removing the need
-to build single page apps. Hotwire will be the
+to build single page apps. Hotwire is the
 [default tool](https://world.hey.com/dhh/the-time-is-right-for-hotwire-ecdb9b33)
 for frontend development in Rails 7.
 However when using hotwire the responsibilty of maintaining frontend state entirely
 falls to the backend application. So when building your editor or search page
-you need a way to keep track of that state. The redux (also known as flux) pattern
-is still very useful for this purpose.
+you need a way to keep track of that state. The redux (also known as flux- or observer-)
+pattern is very useful for this purpose.
 
+### Hotwire
 This gem aims to combine html-over-the-wire approach with the redux pattern to
-radically reduce complexity of the overall application.
+radically reduce overall complexity of an application.
 (At least when compared to for instance react+cqrs application stacks.)
 Only four components are required:
 
@@ -39,9 +81,16 @@ Only four components are required:
 4. Reducers, a set of functions (provided by you) that translate actions to changes in
    state. The state can be used again in step 1
 
-Common actions (undo, redo, flatten actions to initial state) are provided by this gem.
-Combined with turbo frames for rendering partial page updates this makes it easy to
-create a very smooth user experience.
+### Benefits
+
+- Straightforward workflow
+- Common actions (undo, redo, flatten actions to initial state) are provided by this gem.
+  Combined with turbo frames for rendering partial page updates this makes it easy to
+  create a very smooth user experience
+- You can create a store of attributes within a single ActiveRecord model.
+  In a Single Page App (SPA) lots of settings may be needed for a good user
+  experience. It may be a lot of work to store these in multiple models.
+  A redux store can hold an arbitrary amount of attributes
 
 ## Usage
 ### Model
@@ -60,15 +109,17 @@ class Foobar < ApplicationRecord
   private
 
   def my_redux_reducers
-  ->(state, action) {
-    case action[:type]
-    when :add
-      state[:total] += 1
-    when :remove
-      state[:total] -= 1
-    end
-    state
-  },
+    [
+      ->(state, action) {
+        case action[:type]
+        when :add
+          state[:total] += 1
+        when :remove
+          state[:total] -= 1
+        end
+        state
+      }
+    ]
   end
 end
 ```
@@ -79,7 +130,7 @@ Or specify your own reducer method:
 acts_as_redux :my_redux, reducers: :my_list_of_reducers
 
 def my_list_of_reducers
-# ...
+  # ...
 ```
 
 ### Undo/redo
@@ -99,7 +150,8 @@ In the controller action use the `undo!` method to perform the action.
 For redoing actions the similar methods `redo?`, `redo_action` and `redo!` are available.
 
 ### Flatten
-You can 'save' the current state. Essentially this flattens the list of actions to the initial state.
+You can 'save' the current state. Essentially this copies the current view state to the initial state
+and truncates the list of actions. Redo and undo are not possible until new actions are added.
 Methods `flatten?` and `flatten!` can be used in a view and controller:
 
 ```ruby
@@ -112,7 +164,7 @@ Methods `flatten?` and `flatten!` can be used in a view and controller:
 ```
 
 ### Sequence ID
-As a convenience a sequence ID id available which should always return a unique id
+As a convenience a sequence ID id is available which should always return a unique id
 (within the context of the model instance). To get the next sequence id use `next_seq_id`,
 to get the current sequence value use `seq_id`.
 You could use a sequence in a reducer function to make sure every added item is assigned a unique id.
@@ -143,11 +195,86 @@ on the reducer functions you have implemented.
 For a full working example see the demo applications [view](test/dummy/app/views/foobars/_editor.html.erb)
 and [controller](test/dummy/app/controllers/foobars_controller.rb).
 
+### Adding errors
+Just like you can add validation errors on a model, you can add errors inside your reducer methods.
+There is an ActiveModel::Errors object for redux errors. It is separate from the one for the model and
+can be accessed via `reduce_errors`. Use it like this:
+
+```ruby
+def my_redux_reducers
+  @my_redux_reducers ||= [
+    -> (state, action) {
+      case action[:type]&.to_sym
+      when :add
+        if action[:item].length <= 6
+          state[:items] << { id: next_seq_id, value: CGI.escape(action[:item]) }
+        else
+          reduce_errors.add(:item, :too_long, { count: 6 })
+        end
+      end
+
+      state
+    }
+  ]
+end
+```
+
+Since ActiveModel does not know anything about attributes living inside your redux store
+using `reduce_errors.full_messages` won't work. You can create you own error to message translation or
+supply `:base` as the attribute name plus a message.
+See the [Rails documentation](https://api.rubyonrails.org/classes/ActiveModel/Errors.html#method-i-add).
+
+```ruby
+reduce_errors.add(:base, message: 'Item should have between 1 and 6 characters')
+```
+
+If any reduce error is present the `dispatch!` method will return false.
+To check if there are any errors present (to prevent saving the model) use:
+
+```ruby
+@foobar.reduce_valid?
+```
+
+In the controller you may want to reload the model if the dispatch action gave an error,
+so the old state is rendered.
+
+### After change callback
+Sometimes you want to do something after the redux store has changed.
+For instance to manipulate the view state based on all entries
+(the reducer methods only handle one action at the time).
+This callback method is called after `dispatch!`, `undo!` and `redo!`.
+In the model:
+
+```ruby
+class AnotherFooBar < ApplicationRecord
+  include RailsRedhot::ActsAsRedux
+
+  acts_as_redux :another_redux_store, after_change: :my_after_change_actions
+
+  private
+
+    def another_redux_store_reducers
+      [
+        -> (state, _action) {
+          state[:items] ||= []
+          state
+        },
+        # ...
+      ]
+    end
+
+    def my_after_change_actions
+      # Do something with the view_state
+      # view_state[:items].each { do_something }
+    end
+end
+```
+
 ## Security
-Care must be taken to not introduce any vulnerabilities.
+Care must be taken to not introduce any vulnerabilities!
 When passing values from the request to the reducer functions treat any string or complex
-values as potential candidates for SQL injection. Either sanitize the value or `CGI.escape`
-a string before adding it to the redux store.
+values as potential candidates for SQL injection. Either sanitize or `CGI.escape`
+strings before adding them to the redux store.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -175,7 +302,7 @@ cd rails_redhot
 bundle install
 cd test/dummy
 rails db:setup
-rails server
+bin/dev
 ```
 
 Then open the [application](http://localhost:3000/foobars).
@@ -193,10 +320,9 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Remarks
 
-- Developed using Ruby 3.0.3
 - This gem is not designed to handle very large lists of actions and state.
-  When calling `undo` the state is rebuilt from scratch
-  If the list of actions to process is large this would become slow.
+  When calling `undo` the state is rebuilt from scratch,
+  if the list of actions to process is large this would become slow.
   One would need add 'savepoints' that regularly save the state and rebuild
   the current state from that point forward
 - Stricly speaking, hotwire is not needed for this gem to work. Just using

data/lib/rails_redhot/acts_as_redux.rb

@@ -8,6 +8,8 @@ module RailsRedhot
     class_methods do
       def acts_as_redux(store_name, options = {})
         reducers = options.key?(:reducers) ? options[:reducers] : "#{store_name}_reducers".to_sym
+        reducer_errors = nil
+        reducer_after_change = options[:after_change]
 
         store(store_name, accessors: [ :initial_state, :state, :actions, :head, :seq_id ], coder: JSON)
 
@@ -43,8 +45,7 @@ module RailsRedhot
             self.state = initial_state
             if head > -1
               actions[0..head].each { |action| perform_reduce(action) }
-            else
-              perform_reduce(initial_state)
+              self.send(reducer_after_change) if reducer_after_change
             end
             true
           else
@@ -56,6 +57,7 @@ module RailsRedhot
           if redo?
             self.head += 1
             perform_reduce(actions[head])
+            self.send(reducer_after_change) if reducer_after_change
             true
           else
             false
@@ -63,13 +65,21 @@ module RailsRedhot
         end
 
         define_method('flatten!') do
-          self.initial_state = state
+          self.initial_state = view_state
           self.state         = nil
           self.head          = -1
           self.actions       = []
           true
         end
 
+        define_method('reduce_errors') do
+          reducer_errors
+        end
+
+        define_method('reduce_valid?') do
+          reducer_errors.details.empty?
+        end
+
         define_method('next_seq_id') do
           self.seq_id += 1
         end
@@ -80,19 +90,29 @@ module RailsRedhot
 
           self.actions << action
           self.head += 1
-          perform_reduce(action)
-          true
+          perform_reduce(action.deep_dup.deep_symbolize_keys)
+          self.send(reducer_after_change) if reducer_after_change
+          reduce_valid?
         end
 
         # private
 
+          define_method('reset_reduce_errors') do
+            reducer_errors = ActiveModel::Errors.new(self)
+          end
+
           define_method('load_store') do
             self.initial_state ||= {}
             # self.state is initially nil: no need to store state twice when there are no actions
             self.head          ||= -1
             self.actions       ||= []
             self.seq_id        ||= 0
-            perform_reduce({}) if state.blank? && initial_state.blank?
+
+            if state.blank? && initial_state.blank?
+              perform_reduce({})
+            else
+              reset_reduce_errors
+            end
           end
 
           define_method('all_reducers') do
@@ -100,10 +120,12 @@ module RailsRedhot
           end
 
           define_method('perform_reduce') do |action|
+            reset_reduce_errors
+
             self.state = all_reducers.reduce(
-              view_state.dup.deep_symbolize_keys
+              view_state.deep_dup.deep_symbolize_keys
             ) do |current_state, reducer|
-              reducer.call(current_state, action.deep_symbolize_keys)
+              reducer.call(current_state, action)
             end
           end
 

data/lib/rails_redhot/version.rb

@@ -1,4 +1,4 @@
 module RailsRedhot
   # Gem version
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_redhot
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ivo Herweijer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-30 00:00:00.000000000 Z
+date: 2023-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.4.6
 signing_key: 
 specification_version: 4
 summary: REDux pattern for HOTwire == Redhot