decide.rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d042a0810111e7fcb0f9226ad109b20903a8305689df72d25a04caaa17deeff
-  data.tar.gz: d45f4d9aa5edc832dbdf303c8b0ba2e5aa6b7293c8c00614f9f8dfc69186c5c3
+  metadata.gz: da945c90e06dab8eb7c391135319bf4f9e126fd2e1904ac4481aabfc4df8943a
+  data.tar.gz: 9e70f93d1ee072b555f7a44b8babc2c0fb0bef50df27949d3bd45654b8c05ed8
 SHA512:
-  metadata.gz: bf2b770bdabf04def99cbb942d6de633b00a9be6637adec05e81ad52228022e92e0cfc8e71e2e9ac12501febcdb411386242eb341d25e4d0be8f52b62f761ff6
-  data.tar.gz: 614461548e7859a8524cbd6e29961790443e89a10e69d49ec690448af7204afb04a71bf984e8825de3d7b57496753e836e98c0b7ff9c4475d2715838ffaa0075
+  metadata.gz: 67a5f37bf266ce6ca5ca35820cc384fa502d33ca0dae794527d160dc7b247eb7e376c96f6dedfe204c348c25436d64db6c934d9fc407daf8e8421c38e23758bd
+  data.tar.gz: aea4f6f4de5a4509ce7b908fb04c59e6546f96c01502b762b564e5c8f44b7b235f380bf98631cf2f906d08eeaf210cde02564ce6060b5fbf9677fcbdd24b675f

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.3.0
+
+* Rename `Decider.state` to `Decider.initial_state`
+* Allow to use anything as state
+* Use tuple-like array for composition
+* Do not raise error when deciding unknown command
+* Do not raise error when evolving unknown event
+
 # 0.2.0
 
 * Added `terminal?` function

data/README.md

@@ -21,6 +21,16 @@ gem "decide.rb"
 ```ruby
 require "decider"
 
+State = Data.define(:value) do
+  def max?
+    value >= MAX
+  end
+  
+  def min?
+    value <= MIN
+  end
+end
+
 module Commands
   Increase = Data.define
   Decrease = Data.define
@@ -36,16 +46,7 @@ MAX = 100
 
 ValueDecider = Decider.define do
   # define intial state
-  state value: 0 do
-    # you can define custom methods on state
-    def max?
-      value >= MAX
-    end
-
-    def min?
-      value <= MIN
-    end
-  end
+  initial_state State.new(value: 0)
 
   # decide command with state
   decide Commands::Increase do |command, state|
@@ -89,8 +90,11 @@ new_state = events.reduce(state) { |state, event| ValueDecider.evolve(state, eve
 You can also compose deciders:
 
 ```ruby
+Left = Data.define(:value)
+Right = Data.define(:value)
+
 left = Decider.define do
-  state value: 0
+  initial_state Left.new(value: 0)
 
   decide Commands::LeftCommand do |command, state|
     [Events::LeftEvent.new(value: command.value)]
@@ -106,7 +110,7 @@ left = Decider.define do
 end
 
 right = Decider.define do
-  state value: 0
+  initial_state Right.new(value: 0)
 
   decide Commands::RightCommand do |command, state|
     [Events::RightEvent.new(value: command.value)]
@@ -124,7 +128,7 @@ end
 Composition = Decider.compose(left, right)
 
 state = Composition.initial_state
-#> #<data left=#<data value=0>, right=#<data value=0>>
+#> #<data left=#<data Left value=0>, right=#<data Right value=0>>
 
 events = Composition.decide(Commands::LeftCommand.new(value: 1), state)
 #> [#<data value=1>]

data/examples/decide.md

@@ -0,0 +1,23 @@
+# Decide
+
+## Handling unknown commands
+
+```ruby
+decider = Decider.define do
+  initial_state :initial
+end
+```
+
+Return empty list of events (nothing changed) by default:
+
+```ruby
+decider.decide :unknown, decider.initial_state
+#> []
+```
+
+Raise error when using `decide!`:
+
+```ruby
+decider.decide! :unknown, decider.initial_state
+#> raise ArgumentError, Unknown command
+```

data/examples/evolve.md

@@ -0,0 +1,23 @@
+# Evolve
+
+## Handling unknown events
+
+```ruby
+decider = Decider.define do
+  initial_state :initial
+end
+```
+
+Return state (nothing changed) by default:
+
+```ruby
+decider.evolve decider.initial_state, :unknown
+#> :initial
+```
+
+Raise error when using `evolve!`:
+
+```ruby
+decider.evolve! decider.initial_state, :unknown
+#> raise ArgumentError, Unknown event
+```

data/examples/state.md

@@ -0,0 +1,65 @@
+# State examples
+
+## Data
+
+```ruby
+State = Data.define(:value)
+
+decider = Decider.define do
+  initial_state State.new(value: 0)
+
+  decide Commands::Command do |command, state|
+    [Events::Event.new(value: command.value)]
+  end
+
+  evolve Events::Event do |state, event|
+    state.with(value: state.value + 1)
+  end
+end
+```
+
+## Primitive
+
+```ruby
+decider = Decider.define do
+  initial_state :turned_off
+
+  decide Commands::TurnOn do |_command, state|
+    case state
+    in :turned_off
+      [Events::TurnedOn.new]
+    else
+      []
+    end
+  end
+
+  decide Commands::TurnOff do |_command, state|
+    case state
+    in :turned_on
+      [Events::TurnedOn.new]
+    else
+      []
+    end
+  end
+
+  evolve Events::TurnedOn do |_state, _event|
+    :turned_off
+  end
+end
+```
+
+## List
+
+```ruby
+decider = Decider.define do
+  initial_state []
+
+  decide Commands::Command do |command, _state|
+    [Events::Event.new(value: command.value)]
+  end
+
+  evolve Events::Event do |state, event|
+    state = state + [event]
+  end
+end
+```

data/lib/decider/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Decider
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/decider.rb

@@ -4,10 +4,34 @@ module Decider
   StateAlreadyDefined = Class.new(StandardError)
   StateNotDefined = Class.new(StandardError)
 
+  class Composition < Array
+    BLANK = Object.new
+    private_constant :BLANK
+
+    def initialize(left, right)
+      super([left, right]).freeze
+    end
+
+    def with(left: BLANK, right: BLANK)
+      Composition.new(
+        (left == BLANK) ? self.left : left,
+        (right == BLANK) ? self.right : right
+      )
+    end
+
+    def left
+      self[0]
+    end
+
+    def right
+      self[1]
+    end
+  end
+
   class Module < ::Module
-    def initialize(initial_state_args:, deciders:, evolvers:, terminal:)
+    def initialize(initial_state:, deciders:, evolvers:, terminal:)
       define_method(:initial_state) do
-        new(**initial_state_args)
+        initial_state
       end
 
       define_method(:commands) do
@@ -18,7 +42,7 @@ module Decider
         evolvers.keys
       end
 
-      define_method(:decide) do |command, state|
+      define_method(:decide!) do |command, state|
         handler = deciders.fetch(command.class) {
           raise ArgumentError, "Unknown command: #{command.class}"
         }
@@ -26,7 +50,15 @@ module Decider
         handler.call(command, state)
       end
 
-      define_method(:evolve) do |state, event|
+      define_method(:decide) do |command, state|
+        handler = deciders.fetch(command.class) {
+          return []
+        }
+
+        handler.call(command, state)
+      end
+
+      define_method(:evolve!) do |state, event|
         handler = evolvers.fetch(event.class) {
           raise ArgumentError, "Unknown event: #{event.class}"
         }
@@ -34,6 +66,14 @@ module Decider
         handler.call(state, event)
       end
 
+      define_method(:evolve) do |state, event|
+        handler = evolvers.fetch(event.class) {
+          return state
+        }
+
+        handler.call(state, event)
+      end
+
       define_method(:terminal?) do |state|
         terminal.call(state)
       end
@@ -46,7 +86,7 @@ module Decider
     attr_reader :module
 
     def initialize
-      @state = DEFAULT
+      @initial_state = DEFAULT
       @deciders = {}
       @evolvers = {}
       @terminal = ->(_state) { false }
@@ -55,29 +95,30 @@ module Decider
     def build(&block)
       instance_exec(&block) if block_given?
 
-      raise StateNotDefined if @state == DEFAULT
+      raise StateNotDefined if @initial_state == DEFAULT
+
+      decider = Object.new
 
       @module = Module.new(
-        initial_state_args: initial_state_args,
+        initial_state: @initial_state,
         deciders: deciders,
         evolvers: evolvers,
         terminal: terminal
       )
 
-      @state.extend(@module)
+      decider.extend(@module)
 
-      @state
+      decider
     end
 
     private
 
-    attr_reader :initial_state_args, :deciders, :evolvers, :terminal
+    attr_reader :deciders, :evolvers, :terminal
 
-    def state(**kwargs, &block)
-      raise StateAlreadyDefined if @state != DEFAULT
+    def initial_state(state)
+      raise StateAlreadyDefined if @initial_state != DEFAULT
 
-      @state = Data.define(*kwargs.keys, &block)
-      @initial_state_args = kwargs
+      @initial_state = state
     end
 
     def decide(command, &block)
@@ -101,7 +142,7 @@ module Decider
 
   def self.compose(left, right)
     define do
-      state left: left.initial_state, right: right.initial_state
+      initial_state Composition.new(left.initial_state, right.initial_state)
 
       left.commands.each do |klass|
         decide klass do |command, state|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decide.rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jan Dudulski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-04 00:00:00.000000000 Z
+date: 2024-11-11 00:00:00.000000000 Z
 dependencies: []
 description: Functional Event Sourcing Decider in Ruby
 email:
@@ -23,6 +23,9 @@ files:
 - README.md
 - Rakefile
 - Steepfile
+- examples/decide.md
+- examples/evolve.md
+- examples/state.md
 - lib/decider.rb
 - lib/decider/version.rb
 - sig/decider.rbs