decide.rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b7afded6cbe7cf6fd572d9a7779875e901dbe81b25292847eea0377a549538c
-  data.tar.gz: 713abc6c3365c06b611a254859bb83fe0a642c26bef2ee51c8c53eb075c47e72
+  metadata.gz: da945c90e06dab8eb7c391135319bf4f9e126fd2e1904ac4481aabfc4df8943a
+  data.tar.gz: 9e70f93d1ee072b555f7a44b8babc2c0fb0bef50df27949d3bd45654b8c05ed8
 SHA512:
-  metadata.gz: 969092990e15943086821f2821d44d73e6bff46e77aa865904cf8152dd4cdadc65a979bfa6edd241583f2aee2748fd229b86f5e2a188fd04c9306c1b5209c963
-  data.tar.gz: 29b205b6af520c32e971c6e6a5691f9d4cd4e745a0290fd932ee96217018a69a7429722eb7fa3c66b74e204f10529406075cf6e3e2aa8e89af053139f86c9838
+  metadata.gz: 67a5f37bf266ce6ca5ca35820cc384fa502d33ca0dae794527d160dc7b247eb7e376c96f6dedfe204c348c25436d64db6c934d9fc407daf8e8421c38e23758bd
+  data.tar.gz: aea4f6f4de5a4509ce7b908fb04c59e6546f96c01502b762b564e5c8f44b7b235f380bf98631cf2f906d08eeaf210cde02564ce6060b5fbf9677fcbdd24b675f

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# 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
+* `Decider.compose(left, right)`
+
 # 0.1.0
 
 * Initial release

data/README.md

@@ -19,7 +19,17 @@ gem "decide.rb"
 ## Usage
 
 ```ruby
-require "decide.rb"
+require "decider"
+
+State = Data.define(:value) do
+  def max?
+    value >= MAX
+  end
+  
+  def min?
+    value <= MIN
+  end
+end
 
 module Commands
   Increase = Data.define
@@ -31,21 +41,12 @@ module Events
   ValueDecreased = Data.define
 end
 
-ValueDecider = Decider.define do
-  MIN = 0
-  MAX = 100
+MIN = 0
+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|
@@ -75,6 +76,10 @@ ValueDecider = Decider.define do
     # state is immutable Data object
     state.with(value: state.value - 1)
   end
+
+  terminal? do |state|
+    state <= 0
+  end
 end
 
 state = ValueDecider.initial_state
@@ -82,6 +87,56 @@ events = ValueDecider.decide(Commands::Increase.new, state)
 new_state = events.reduce(state) { |state, event| ValueDecider.evolve(state, events)
 ```
 
+You can also compose deciders:
+
+```ruby
+Left = Data.define(:value)
+Right = Data.define(:value)
+
+left = Decider.define do
+  initial_state Left.new(value: 0)
+
+  decide Commands::LeftCommand do |command, state|
+    [Events::LeftEvent.new(value: command.value)]
+  end
+
+  evolve Events::LeftEvent do |state, event|
+    state.with(value: state.value + 1)
+  end
+
+  terminal? do |state|
+    state <= 0
+  end
+end
+
+right = Decider.define do
+  initial_state Right.new(value: 0)
+
+  decide Commands::RightCommand do |command, state|
+    [Events::RightEvent.new(value: command.value)]
+  end
+
+  evolve Events::RightEvent do |state, event|
+    state.with(value: state.value + 1)
+  end
+
+  terminal? do |state|
+    state <= 0
+  end
+end
+
+Composition = Decider.compose(left, right)
+
+state = Composition.initial_state
+#> #<data left=#<data Left value=0>, right=#<data Right value=0>>
+
+events = Composition.decide(Commands::LeftCommand.new(value: 1), state)
+#> [#<data value=1>]
+
+state = events.reduce(state, &Composition.method(:evolve))
+#> #<data left=#<data value=1>, right=#<data value=0>>
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Steepfile

@@ -0,0 +1,26 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+  check "Gemfile"
+
+  # library "pathname"              # Standard libraries
+  # library "strong_json"           # Gems
+
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+# target :test do
+#   signature "sig", "sig-private"
+
+#   check "test"
+
+#   # library "pathname"              # Standard libraries
+# end

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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/decider.rb

@@ -4,13 +4,45 @@ 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:)
+    def initialize(initial_state:, deciders:, evolvers:, terminal:)
       define_method(:initial_state) do
-        new(**initial_state_args)
+        initial_state
       end
 
-      define_method(:decide) do |command, state|
+      define_method(:commands) do
+        deciders.keys
+      end
+
+      define_method(:events) do
+        evolvers.keys
+      end
+
+      define_method(:decide!) do |command, state|
         handler = deciders.fetch(command.class) {
           raise ArgumentError, "Unknown command: #{command.class}"
         }
@@ -18,13 +50,33 @@ 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}"
         }
 
         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
     end
   end
 
@@ -34,36 +86,39 @@ module Decider
     attr_reader :module
 
     def initialize
-      @state = DEFAULT
+      @initial_state = DEFAULT
       @deciders = {}
       @evolvers = {}
+      @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
+        evolvers: evolvers,
+        terminal: terminal
       )
 
-      @state.extend(@module)
+      decider.extend(@module)
 
-      @state
+      decider
     end
 
     private
 
-    attr_reader :initial_state_args, :deciders, :evolvers
+    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)
@@ -73,6 +128,10 @@ module Decider
     def evolve(event, &block)
       evolvers[event] = block
     end
+
+    def terminal?(&block)
+      @terminal = block
+    end
   end
   private_constant :Builder
 
@@ -80,4 +139,42 @@ module Decider
     builder = Builder.new
     builder.build(&block)
   end
+
+  def self.compose(left, right)
+    define do
+      initial_state Composition.new(left.initial_state, right.initial_state)
+
+      left.commands.each do |klass|
+        decide klass do |command, state|
+          left.decide(command, state.left)
+        end
+      end
+
+      right.commands.each do |klass|
+        decide klass do |command, state|
+          right.decide(command, state.right)
+        end
+      end
+
+      left.events.each do |klass|
+        evolve klass do |state, event|
+          state.with(
+            left: left.evolve(state.left, event)
+          )
+        end
+      end
+
+      right.events.each do |klass|
+        evolve klass do |state, event|
+          state.with(
+            right: right.evolve(state.right, event)
+          )
+        end
+      end
+
+      terminal? do |state|
+        left.terminal?(state.left) && right.terminal?(state.right)
+      end
+    end
+  end
 end

data/sig/decider.rbs

@@ -1,3 +1,16 @@
 module Decider
   VERSION: String
+
+  interface _Decider[C, S, E]
+    def decide: (C, S) -> Array[E]
+
+    def evolve: (S, E) -> S
+
+    def initial_state: () -> S
+
+    def terminal?: (S) -> bool
+  end
+
+  def self.compose: [C1, S1, E1, C2, S2, E2] (_Decider[C1, S1, E1], _Decider[C2, S2, E2]) -> _Decider[C1 | C2, S1 & S2, E1 | E2]
+  def self.define: [C, S, E] () -> _Decider[C, S, E]
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decide.rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jan Dudulski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-20 00:00:00.000000000 Z
+date: 2024-11-11 00:00:00.000000000 Z
 dependencies: []
 description: Functional Event Sourcing Decider in Ruby
 email:
@@ -22,19 +22,23 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
+- examples/decide.md
+- examples/evolve.md
+- examples/state.md
 - lib/decider.rb
 - lib/decider/version.rb
 - sig/decider.rbs
-homepage: https://github.com/jandudulski/decider.rb
+homepage: https://github.com/jandudulski/decide.rb
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  bug_tracker_uri: https://github.com/jandudulski/decider.rb/issues
-  changelog_uri: https://github.com/jandudulski/decider.rb/CHANGELOG.md
-  documentation_uri: https://github.com/jandudulski/decider.rb
-  homepage_uri: https://github.com/jandudulski/decider.rb
-  source_code_uri: https://github.com/jandudulski/decider.rb
+  bug_tracker_uri: https://github.com/jandudulski/decide.rb/issues
+  changelog_uri: https://github.com/jandudulski/decide.rb/CHANGELOG.md
+  documentation_uri: https://github.com/jandudulski/decide.rb
+  homepage_uri: https://github.com/jandudulski/decide.rb
+  source_code_uri: https://github.com/jandudulski/decide.rb
 post_install_message:
 rdoc_options: []
 require_paths: