composable-service 0.0.12 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc5b70b66baf4e7832ff94d98dc2c8d3b6549f8a125821d492ec4fa09d005678
-  data.tar.gz: 2cfab4a6fb7894d73ee6367e7a4d2bceb1e6194122d4a8a9b8fe88b311df616c
+  metadata.gz: b3c690febbfbbd5921084d97b28acd8b0c1a501f6f9a317d72f58309ccd9019f
+  data.tar.gz: 0242eaf874208b7f5c57818fc934c09a98fef18ec869a9f47f66a476487c42d9
 SHA512:
-  metadata.gz: 742240c553a3d2fbf5bd1fc79535babf18d511ff3fb9d6f149c301dd6ceeb6c8abf779c6e7f88e076c70e7a1b98a698c443b90e28b0316ed7affa296aeb42286
-  data.tar.gz: 6bc3ac05b832b0fee8a5a9d2cce9177d0c927b51fc04683af14bb1f3def93f6713f268aa630d637ebb318b4a36e45771143ced991772f5d4e58b62cf23048317
+  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
-          save_composables { save }
+        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  = 12
+      TINY  = 14
       PRE   = nil
 
       STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: composable-service
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.14
 platform: ruby
 authors:
 - Jairo Vazquez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-02 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: composable-core
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: 0.0.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: 0.0.14
 description: Service composable object to work with ruby services
 email:
 - jairovm20@gmail.com
@@ -45,7 +44,6 @@ metadata:
   homepage_uri: https://github.com/jairovm/composables
   source_code_uri: https://github.com/jairovm/composables/tree/main/composable-service
   changelog_uri: https://github.com/jairovm/composables/tree/main/composable-service/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -53,15 +51,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Service Composable Object
 test_files: []