composable-service 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6931ed3eb03cf44174c6e7eca090b081d768a96d008624d433ecc91d13ca2ff6
-  data.tar.gz: 2880a4ff4041a563c3c2f8549fe04eaa9fedc3033999d7952cc3c97b73bfc5ce
+  metadata.gz: b3c690febbfbbd5921084d97b28acd8b0c1a501f6f9a317d72f58309ccd9019f
+  data.tar.gz: 0242eaf874208b7f5c57818fc934c09a98fef18ec869a9f47f66a476487c42d9
 SHA512:
-  metadata.gz: bb4f38d5f958be887ce62a3a34c83707530aff6711de1b5f143fd76faa32ae5156566553fc93116e1544546805343c7b8e5934917183892c2f5c515e043b9dbd
-  data.tar.gz: 51c0be06a6f9f3717387dc119dd5cbc95cd32056b5c380182356dec5206ddce79a9459c76ccb46ede013ad2c082e726ae28d35d1936bed0d3b8f7000c51ca89a
+  metadata.gz: b7a4752d7a9228d8177abab42e2d03157535e9e504f46683eb3007aa0764fe3267b0bb67780e3d919ef2289d33296909dbde4704ae4020bfbb21fae7e72caad3
+  data.tar.gz: bf76c2769e5e29f5ec310dc0eba0430bf82ea69a6fd98791f080115bd71247db522e002400f1c284338b1037b50e33791531d75f4e86727dd43109bfa6847939

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+- Preserve results across nested subclasses and mark aborted callbacks as failures.
+- Document service lifecycle and transaction boundaries.
+- Add behavioral tests with complete line/branch coverage.
+
 ## [0.0.1] - 2022-01-24
 
 - Initial release

data/README.md

@@ -1,43 +1,144 @@
-# Composable::Service
+# composable-service
 
-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/composable/service`. To experiment with that code, run `bin/console` for an interactive prompt.
+Validated service objects with attributes, record composition, callbacks and an
+explicit result. Requires Ruby 3.2+ and ActiveModel/ActiveSupport 7.2+.
+Install `gem "composable-service"`; require `composable/service`.
 
-TODO: Delete this and the text above, and describe your gem
+## Implement an operation
 
-## Installation
+```ruby
+require "composable/service"
 
-Add this line to your application's Gemfile:
+class BuildGreeting < Composable::Service::Command
+  attribute :name, type: :string
+  validates :name, presence: true
 
-```ruby
-gem 'composable-service'
+  private
+
+  def save
+    "Hello, #{name}"
+  end
+end
+
+operation = BuildGreeting.call(name: "Example")
+operation.success? # => true
+operation.result   # => "Hello, Example"
+BuildGreeting.call(name: "").failure? # => true
 ```
 
-And then execute:
+Implement `save`, whose return value becomes `result`. Call `.call` on the class
+or initialize an instance and call it. Validation runs before the save callback
+chain and persistence. `.call!` raises `Composable::Core::Error` on failure.
+Before execution, `success?` and `failure?` both return false.
 
-    $ bundle install
+Use `before_save`, `around_save`, and `after_save` for operation lifecycle hooks.
+An aborted callback or a save returning `false` records failure; nil is a valid
+result. `rescue_from` handles expected `StandardError` subclasses for `.call`;
+unhandled errors and all exceptions from `.call!` propagate. Handlers should add
+an appropriate error without including secrets.
 
-Or install it yourself as:
+## Compose records
 
-    $ gem install composable-service
+`attribute`, `composable`, `sync`, typing, defaults and conditions come from
+[core](../composable-core/README.md). Declare explicit mappings for allowed
+writes. Record assignment initializes mapped attributes; explicit operation
+attributes override them. Eligible records are saved before `save`, inside nested
+record transactions. ActiveRecord validation errors become operation errors.
 
-## Usage
+Exceptions roll back changes on a shared database connection. Adding errors alone
+does not undo writes. External API calls and work across multiple databases are
+not transactional; use application-level compensation or an outbox when needed.
+Service objects do not authorize resources or manage job retries automatically.
 
-TODO: Write usage instructions here
+Use a fresh operation for each execution. Read failures before consuming the
+result. See [testing](../docs/testing.md) for running this gem's suite.
 
-## Development
+## Inspect failure and use the raising interface
 
-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.
+```ruby
+operation = BuildGreeting.new(name: "")
+operation.success? # => false: it has not run yet
+operation.failure? # => false
+
+operation.call
+operation.failure?              # => true
+operation.errors.full_messages # => ["Name can't be blank"]
+operation.result                # => nil
+
+begin
+  BuildGreeting.call!(name: "")
+rescue Composable::Core::Error => error
+  # Present a suitable application error; do not assume a result is available.
+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).
+## Add callbacks and handle expected exceptions
 
-## Contributing
+This example takes an application-provided delivery adapter. The adapter must
+implement `deliver(message)` and return a receipt; it may raise `DeliveryUnavailable`.
 
-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).
+```ruby
+class DeliveryUnavailable < StandardError; end
+
+class SendNotice < Composable::Service::Command
+  attribute :message, type: :string
+  attribute :delivery
+  validates :message, :delivery, presence: true
+
+  before_save do
+    self.message = message.strip
+  end
+
+  rescue_from DeliveryUnavailable do
+    errors.add(:base, "Delivery is temporarily unavailable")
+  end
+
+  private
+
+  def save
+    delivery.deliver(message)
+  end
+end
+
+# adapter is supplied by the application.
+operation = SendNotice.call(message: " Example notice ", delivery: adapter)
+if operation.success?
+  receipt = operation.result
+else
+  messages = operation.errors.full_messages
+end
+```
 
-## License
+Only the expected exception is translated. Other exceptions propagate, and
+`SendNotice.call!` propagates `DeliveryUnavailable` without calling the handler.
+The callback runs after validation; use setters when normalization must affect
+validation itself.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Update a composed record
 
-## Code of Conduct
+Assume the application defines a `Project` model with a `name` column. The caller
+must obtain an authorized project before invoking the service.
+
+```ruby
+class RenameProject < Composable::Service::Command
+  attribute :name, type: :string
+  validates :name, presence: true
+
+  composable :project do
+    sync :name
+  end
+
+  private
+
+  def save
+    project
+  end
+end
+
+operation = RenameProject.call(project: authorized_project, name: "New name")
+operation.result # => the saved project on success
+```
 
-Everyone interacting in the Composable::Service 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).
+Implement `save` in subclasses, including subclasses of your application service
+base. Overriding `call` can bypass the inherited command wrapper. Use a fresh
+instance for each operation instead of calling the same instance repeatedly.

data/lib/composable/service/command.rb

@@ -6,20 +6,16 @@ module Composable
       include Core::AttributeDSL
       include Core::ComposableDSL
       include Core::Callbacks
-
-      class << self
-        def inherited(subclass)
-          super
-          subclass.prepend(Core::Command)
-        end
-      end
+      prepend Core::Command
 
       def call
         return unless valid?
 
-        run_callbacks :save do
+        completed = run_callbacks :save do
           @result = save_composables { save }
         end
+        errors.add(:base, :invalid) if completed == false
+        @result
       end
 
       private

data/lib/composable/service/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(".")

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: composable-service
 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: composable-core
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
 description: Service composable object to work with ruby services
 email:
 - jairovm20@gmail.com
@@ -51,7 +51,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:
   - - ">="