statecraft 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1694416ac7a88eff03c4f73c1fab5c0b2d8bd182f7c8d88d72c4eb1da2574ecc
-  data.tar.gz: 4fa98301ac81c1d5b2cee6007048fe05f2ea6db36400cb2d6844d8f19fef9011
+  metadata.gz: b9f0a6cac349045859dd7966a325ae9d0a4b27175b846e8f43bd924b298576b6
+  data.tar.gz: a148de67af8ddd2bb976ae5ed03db6a38122ebd795013f9aae6c5803e45f7120
 SHA512:
-  metadata.gz: 6cc41535452dc33140e39f342c07488491b595c945538fc71f661e2233d03f2e922a52a3182e6d2022f57c2eed5cc494810126189f280fc532aae973d5eb2f4b
-  data.tar.gz: bc485f03bcee46d53f027d955def314aa7f2836211811dba751c93b2a29eaa8887a944479d2fb62ab62f540aa0e43aca0813c95f115212488e9495f80a8b8f90
+  metadata.gz: a48dbba9f2e06f23bbcffc0fc632f17f6915954737c2f104c132fa8763823bb9f07a0e754dabf4eb95d14b21b97c912885d0d1efa252c7e3ce64cedeeb206a22
+  data.tar.gz: 8256c0463e14d6ddf19d2a757647f81bae4bfa73ecc37796f905adc82d397dbdcb730c45861d23b172711e75aff224482de7dbbdc94a07fbbc9c4cca95fd4c37

data/README.md

@@ -349,6 +349,26 @@ degrades — the locking clause is dropped, the reload still runs, and
 statecraft warns once per machine per process that row-locking guarantees
 require PostgreSQL.
 
+## Running the tests
+
+Natively, against SQLite:
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+Against PostgreSQL — where the concurrency proof actually runs — point
+`DATABASE_URL` at a database of your own, or use the bundled containers, which
+pin the same PostgreSQL major as CI and take the Ruby and ActiveRecord versions
+as parameters, so any CI matrix cell reproduces locally:
+
+```sh
+docker compose run --rm test                                # sqlite, default Ruby
+docker compose run --rm test-postgres                       # PostgreSQL 16
+AR_VERSION=7.2 RUBY_VERSION=3.3 docker compose run --rm test-postgres
+```
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/statecraft/machine/machine_generator.rb

@@ -93,13 +93,6 @@ module Statecraft
       def migration_class_name
         "Create#{class_name}StateMachine"
       end
-
-      def metadata_column_type
-        adapter = ActiveRecord::Base.connection.adapter_name
-        adapter.match?(/postg/i) ? "jsonb" : "json"
-      rescue ActiveRecord::ActiveRecordError
-        "jsonb"
-      end
     end
   end
 end

data/lib/generators/statecraft/machine/templates/add_migration.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :state, :string, null: false, default: "pending"
+    add_index :<%= table_name %>, :state
+    add_column :<%= table_name %>, :state_changed_at, :datetime
+
+    # The existing table may carry legacy values, so no CHECK constraint is
+    # generated here. To add one later without blocking writes:
+    #   ALTER TABLE ... ADD CONSTRAINT ... CHECK (state IN (...)) NOT VALID;
+    #   -- clean the data --
+    #   ALTER TABLE ... VALIDATE CONSTRAINT ...;
+
+    create_table :<%= log_table_name.pluralize %> do |t|
+      t.references :<%= file_name %>, null: false,
+                                      foreign_key: { to_table: :<%= table_name %>, on_delete: :cascade },
+                                      index: false
+      t.string :from_state, null: false
+      t.string :to_state, null: false
+      t.string :event
+      t.column :metadata, metadata_column_type, null: false, default: {}
+      t.datetime :created_at, null: false
+      t.index %i[<%= foreign_key_column %> id]
+    end
+  end
+
+  private
+
+  # jsonb where the database has it, json elsewhere: the adapter is known
+  # only when the migration actually runs, never at generation time.
+  def metadata_column_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/lib/generators/statecraft/machine/templates/application_machine.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Shared home for private guard helpers used by several machines. Keep it
+# free of DSL declarations (states, transitions, events): machine definitions
+# are NOT inherited — each machine declares its own graph.
+class ApplicationMachine
+  include Statecraft::Machine
+end

data/lib/generators/statecraft/machine/templates/create_migration.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :state, null: false, default: "pending", index: true
+      t.datetime :state_changed_at
+      t.timestamps null: false
+    end
+
+    # add new states here when the machine grows
+    add_check_constraint :<%= table_name %>, "state IN ('pending')",
+                         name: "<%= table_name %>_state_check"
+
+    create_table :<%= log_table_name.pluralize %> do |t|
+      t.references :<%= file_name %>, null: false,
+                                      foreign_key: { to_table: :<%= table_name %>, on_delete: :cascade },
+                                      index: false
+      t.string :from_state, null: false
+      t.string :to_state, null: false
+      t.string :event
+      t.column :metadata, metadata_column_type, null: false, default: {}
+      t.datetime :created_at, null: false
+      t.index %i[<%= foreign_key_column %> id]
+    end
+  end
+
+  private
+
+  # jsonb where the database has it, json elsewhere: the adapter is known
+  # only when the migration actually runs, never at generation time.
+  def metadata_column_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/lib/generators/statecraft/machine/templates/log_model.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Append-only transition log for <%= class_name %>. This is a read-model:
+# scopes, reading methods and serializers are yours; the transition pipeline
+# writes rows through the insert path and never calls validations or
+# callbacks declared here.
+class <%= class_name %>Transition < <%= parent_class_name %>
+  def readonly? = persisted?
+end

data/lib/generators/statecraft/machine/templates/machine.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Flow < ApplicationMachine
+  state :pending, initial: true
+  # state :paid
+  #
+  # event :pay, from: :pending, to: :paid, guard: :payable?
+  #
+  # Guards and callbacks resolve to instance methods of this class:
+  #
+  # private
+  #
+  # def payable?(record, metadata)
+  #   metadata["amount"].to_i.positive?
+  # end
+end

data/lib/generators/statecraft/machine/templates/model.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationRecord
+  state_machine <%= class_name %>Flow, changed_at: true, helpers: true, scopes: true
+end

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Igor Pugachev
@@ -61,6 +61,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/generators/statecraft/machine/machine_generator.rb
+- lib/generators/statecraft/machine/templates/add_migration.rb.tt
+- lib/generators/statecraft/machine/templates/application_machine.rb.tt
+- lib/generators/statecraft/machine/templates/create_migration.rb.tt
+- lib/generators/statecraft/machine/templates/log_model.rb.tt
+- lib/generators/statecraft/machine/templates/machine.rb.tt
+- lib/generators/statecraft/machine/templates/model.rb.tt
 - lib/statecraft.rb
 - lib/statecraft/errors.rb
 - lib/statecraft/instrumentation.rb
@@ -71,9 +77,14 @@ files:
 - lib/statecraft/pipeline.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb
+homepage: https://supostat.github.io/statecraft/
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://supostat.github.io/statecraft/
+  source_code_uri: https://github.com/supostat/statecraft
+  changelog_uri: https://github.com/supostat/statecraft/releases
+  bug_tracker_uri: https://github.com/supostat/statecraft/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: