decide.rb 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d042a0810111e7fcb0f9226ad109b20903a8305689df72d25a04caaa17deeff
-  data.tar.gz: d45f4d9aa5edc832dbdf303c8b0ba2e5aa6b7293c8c00614f9f8dfc69186c5c3
+  metadata.gz: 73423e6911201b60ed5a3333ef636880cc93751425e95b39e522bed75d9ca4a5
+  data.tar.gz: 2b352d0c34587f8dfe90e819504e3d07093de738ddde24cea4e96a152f09ce0d
 SHA512:
-  metadata.gz: bf2b770bdabf04def99cbb942d6de633b00a9be6637adec05e81ad52228022e92e0cfc8e71e2e9ac12501febcdb411386242eb341d25e4d0be8f52b62f761ff6
-  data.tar.gz: 614461548e7859a8524cbd6e29961790443e89a10e69d49ec690448af7204afb04a71bf984e8825de3d7b57496753e836e98c0b7ff9c4475d2715838ffaa0075
+  metadata.gz: 8f2e2449fac23e3ae81014a6fd0cfefd5a2a888089c3c89b2072cb52592f6ba5bb659c9f2a816c6d8b13eb6082b463f42594dbffedb2add06469857b7bfe07d0
+  data.tar.gz: 1a310ac9f050f40ba09df6605860fc62b348e093133fd0237618726753d25f5c669f72b723b9072664862d1d80a01898dd963dbd323c97ef30c8533ed9f523e7

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# Unreleased
+
+* Accept more data structures for commands and events
+
+# 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,81 @@
+# 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
+```
+
+## Commands
+
+Commands can be primitives like symbols:
+
+```ruby
+decider = Decider.define do
+  initial_state :initial
+
+  decide :start do |command, state|
+    case state
+    in :initial, :stopped
+      [:started]
+    else
+      []
+    end
+  end
+
+  decide :stop do |command, state|
+    case state
+    in :started
+      [:stopped]
+    else
+      []
+    end
+  end
+end
+```
+
+Or any classes like [Dry::Struct](https://dry-rb.org/gems/dry-struct/) or [Data](https://rubyapi.org/3.3/o/data):
+
+```ruby
+Start = Data.define(:value)
+Stop = Data.define
+
+decider = Decider.define do
+  initial_state :initial
+
+  decide Start do |command, state|
+    case state
+    in :initial, :stopped
+      [:started, command.value]
+    else
+      []
+    end
+  end
+
+  decide Stop do |command, state|
+    case state
+    in :started
+      [:stopped]
+    else
+      []
+    end
+  end
+end
+```
+

data/examples/evolve.md

@@ -0,0 +1,62 @@
+# 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
+```
+
+## Events
+
+Events can be primitives like symbols:
+
+```ruby
+decider = Decider.define do
+  initial_state :initial
+
+  evolve :started do |state, event|
+    :started
+  end
+
+  evolve :stopped do |state, event|
+    :stopped
+  end
+end
+```
+
+Or any classes like [Dry::Struct](https://dry-rb.org/gems/dry-struct/) or [Data](https://rubyapi.org/3.3/o/data):
+
+```ruby
+State = Data.define(:speed)
+Started = Data.define(:speed)
+Stopped = Data.define
+
+decider = Decider.define do
+  initial_state State.new(speed: 0)
+
+  evolve Started do |state, event|
+    State.new(speed: event.speed)
+  end
+
+  evolve Stopped do |state, event|
+    State.new(speed: 0)
+  end
+end
+```
+

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.4.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:, evolutions:, terminal:)
       define_method(:initial_state) do
-        new(**initial_state_args)
+        initial_state
       end
 
       define_method(:commands) do
@@ -15,23 +39,43 @@ module Decider
       end
 
       define_method(:events) do
-        evolvers.keys
+        evolutions.keys
+      end
+
+      define_method(:decide!) do |command, state|
+        case deciders.find { |key, _| key === command }
+        in [_, handler]
+          handler.call(command, state)
+        else
+          raise ArgumentError, "Unknown command: #{command.inspect}"
+        end
       end
 
       define_method(:decide) do |command, state|
-        handler = deciders.fetch(command.class) {
-          raise ArgumentError, "Unknown command: #{command.class}"
-        }
+        case deciders.find { |key, _| key === command }
+        in [_, handler]
+          handler.call(command, state)
+        else
+          []
+        end
+      end
 
-        handler.call(command, state)
+      define_method(:evolve!) do |state, event|
+        case evolutions.find { |key, _| key === event }
+        in [_, handler]
+          handler.call(state, event)
+        else
+          raise ArgumentError, "Unknown event: #{event.inspect}"
+        end
       end
 
       define_method(:evolve) do |state, event|
-        handler = evolvers.fetch(event.class) {
-          raise ArgumentError, "Unknown event: #{event.class}"
-        }
-
-        handler.call(state, event)
+        case evolutions.find { |key, _| key === event }
+        in [_, handler]
+          handler.call(state, event)
+        else
+          state
+        end
       end
 
       define_method(:terminal?) do |state|
@@ -46,38 +90,39 @@ module Decider
     attr_reader :module
 
     def initialize
-      @state = DEFAULT
+      @initial_state = DEFAULT
       @deciders = {}
-      @evolvers = {}
+      @evolutions = {}
       @terminal = ->(_state) { false }
     end
 
     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,
+        evolutions: evolutions,
         terminal: terminal
       )
 
-      @state.extend(@module)
+      decider.extend(@module)
 
-      @state
+      decider
     end
 
     private
 
-    attr_reader :initial_state_args, :deciders, :evolvers, :terminal
+    attr_reader :deciders, :evolutions, :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)
@@ -85,7 +130,7 @@ module Decider
     end
 
     def evolve(event, &block)
-      evolvers[event] = block
+      evolutions[event] = block
     end
 
     def terminal?(&block)
@@ -101,7 +146,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.4.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