composable-core 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70e5155da7770ce04fad201ba581124b87f97ea3979d58f6d632667332c19128
-  data.tar.gz: 71d9e06091dd8393992300ef63511e47ca0cd82ad8f31721b310088d4e502f63
+  metadata.gz: 6f4df88ab1a3ea8dfe4a54166f06d63608f480683efe0bc31beea1f2ca0b02e9
+  data.tar.gz: 307e555872f0f2a58ad7861cf9919643f66cf5d629ac45ba0667e935f02885af
 SHA512:
-  metadata.gz: d49c2269c53bfc9547cb5a3a17962fc2db38ac490b377e75250f503f091e232efcb1aef030db020d1ed8f4f138b9b3986b5b768f07c5560c7f1278209db8882a
-  data.tar.gz: 85397c8020abf54b51976494ccc9aef9ba71e8714b2618990243aa0845687b246627950afc71e2f1c1e1cc52a9621ffaef7355d435e7e4c46dd85c7d03fa2f27
+  metadata.gz: 265a79bd34dd978dd60005f4c474d43a42730270f4a4173e690739933526a02e601c9417254e9508752433aee321ba4363cd8c5c860f40c123deaf6f818b57ba
+  data.tar.gz: d769eb62f1232b101a9339f2a3951d8aa13f1b6fa54210d65ace8c0b92efb4011a5cd79cbddeea5c3db5ec34d90155b1f6cc1c5a63ff99276a3abaa8dd5cebf7

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+- Evaluate composable eligibility once before synchronization and reuse it for persistence.
+- Preserve reverse synchronization for predeclared record attributes.
+- Copy constructor inputs and preserve explicit nil and symbol-key precedence.
+- Deep-copy inheritance defaults and replace interpolated accessor generation.
+- Preserve process-control exceptions and handle record validation without mutating errors, including late ActiveRecord loading.
+- Replace placeholder tests and enforce complete line/branch coverage.
+
 ## [0.0.1] - 2022-01-20
 
 - Initial release

data/README.md

@@ -1,43 +1,182 @@
-# Core
+# composable-core
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/core`. To experiment with that code, run `bin/console` for an interactive prompt.
+Reusable concerns for attributes, command execution, callbacks, composed records,
+and class configuration. Requires Ruby 3.2+, ActiveModel and ActiveSupport 7.2+.
+Install with `gem "composable-core"` and require `composable/core`.
 
-TODO: Delete this and the text above, and describe your gem
+## Attributes
 
-## Installation
+```ruby
+require "composable/core"
+
+class MessageInput
+  include Composable::Core::AttributeDSL
+
+  attribute :title, type: :string
+  attribute :count, type: :integer, default: 1
+  attribute :labels, default: []
+  attribute :requested_at, default: -> { Time.current }
+end
+
+input = {"title" => "Example", "count" => "2", class: "notice"}.freeze
+message = MessageInput.new(input)
+message.count # => 2
+message.params[:title] # => "Example"
+message.rest # => { class: "notice" }
+```
 
-Add this line to your application's Gemfile:
+`attribute` declares readers, writers and `name?` predicates using Rails
+`present?`. `attributes`/`attribute` without arguments return the declared Set;
+`params` returns declared values; `rest` contains unknown keys. Unknown keys are
+retained rather than assigned to methods.
+
+Inputs must be hashes or hash-like objects exposing `each_pair` and `to_h`.
+Permitted Rails parameters are accepted; unpermitted parameters raise through
+Rails. Initialization copies the input, supports string and symbol keys and gives
+the symbol key precedence. Explicit `nil` replaces a default. Mutable defaults
+are deep-copied per instance; callable defaults run lazily without arguments.
+Types are resolved through `ActiveModel::Type.lookup`, including registered
+application types and their keyword options.
+
+## Commands and callbacks
+
+Prefer the service/form/client bases when applicable. A custom command can
+prepend `Composable::Core::Command` and implement `call`. The wrapper adds
+ActiveModel validation and `rescue_from`, class-level `.call`/`.call!`, and
+instance-level status/result methods. A custom implementation must call `valid?`
+itself; the provided bases already do so. A missing implementation raises
+`Composable::Core::Command::NotImplementedError`.
+
+Handled exceptions return the command; handlers must record failure in `errors`.
+`.call!` raises `Composable::Core::Error` when errors exist, and propagates raised
+exceptions without invoking handlers. `Interrupt`, `SystemExit` and other
+exceptions outside `StandardError` are never swallowed.
+
+`Composable::Core::Callbacks` defines the `save` callback chain (`before_save`,
+`around_save`, `after_save`). It does not execute that chain on its own.
+
+## Record composition
+
+`ComposableDSL` pairs with `AttributeDSL`. Declare a record with
+`composable(:project) { sync :name; sync :display_name, to: :name }`.
+Assigning the record copies mapped values into the command, including when the
+record attribute was declared before `composable`. Existing attribute type/default
+configuration is retained. During initialization,
+record values are copied first so explicit command attributes take precedence.
+`save_composables` copies command values into records, calls `save!` on eligible
+records, and executes an optional block.
+
+Both a composable and an individual `sync` accept `if:` and `unless:` conditions.
+Composable eligibility is evaluated once per save, before any record mappings
+are applied. The same selected records are then synchronized and saved; a
+condition depending on a record's old value is not re-evaluated after that value
+changes. Individual `sync` conditions still run when their field is synchronized.
+Use a method symbol or a Proc: zero-argument blocks run on the command; blocks
+with an argument receive the record. Conditions use Ruby truthiness. Reverse
+mapping on record assignment always initializes the command's values. Conditional
+saving does not make a declared record optional: a missing record raises
+`ArgumentError`.
+
+Records exposing `transaction` are wrapped in nested transactions. Exceptions
+roll back work on a shared connection. Separate databases do not provide a
+distributed atomic commit; a commit failure can leave partial persistence.
+Adding command errors alone does not roll back writes. With ActiveRecord loaded,
+record validation errors are copied into command errors without changing the
+record's original errors; record error names matching declared command attributes
+are copied to those fields, while other names become base errors. Renamed sync
+mappings do not rename validation-error fields automatically.
+
+## Inheritable configuration
+
+Include `InheritableAttributes` and declare
+`inheritable_attributes :settings, default: {}` for a deep copy of the parent's
+current value in each subclass. `uninheritable_attributes :cache, default: []`
+resets the subclass to a fresh copy of the declared default. False and nil values
+are preserved. These are class settings, not request-local storage.
+
+
+## Build a custom command
+
+Use the concerns directly when the service/form bases do not fit your lifecycle.
+This standalone command validates before producing its result:
 
 ```ruby
-gem 'composable-core'
-```
+class FormatMessage
+  include Composable::Core::AttributeDSL
+  prepend Composable::Core::Command
+
+  attribute :text, type: :string
+  validates :text, presence: true
+
+  def call
+    return unless valid?
 
-And then execute:
+    text.strip.upcase
+  end
+end
 
-    $ bundle install
+command = FormatMessage.call(text: " hello ")
+command.result   # => "HELLO"
+command.success? # => true
 
-Or install it yourself as:
+invalid = FormatMessage.call(text: "")
+invalid.failure?              # => true
+invalid.errors.full_messages # => ["Text can't be blank"]
+```
 
-    $ gem install composable-core
+A module prepended to a base class wraps that base's implementation. A subclass
+that overrides `call` can bypass the wrapper. For services/forms implement `save`,
+and for HTTP clients implement `request`, to preserve the inherited lifecycle.
 
-## Usage
+## Override defaults in a subclass
 
-TODO: Write usage instructions here
+Attribute definitions are inherited independently; changing a subclass's default
+does not change its parent. Mutable defaults are also independent per instance.
 
-## Development
+```ruby
+class BatchInput
+  include Composable::Core::AttributeDSL
+  attribute :limit, type: :integer, default: 10
+  attribute :labels, default: []
+end
 
-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.
+class SmallBatchInput < BatchInput
+  attribute :limit, default: 2
+end
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+BatchInput.new.limit      # => 10
+SmallBatchInput.new.limit # => 2
 
-## Contributing
+first = BatchInput.new
+second = BatchInput.new
+first.labels << "priority"
+second.labels # => []
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jairovm/composables. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jairovm/composables/tree/main/CODE_OF_CONDUCT.md).
+BatchInput.new(limit: nil).limit # => nil, rather than the default
+```
 
-## License
+## Copy or reset class configuration
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```ruby
+class Processor
+  include Composable::Core::InheritableAttributes
+  inheritable_attributes :settings, default: { retries: 2, tags: [] }
+  uninheritable_attributes :cache, default: {}
+end
+
+Processor.settings[:tags] << "parent"
+Processor.cache[:last_run] = "example"
+
+class SpecializedProcessor < Processor
+end
+
+SpecializedProcessor.settings[:tags] # => ["parent"]
+SpecializedProcessor.cache           # => {}
+SpecializedProcessor.settings[:tags] << "child"
+Processor.settings[:tags]            # => ["parent"]
+```
 
-## Code of Conduct
+Subclass configuration is copied when the subclass is created. Later parent
+changes do not update existing subclasses automatically.
 
-Everyone interacting in the Core project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jairovm/composables/tree/main/CODE_OF_CONDUCT.md).
+See [testing](../docs/testing.md) for the isolated suite and coverage gates.

data/lib/composable/core/attribute_dsl.rb

@@ -12,16 +12,15 @@ module Composable
       end
 
       def initialize(options = {})
-        unless options.respond_to?(:has_key?)
-          raise ArgumentError, "When assigning attributes, you must pass a hash" \
-                               " as an argument, #{options.class} passed."
-        end
-
+        options = normalize_attributes(options)
         attributes.each do |attribute|
-          # Try a `string` key if `symbol` key does not exist
-          value = options.delete(attribute.to_sym)
-          value = options.delete(attribute.to_s) if value.nil?
-          send("#{attribute}=", value) unless value.nil?
+          if options.key?(attribute)
+            value = options.delete(attribute)
+            options.delete(attribute.to_s)
+            public_send("#{attribute}=", value)
+          elsif options.key?(attribute.to_s)
+            public_send("#{attribute}=", options.delete(attribute.to_s))
+          end
         end
 
         @rest = options
@@ -41,6 +40,17 @@ module Composable
         @rest
       end
 
+      private
+
+      def normalize_attributes(options)
+        unless options.respond_to?(:each_pair) && options.respond_to?(:to_h)
+          raise ArgumentError, "When assigning attributes, you must pass a hash"
+        end
+        options.to_h.dup
+      end
+
+      public
+
       module ClassMethods
         def attribute(*attrs)
           options = attrs.extract_options!

data/lib/composable/core/command.rb

@@ -33,7 +33,7 @@ module Composable
         raise Error, errors.full_messages.to_sentence if raise_exception && failure?
 
         self
-      rescue Exception => exception
+      rescue StandardError => exception
         raise if raise_exception || !rescue_with_handler(exception)
 
         self

data/lib/composable/core/composable_dsl.rb

@@ -15,9 +15,9 @@ module Composable
           composables[attribute.to_sym] ||= Composable.new(attribute)
           composables[attribute.to_sym].evaluate(**options, &block)
 
-          return if attributes.include?(attribute.to_sym)
+          return if method_defined?("#{attribute}_original_setter=")
 
-          attribute attribute
+          attribute(attribute) unless attributes.include?(attribute.to_sym)
 
           alias_method "#{attribute}_original_setter=", "#{attribute}="
 
@@ -34,9 +34,15 @@ module Composable
       # overridden by composable_record values, composable_record mapping methods
       # have to be synced first.
       def initialize(options = {})
+        options = normalize_attributes(options)
         composable_keys.each do |attribute|
-          value = options.delete(attribute) || options.delete(attribute.to_s)
-          send("#{attribute}=", value) if value
+          if options.key?(attribute)
+            value = options.delete(attribute)
+            options.delete(attribute.to_s)
+            public_send("#{attribute}=", value)
+          elsif options.key?(attribute.to_s)
+            public_send("#{attribute}=", options.delete(attribute.to_s))
+          end
         end
 
         super
@@ -48,8 +54,11 @@ module Composable
 
       def save_composables
         multi_db_transaction do
-          sync_composable_records
-          save_composable_records
+          eligible_composables = composables.select do |attribute, composable|
+            composable.valid?(self, composable_record_for(attribute))
+          end
+          sync_composable_records(eligible_composables)
+          save_composable_records(eligible_composables)
 
           yield if block_given?
         end
@@ -57,24 +66,22 @@ module Composable
 
       private
 
-      def sync_composable_records
-        composables.each do |attribute, composable|
+      def sync_composable_records(eligible_composables)
+        eligible_composables.each do |attribute, composable|
           record = composable_record_for(attribute)
-          composable.sync_attributes(self, record) if composable.valid?(self, record)
+          composable.sync_attributes(self, record)
         end
       end
 
-      def save_composable_records
-        composables.each do |attribute, composable|
+      def save_composable_records(eligible_composables)
+        eligible_composables.each_key do |attribute|
           record = composable_record_for(attribute)
-          record.save! if composable.valid?(self, record)
+          record.save!
         end
       end
 
-      # Ensures `save!` queries are wrapped within multiple db transactions.
-      # It might be the case that our service is working with several composable
-      # objects that are gonna be saved into diffent databases, if there is an
-      # error, all transactions are gonna be rollback regardless of the DB.
+      # Nest transactions for composable records. Transactions across distinct
+      # database connections are not a distributed atomic commit.
       def multi_db_transaction(attribute: composable_keys.first, &block)
         return yield if attribute.nil?
 
@@ -129,8 +136,6 @@ module Composable
 
         # DSL method
         def sync(*args, to: nil, **options)
-          args.extract_options!
-
           args.compact.uniq.each do |name|
             mapping[name.to_sym] ||= Sync.new(from: name)
             mapping[name.to_sym].merge(to: (to || name), **options)
@@ -197,7 +202,7 @@ module Composable
           end
 
           def call(form, record)
-            callable.call(form, record).eql?(statement == :if)
+            !!callable.call(form, record) == (statement == :if)
           end
 
           private
@@ -208,10 +213,14 @@ module Composable
               ->(form, _record) { form.send(condition) }
             when ::Proc
               lambda { |form, record|
-                form.instance_exec(*[record][0...condition.arity], &condition)
+                if condition.arity == 0
+                  form.instance_exec(&condition)
+                else
+                  form.instance_exec(record, &condition)
+                end
               }
             else
-              ->(*) { true }
+              raise ArgumentError, "condition must be a Symbol or Proc"
             end
           end
         end

data/lib/composable/core/gem_version.rb

@@ -10,7 +10,7 @@ module Composable
     module VERSION
       MAJOR = 0
       MINOR = 0
-      TINY  = 13
+      TINY  = 14
       PRE   = nil
 
       STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/composable/core/inheritable_attributes.rb

@@ -13,10 +13,8 @@ module Composable
           attributes.each do |attribute|
             @inheritable_attributes << {attribute: attribute, default: options[:default]}
 
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              class << self; attr_accessor :#{attribute} end
-            RUBY
-            send("#{attribute}=", options[:default]) unless options[:default].nil?
+            singleton_class.attr_accessor(attribute)
+            send("#{attribute}=", options[:default].deep_dup) unless options[:default].nil?
           end
           @inheritable_attributes
         end
@@ -29,10 +27,8 @@ module Composable
           attributes.each do |attribute|
             @uninheritable_attributes << {attribute: attribute, default: options[:default]}
 
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              class << self; attr_accessor :#{attribute} end
-            RUBY
-            send("#{attribute}=", options[:default]) unless options[:default].nil?
+            singleton_class.attr_accessor(attribute)
+            send("#{attribute}=", options[:default].deep_dup) unless options[:default].nil?
           end
 
           @uninheritable_attributes
@@ -45,7 +41,7 @@ module Composable
             inheritable_attribute = hash[:attribute]
             instance_name = "@#{inheritable_attribute}"
             instance_value = instance_variable_get(instance_name).deep_dup
-            subclass.instance_variable_set(instance_name, instance_value || hash[:default].deep_dup)
+            subclass.instance_variable_set(instance_name, instance_value)
           end
 
           Array(@uninheritable_attributes).each do |hash|

data/lib/composable/core/record_invalid.rb

@@ -6,11 +6,12 @@ module Composable
       extend ActiveSupport::Concern
       include ActiveSupport::Rescuable
 
-      class ErrorWithRecord < Exception
+      class ErrorWithRecord < StandardError
         attr_reader :record
 
         def initialize(record)
           @record = record
+          super(record.errors.full_messages.to_sentence)
         end
       end
 
@@ -18,9 +19,8 @@ module Composable
         prepend ComposableDSLExt
 
         rescue_from(ErrorWithRecord) do |exception|
-          exception.record.errors.delete(:base)&.each { |m| errors.add(:base, m) }
           exception.record.errors.each do |error|
-            if error.attribute.to_sym.in?(attributes)
+            if error.attribute == :base || error.attribute.to_sym.in?(attributes)
               errors.add(error.attribute, error.message)
             else
               errors.add(:base, exception.record.errors.full_message(error.attribute, error.message))
@@ -30,9 +30,11 @@ module Composable
       end
 
       module ComposableDSLExt
-        def save_composable_records
+        def save_composable_records(...)
           super
-        rescue ActiveRecord::RecordInvalid => exception
+        rescue StandardError => exception
+          raise unless defined?(ActiveRecord::RecordInvalid) && exception.is_a?(ActiveRecord::RecordInvalid)
+
           raise ErrorWithRecord.new(exception.record)
         end
       end

data/lib/composable/core.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "core/version"
+require "set"
 require "active_support"
 require "active_support/core_ext/object/deep_dup"
 require "active_model"
@@ -17,4 +18,4 @@ module Composable
   end
 end
 
-require "composable/core/record_invalid" if defined?(ActiveRecord)
+require "composable/core/record_invalid"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: composable-core
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Jairo Vazquez
 bindir: exe
 cert_chain: []
-date: 2025-08-09 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 description: Core composable object to work with ruby services and forms
 email:
 - jairovm20@gmail.com
@@ -70,7 +70,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="