service_core 0.2.0 → 1.0.0

data/README.md

@@ -1,40 +1,50 @@
 # ServiceCore
 
-ServiceCore provides a standardized way to define and use service objects in Ruby and Rails applications. It includes support for specifying fields, validations, responses, and error logging. This approach is inspired by the DRY (Don't Repeat Yourself) principle and Rails' convention over configuration philosophy.
+ServiceCore is a small Ruby gem that gives service objects a shared shape. Every service exposes a single `call` method and returns the same four-key response, regardless of who wrote it. The idea behind the shape is unpacked in [The Shape of a Service Response](https://agnosticlogic.substack.com/p/the-shape-of-a-service-response).
+
+- Four-key response contract: **status**, **data**, **message**, **errors**.
+- Field declarations with types, defaults, and ActiveModel validations.
+- Step-by-step validation that survives `valid?` calls.
+- Hash-compatible value objects (`Response`, `FieldSet`) instead of raw hashes.
+- Works on Ruby >= 3.1 and Rails (ActiveModel/ActiveSupport) 6.1 through 8.x.
 
 ## Installation
-Install the gem and add to the application's Gemfile by executing:
 
 ```sh
 bundle add service_core
 ```
-Or in your Gemfile:
+
+Or add it to your Gemfile:
 
 ```ruby
 gem "service_core"
 ```
 
-If the bundler is not being used to manage dependencies, install the gem by executing:
+If you are not using Bundler:
 
 ```sh
 gem install service_core
 ```
 
-### Service Response Structure
-The idea is to define a convention that the response from a service can have only four keys:
-- status
-- data
-- message
-- errors
+## The four-key response
+
+Every service responds with at most four keys:
+
+| Key       | Purpose                                                                |
+| --------- | ---------------------------------------------------------------------- |
+| `status`  | Machine-readable signal (`"success"`, `"error"`, or any custom state). |
+| `data`    | The payload the caller asked for.                                      |
+| `message` | High-level human context, distinct from per-field error detail.        |
+| `errors`  | Structured error detail (Hash, Array, ActiveModel::Errors, ...).       |
 
-The data type of any of the above keys is not enforced, giving the developer flexibility to return based on the use case, but should follow this response structure.
-## Usage
+The shape is enforced; the value types are not. Writing a key other than these four raises `ServiceCore::InvalidKey`.
 
-### Defining a Service
+## Defining a service
+
+Include `ServiceCore` in your class and implement `perform`:
 
-To define a new service, include the `ServiceCore` module in your service class and define your fields and the `perform` method.
 ```ruby
-class MyService
+class GreetService
   include ServiceCore
 
   field :first_name, :string
@@ -42,212 +52,137 @@ class MyService
   field :active, :boolean, default: true
 
   def perform
-    success_response(message: "Hello, World", data: name)
+    success_response(message: "Hello, World", data: full_name)
   end
 
-  def name
+  private
+
+  def full_name
     "#{first_name} #{last_name}"
   end
 end
 ```
 
-### Using a Service
-Instantiate and call the service to execute it. The call method will validate the input, perform the operation, and return the output.
-```ruby
-service = MyService.new(first_name: "John", last_name: "Doe")
-result = service.call
-puts result
-# Output:
-# {
-#   status: "success",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
-
-puts service.output
-# Output:
-# {
-#   status: "success",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
-```
+## Calling a service
+
+You can call a service either via `new(...).call` or via the `.call` shortcut on the class:
 
-The `call` method can be invoked on the service class and it too will return the object of the service.
 ```ruby
-obj = MyService.call(first_name: "John", last_name: "Doe")
-puts obj.output
-# Output:
-# {
-#   status: "success",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
+response = GreetService.new(first_name: "John", last_name: "Doe").call
+puts response
+# => {status: "success", message: "Hello, World", data: "John Doe"}
+
+service = GreetService.call(first_name: "John", last_name: "Doe")
+service.response
+# => {status: "success", message: "Hello, World", data: "John Doe"}
 ```
 
-### `field` method
-The `field` method can define primitive types and objects, like hash/array or any object. For objects, there is no need to declare the datatype.
-```ruby
-class MyService
-  include ServiceCore
+The instance method returns the response value object. The class-level `.call` returns the service instance, so you can also reach for `service.response` (or `service.output`, which is kept as an alias) after the fact.
 
-  field :first_name, :string
-  field :last_name, :string
-  field :payload # can be object/hash/array
+## `Response`: the value object
 
-  def perform
-    success_response(message: "Hello, World", data: name)
-  end
+`service.response` (and the value returned from `#call`) is a `ServiceCore::Response`. It exposes both named accessors and Hash-style access, and serialises to JSON like the underlying hash:
 
-  def name
-    "#{first_name} #{last_name}"
-  end
-end
+```ruby
+response = GreetService.call(first_name: "John", last_name: "Doe").response
+
+response.status   # => "success"
+response.data     # => "John Doe"
+response[:status] # => "success"
+response == { status: "success", message: "Hello, World", data: "John Doe" } # => true
+response.to_json  # => '{"status":"success","message":"Hello, World","data":"John Doe"}'
 ```
 
-### `set_output` method
+Writing or reading a key other than the four allowed raises `ServiceCore::InvalidKey`.
+
+## Declaring fields
+
+`field` supports both typed and untyped declarations.
 
-The `set_output` method provides a way to set output of a specific key. It is the method used by the response_setters to set specific output value
 ```ruby
 class MyService
   include ServiceCore
 
-  field :first_name, :string
-  field :last_name, :string
-  field :payload # can be object/hash/array
+  field :first_name, :string                  # typed (ActiveModel::Attributes)
+  field :active, :boolean, default: true      # typed with keyword default
+  field :enabled, :boolean, false             # typed with positional default
+  field :payload                              # untyped, can be any object/hash/array
+end
+```
 
-  def perform
-    set_output :message, "Hello, World"
-    set_output :data, name
-  end
+Typed fields are backed by `ActiveModel::Attributes` and inherit its casting and default support.
 
-  def name
-    "#{first_name} #{last_name}"
-  end
-end
+The following names are reserved and cannot be used as field names because they would shadow methods the gem itself defines: `:call`, `:errors`, `:fields`, `:output`, `:perform`, `:response`. Declaring `field :errors` (for example) raises `ServiceCore::ReservedFieldName`.
 
-obj = MyService.call(first_name: "John", last_name: "Doe")
-puts obj.output
-# Output:
-# {
-#   status: "success",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
-```
-*NOTE:* If `:status` is not explicitly set in the perform method, the `success` status is returned if `errors` are blank else the `error` status is returned.
+### Field snapshot via `FieldSet`
 
-### Response Setters
+After construction, `service.fields` exposes an immutable snapshot of the declared fields and their values as a `ServiceCore::FieldSet`. Each declared symbol field is available as a real method; call `to_h` if you need a plain Hash.
 
-#### `success_response`
-Use the `success_response` method to return the `success` status, `data` and `message`
 ```ruby
+service = GreetService.new(first_name: "John", last_name: "Doe")
 
-class MyService
-  include ServiceCore
+service.fields.first_name   # => "John"
+service.fields.to_h         # => { first_name: "John", last_name: "Doe", active: true }
+```
 
-  field :first_name, :string
-  field :last_name, :string
-  field :active, :boolean, default: true
+The snapshot is taken at `#initialize`, so it reflects the values at construction time. Live values are still available through each declared accessor (e.g. `service.first_name`).
 
-  def perform
-    success_response(message: "Hello, World", data: name)
-  end
+## Building responses
 
-  def name
-    "#{first_name} #{last_name}"
-  end
-end
-
-service = MyService.new(first_name: "John", last_name: "Doe")
-result = service.call
-puts result
-# Output:
-# {
-#   status: "success",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
-```
+Three helpers cover almost every case.
 
-`success_response` accepts following arguments:
-- message
-- data
+### `success_response`
 
-#### `error_response`
-Use the `error_response` method to return the `error` status, `errors` and `message`
 ```ruby
+def perform
+  success_response(message: "Hello, World", data: full_name)
+end
+# => {status: "success", message: "Hello, World", data: "John Doe"}
+```
 
-class MyService
-  include ServiceCore
+Accepts `message` and `data`. Status is set to `"success"`.
 
-  field :first_name, :string
-  field :last_name, :string
-  field :active, :boolean, default: true
+### `error_response`
 
-  def perform
-    error_response(message: "validation failure", errors: "last_name can't be blank")
-  end
-
-  def name
-    "#{first_name} #{last_name}"
-  end
+```ruby
+def perform
+  error_response(message: "validation failure", errors: "last_name can't be blank")
 end
-
-service = MyService.new(first_name: "John")
-result = service.call
-puts result
-# Output:
-# {
-#   status: "error",
-#   message: "validation failure",
-#.  errors: "last_name can't be blank"
-# }
+# => {status: "error", message: "validation failure", errors: "last_name can't be blank"}
 ```
 
-`error_response` accepts following arguments:
-- message
-- errors
+Accepts `message` and `errors`. Status is set to `"error"`. `errors` can be a String, Hash, Array, or `ActiveModel::Errors` (which is normalised through `messages`).
+
+### `formatted_response`
+
+For any status that isn't success or error.
 
-#### `formatted_response`
-Use the `formatted_response` method to return any status other than `success` or `error`.
 ```ruby
+def perform
+  formatted_response(status: "processed", message: "Already done", data: existing_record)
+end
+# => {status: "processed", message: "Already done", data: ...}
+```
 
-class MyService
-  include ServiceCore
+Accepts `status`, `message`, `data`, and `errors`. Use this for `"pending"`, `"queued"`, `"processed"`, or any domain-specific status.
 
-  field :first_name, :string
-  field :last_name, :string
-  field :active, :boolean, default: true
+### `set_output`
 
-  def perform
-    formatted_response(status: 'processed', message: "Hello, World", data: name)
-  end
+For finer-grained control, write a single key at a time:
 
-  def name
-    "#{first_name} #{last_name}"
-  end
+```ruby
+def perform
+  set_output(:message, "Hello, World")
+  set_output(:data, full_name)
 end
-
-service = MyService.new(first_name: "John", last_name: "Doe")
-result = service.call
-puts result
-# Output:
-# {
-#   status: "processed",
-#   message: "Hello, World",
-#.  data: "John Doe"
-# }
 ```
 
-`formatted_response` accepts following arguments:
-- status
-- message
-- data
-- errors
+If `status` is not set explicitly, it is auto-assigned to `"success"` when `errors` is blank, and `"error"` otherwise. `nil` is the only value treated as "not set"; `false`, `0`, and `""` are stored as-is.
+
+## Validations
+
+Standard ActiveModel validations run before `perform`. If they fail, the response is filled in for you.
 
-### Validations
-Define validation on the service and those will be invoked before service logic is invoked.
 ```ruby
 class MyService
   include ServiceCore
@@ -260,52 +195,43 @@ class MyService
   end
 end
 
-service = MyService.new(name: "")
-result = service.call
-puts result
-# Output:
-#{
-#   status: "error",
-#   message: "validation failure",
-#   errors: { name: ["can't be blank"] }
-# }
+MyService.new(name: "").call
+# => {status: "error", message: "validation failure", errors: {name: ["can't be blank"]}}
 ```
 
-### Step Validation
-Perform validation at each step of service logic. This is helpful when the result of the previous step decides the next logic.
+### Step validation
+
+When the result of one step decides the next, `add_error_and_validate` lets you accumulate errors mid-`perform` without `valid?` wiping them.
+
 ```ruby
 class MyService
   include ServiceCore
-  
+
   field :first_name, :string
   field :last_name, :string
-  field :user
 
   validates :first_name, presence: true
-  validates :user, presence: true
 
   def perform
     if last_name.blank?
       add_error_and_validate(:last_name, "can't be nil")
       return error_response(message: "validation failure", errors: errors)
     end
-    
-   success_response(data: { user: { id: 1 } })
+
+    success_response(data: { user: { id: 1 } })
   end
 end
 
-obj = MyService.call(first_name: 'abc')
-obj.output
-# output:
-# {
-#   status: "error",
-#   message: "validation failure",
-#   errors: { last_name: ["can't be nil"] }
-# }
+MyService.call(first_name: "abc").response
+# => {status: "error", message: "validation failure", errors: {last_name: ["can't be nil"]}}
 ```
 
-### Logging Errors
-Log errors using the `log_error` method.
+`add_error_and_validate(attribute, message, options = {})` forwards `options` to `ActiveModel::Errors#add`, so options like `strict: true` are honoured.
+
+## Logging errors
+
+`log_error(exception)` writes through the configured `ServiceCore.logger` and tags the message with the service class name.
+
 ```ruby
 class MyService
   include ServiceCore
@@ -313,43 +239,83 @@ class MyService
   field :name, :string
 
   def perform
-    begin
-      raise StandardError, "Something went wrong"
-    rescue StandardError => e
-      log_error(e)
-      error_response(message: "Failed", errors: { base: [e.message] })
-    end
+    raise StandardError, "Something went wrong"
+  rescue StandardError => e
+    log_error(e)
+    error_response(message: "Failed", errors: { base: [e.message] })
   end
 end
+```
 
-service = MyService.new(name: "World")
-result = service.call
-puts result
-# Output:
-# {
-#   status: "error",
-#   message: "Failed",
-#   errors: { base: ["Something went wrong"] }
-# }
+## Exceptions
 
+All gem-specific exceptions inherit from `ServiceCore::Error`, so a single rescue block can catch anything ServiceCore raises:
+
+```ruby
+begin
+  MyService.call(...)
+rescue ServiceCore::Error => e
+  # any gem-raised error
+end
 ```
 
-### Configuring the Logger
-Configure the logger for the ServiceCore module.
+The current concrete subclasses are:
+
+- `ServiceCore::InvalidKey` — raised by `response[:not_allowed]` or `response[:not_allowed] = value` when the key is not one of the four allowed response keys.
+- `ServiceCore::ReservedFieldName` — raised by `field :errors` (or any other reserved name) at class-definition time.
+
+Two raises stay on stdlib classes: `Response#fetch` raises `KeyError` to match `Hash#fetch`, and the default `perform` raises `StandardError` until the service overrides it.
+
+## Configuration
+
 ```ruby
 ServiceCore.configure do |config|
-  config.logger = Logger.new(STDOUT)
+  config.logger = Logger.new($stdout)
 end
 ```
 
+If you do not configure a logger, `ServiceCore.logger` defaults to `Rails.logger` when available, and otherwise to an `ActiveSupport::Logger` writing to `$stdout`.
+
+## Stability
+
+ServiceCore follows [Semantic Versioning](https://semver.org/). Starting with 1.0.0, the following are part of the public API and changes to them require a major version bump:
+
+- The four-key response contract (`status`, `data`, `message`, `errors`).
+- The Hash-compatible surface of `ServiceCore::Response` (`[]`, `[]=`, `==`, `to_h`, `to_s`, `inspect`, `keys`, `values`, `each`, `dig`, `fetch`, `key?` / `has_key?` / `include?`, `as_json`, `to_json`) and its named accessors (`status`, `data`, `message`, `errors`).
+- The `ServiceCore::FieldSet` API (`to_h` and named accessors per declared symbol field).
+- The service DSL: `include ServiceCore`, `field`, `validates`, `perform`, instance `#call` and class `.call`, `service.fields`, `service.response` / `service.output`.
+- The response builders: `success_response`, `error_response`, `formatted_response`, `set_output`.
+- The step-validation helpers: `add_error`, `add_error_and_validate`.
+- The reserved field names: `:call`, `:errors`, `:fields`, `:output`, `:perform`, `:response`.
+- The exception hierarchy under `ServiceCore::Error`.
+- `ServiceCore.logger` and `ServiceCore.configure`.
+
+The internals of `ServiceCore::Output`, the `Responder` mixin shape, and anything not listed above are implementation details and may change between any release.
+
+## Compatibility
+
+- Ruby: 3.1 minimum; tested against 3.3 and 3.4 (and 4.0 against Rails 8.x).
+- ActiveModel / ActiveSupport: `>= 6.1, < 9.0`; tested against Rails 7.2, 8.0, and 8.1 via [appraisal](https://github.com/thoughtbot/appraisal).
+
+## Development
+
+```sh
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+To run the spec suite against every supported Rails version:
+
+```sh
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sehgalmayank001/service-core. 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/sehgalmayank001/service-core/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at [github.com/sehgalmayank001/service-core](https://github.com/sehgalmayank001/service-core). This project follows the [Contributor Covenant code of conduct](https://github.com/sehgalmayank001/service-core/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the ServiceCore project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sehgalmayank001/service-core/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "activemodel", "~> 7.2.0"
+gem "activesupport", "~> 7.2.0"
+
+group :development, :test do
+  gem "appraisal", "~> 2.5"
+  gem "debug", ">= 1.9"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.86"
+  gem "rubocop-rake", "~> 0.7"
+  gem "rubocop-rspec", "~> 3.0"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "activemodel", "~> 8.0.0"
+gem "activesupport", "~> 8.0.0"
+
+group :development, :test do
+  gem "appraisal", "~> 2.5"
+  gem "debug", ">= 1.9"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.86"
+  gem "rubocop-rake", "~> 0.7"
+  gem "rubocop-rspec", "~> 3.0"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "activemodel", "~> 8.1.0"
+gem "activesupport", "~> 8.1.0"
+
+group :development, :test do
+  gem "appraisal", "~> 2.5"
+  gem "debug", ">= 1.9"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.86"
+  gem "rubocop-rake", "~> 0.7"
+  gem "rubocop-rspec", "~> 3.0"
+end
+
+gemspec path: "../"