service_core 0.2.0 → 1.0.0

data/lib/service_core/base.rb

@@ -1,51 +1,49 @@
-# frozen_string_literal: true
-
 require "active_support/concern"
 require "active_model"
-require_relative "response"
+require "set"
+require_relative "responder"
 
 module ServiceCore
   module Base
     extend ActiveSupport::Concern
 
+    RESERVED_FIELD_NAMES = Set[:call, :errors, :fields, :output, :perform, :response].freeze
+
     included do
-      # ServiceCore::Response is included first as it inherited output,
-      # which too has initialize method.
-      include ServiceCore::Response
+      # NOTE: Responder is included first so its initialize (inherited
+      # from Output) runs at the bottom of the super chain.
+      include ServiceCore::Responder
       include ActiveModel::Model
       include ActiveModel::Attributes
       include ActiveModel::Validations
 
-      # NOTE: fields attribute will hold the fields defined and their values
+      # NOTE: fields holds a ServiceCore::FieldSet snapshot of declared
+      # fields and their values at initialize time.
       attr_reader :fields
 
       class << self
-        # Wrapper method to define attribuutes and attr_accessor methods on object
-        def fields_defined
-          @fields_defined ||= {}
+        def field_names
+          @field_names ||= Set.new
         end
 
         def field(name, *args, **opts)
           # field :active, :boolean, default: true
           # field :active, type: :boolean, default: true
-          # Both explicit and implicit definitions are handled
-          type = args[0] || opts[:type]
-          default = args[1] || opts[:default]
+          # field :active, :boolean, false   # positional default
+          # field :payload                   # untyped (hash/array/object)
+          ensure_field_name_available!(name)
+          type = args.first || opts[:type]
+          # NOTE: arity check, not `||`, so a positional default of
+          # `false` or `nil` is not silently swallowed by opts[:default].
+          default = args.length >= 2 ? args[1] : opts[:default]
 
-          # NOTE: -
-          # ActiveModel::Attributes support only basic data types
-          # for ActiveRecord objects we use attr_accessor through ActiveModel::Model
-          # define attr_accessor to make instance variables also available for attributes
-
-          # define attribute if type is available to type cast
           if type
             attribute(name, type, default: default)
           else
             attr_accessor(name)
           end
 
-          # save fields defind as an hash, makes it easier to check
-          fields_defined[name] = default
+          field_names.add(name)
         end
 
         def call(attributes = {})
@@ -53,16 +51,24 @@ module ServiceCore
           obj.call
           obj
         end
+
+        private
+
+        def ensure_field_name_available!(name)
+          return unless ServiceCore::Base::RESERVED_FIELD_NAMES.include?(name)
+
+          raise(
+            ServiceCore::ReservedFieldName,
+            "`#{name}` is reserved by ServiceCore and cannot be used as a field name"
+          )
+        end
       end
 
       def initialize(attributes = {})
         super
         @local_errors = {}
-        @fields = {}
-        # NOTE: this helps identify values passed from values updated
-        self.class.fields_defined.each_key do |name|
-          @fields[name] = send(name)
-        end
+        snapshot = self.class.field_names.to_h { |name| [name, send(name)] }
+        @fields = ServiceCore::FieldSet.new(snapshot)
       end
 
       def call

data/lib/service_core/errors.rb

@@ -0,0 +1,11 @@
+module ServiceCore
+  class Error < StandardError; end
+
+  # Raised when a value object access (Response#[], Response#[]=) targets
+  # a key that is not one of the four allowed response keys.
+  class InvalidKey < Error; end
+
+  # Raised by `field` when a declared name would shadow a method that
+  # the gem itself defines on every service.
+  class ReservedFieldName < Error; end
+end

data/lib/service_core/field_set.rb

@@ -0,0 +1,21 @@
+module ServiceCore
+  # Immutable snapshot of a service's declared fields and their values
+  # at #initialize time. Each symbol key is exposed as a real method;
+  # call #to_h for the raw snapshot Hash.
+  class FieldSet
+    attr_reader :to_h
+
+    def initialize(values = {})
+      @to_h = values.to_h.freeze
+      @to_h.each_key do |name|
+        next unless name.is_a?(Symbol)
+
+        define_singleton_method(name) { @to_h[name] }
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@to_h.inspect}>"
+    end
+  end
+end

data/lib/service_core/logger.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "active_support/concern"
 
 module ServiceCore

data/lib/service_core/output.rb

@@ -1,42 +1,44 @@
-# frozen_string_literal: true
-
 require "active_support/concern"
-# require "active_model/errors"
+require_relative "response"
 
 module ServiceCore
   module Output
     extend ActiveSupport::Concern
 
-    ALLOWED_KEYS = %i[status data message errors].freeze
+    ALLOWED_KEYS = ServiceCore::Response::ALLOWED_KEYS
 
-    # NOTE: output attribute will hold output of the service
+    # NOTE: output holds the ServiceCore::Response for the service.
+    # response is the preferred name; output is retained as an alias.
     attr_reader :output
+    alias response output
 
     def initialize(_attributes = {})
+      # NOTE: super() with empty parens so positional args aren't forwarded
+      # up to other modules in the ancestor chain (ActiveModel::Model et al).
+      super()
       @output_dirty = false
       @status_dirty = false
-      @output = { status: "initialized" }
+      @output = ServiceCore::Response.new
     end
 
     private
 
+    # NOTE: nil values are skipped; legitimate falsy values
+    # (false, 0, "") are recorded faithfully.
     def set_output(key, value)
-      return unless key && value
-      raise ArgumentError, "Invalid key. Allowed keys are: #{ALLOWED_KEYS.join(", ")}" unless ALLOWED_KEYS.include?(key)
+      return if key.nil? || value.nil?
 
-      @output_dirty ||= true
-      @status_dirty = true if key == :status && !@status_dirty
       @output[key] = value
+      @output_dirty = true
+      @status_dirty = true if key == :status
     end
 
     def auto_assign_status
       if !@output_dirty
         set_output(:status, "success")
-      elsif @output_dirty && !@status_dirty
+      elsif !@status_dirty
         status_value = output[:errors].blank? ? "success" : "error"
         set_output(:status, status_value)
-      elsif @output_dirty && @status_dirty
-        # ignore
       end
     end
   end

data/lib/service_core/responder.rb

@@ -0,0 +1,38 @@
+require "active_support/concern"
+require "active_model/errors"
+require_relative "output"
+
+module ServiceCore
+  # Mixin that provides the response-building helpers used inside +perform+.
+  module Responder
+    extend ActiveSupport::Concern
+
+    include ServiceCore::Output
+
+    protected
+
+    def success_response(message: nil, data: nil)
+      formatted_response(status: "success", message: message, data: data)
+    end
+
+    def error_response(message:, errors: nil)
+      formatted_response(status: "error", message: message, errors: errors)
+    end
+
+    # NOTE: nil-valued keys are skipped; legitimate falsy values
+    # (false, 0, "") are recorded faithfully.
+    def formatted_response(status:, message: nil, data: nil, errors: nil)
+      set_output(:status, status)
+      set_output(:message, message)
+      set_output(:data, data)
+      set_output(:errors, error_messages(errors))
+      output
+    end
+
+    def error_messages(errors)
+      return nil if errors.nil?
+
+      errors.is_a?(ActiveModel::Errors) ? errors.messages : errors
+    end
+  end
+end

data/lib/service_core/response.rb

@@ -1,36 +1,109 @@
-# frozen_string_literal: true
-
-require "active_support/concern"
-require_relative "output"
-# require "active_model/errors"
+require "active_support/json"
 
 module ServiceCore
-  module Response
-    extend ActiveSupport::Concern
+  # Value object carrying the four-key service response.
+  class Response
+    ALLOWED_KEYS = %i[status data message errors].freeze
+    FETCH_DEFAULT_OMITTED = Object.new.freeze
+    private_constant :FETCH_DEFAULT_OMITTED
+
+    attr_accessor(*ALLOWED_KEYS)
+
+    def initialize(status: "initialized", data: nil, message: nil, errors: nil)
+      @status = status
+      @data = data
+      @message = message
+      @errors = errors
+    end
+
+    # NOTE: writes police the four-key contract; reads (fetch, dig)
+    # follow Hash semantics so callers can treat Response like a Hash.
+    def [](key)
+      ensure_allowed_key!(key)
+      public_send(key)
+    end
+
+    def []=(key, value)
+      ensure_allowed_key!(key)
+      public_send(:"#{key}=", value)
+    end
+
+    def fetch(key, default = FETCH_DEFAULT_OMITTED, &block)
+      return public_send(key) if key?(key)
+      return block.call(key) if block
+      return default unless default.equal?(FETCH_DEFAULT_OMITTED)
+
+      raise(KeyError, "key not found: #{key.inspect}")
+    end
+
+    def key?(key)
+      ALLOWED_KEYS.include?(key) && !public_send(key).nil?
+    end
+    alias has_key? key?
+    alias include? key?
+
+    def keys
+      ALLOWED_KEYS.select { |key| key?(key) }
+    end
 
-    include ServiceCore::Output
+    def values
+      keys.map { |key| public_send(key) }
+    end
+
+    def each_pair
+      return to_enum(:each_pair) unless block_given?
+
+      keys.each { |key| yield(key, public_send(key)) }
+    end
+    alias each each_pair
 
-    protected
+    def to_h
+      ALLOWED_KEYS.each_with_object({}) do |key, hash|
+        value = public_send(key)
+        hash[key] = value unless value.nil?
+      end
+    end
+    alias to_hash to_h
 
-    def success_response(message: nil, data: nil)
-      formatted_response(status: "success", message: message, data: data)
+    def to_s
+      to_h.to_s
     end
 
-    def error_response(message:, errors: nil)
-      formatted_response(status: "error", message: message, errors: errors)
+    def inspect
+      "#<#{self.class.name} #{to_h.inspect}>"
     end
 
-    # set output response
-    def formatted_response(status:, message: nil, data: nil, errors: nil)
-      set_output(:status, status)
-      set_output(:message, message) if message.present?
-      set_output(:data, data) if data.present?
-      set_output(:errors, error_messages(errors)) if errors.present?
-      output
+    def ==(other)
+      case other
+      when Response then to_h == other.to_h
+      when Hash then to_h == other
+      else super
+      end
     end
 
-    def error_messages(errors)
-      errors.is_a?(ActiveModel::Errors) ? errors.messages : errors
+    def dig(key, *rest)
+      return nil unless ALLOWED_KEYS.include?(key)
+
+      value = public_send(key)
+      return value if rest.empty? || value.nil?
+
+      value.respond_to?(:dig) ? value.dig(*rest) : nil
+    end
+
+    def as_json(options = nil)
+      to_h.as_json(options)
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    def ensure_allowed_key!(key)
+      return if ALLOWED_KEYS.include?(key)
+
+      raise(ServiceCore::InvalidKey, "Invalid key. Allowed keys are: #{ALLOWED_KEYS.join(", ")}")
     end
   end
 end

data/lib/service_core/step_validation.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "active_support/concern"
 
 module ServiceCore
@@ -7,39 +5,37 @@ module ServiceCore
     extend ActiveSupport::Concern
 
     included do
-      # NOTE: #
-      # added this to support partial validation
-      # valid? method empties all errors, so needed a way to hold errors from within method invocation
+      # NOTE: ActiveModel::Validations resets `errors` on every `valid?`,
+      # so we re-apply any errors recorded via #add_error through a
+      # registered validator. This lets a service accumulate errors
+      # mid-perform without them being wiped.
       validate :local_errors_validation
+    end
 
-      def local_errors_validation
-        _local_errors_validation(@local_errors)
-      end
+    def add_error(attribute, message, options = {})
+      value = options.empty? ? message : [message, options]
+      @local_errors[attribute] ||= []
+      @local_errors[attribute] << value
+    end
 
-      def _local_errors_validation(errors_hsh)
-        errors_hsh.each do |attribute, messages|
-          next unless messages
+    def add_error_and_validate(attribute, message, options = {})
+      add_error(attribute, message, options)
+      valid?
+    end
 
-          messages.each do |message|
-            errors.add(attribute, *message.is_a?(Array) ? message : [message])
-          end
-        end
-        {}
-      end
+    private
 
-      def add_error(attribute, message, options = {})
-        value = options.present? ? [message, options] : message
-        @local_errors[attribute] = if @local_errors[attribute].present?
-                                     Array(@local_errors[attribute]) << value
-                                   else
-                                     [value]
-                                   end
+    def local_errors_validation
+      @local_errors.each do |attribute, messages|
+        Array(messages).each { |message| apply_local_error(attribute, message) }
       end
+    end
 
-      # method to add partial errors and validate
-      def add_error_and_validate(attribute, message, _options = {})
-        add_error(attribute, message, {})
-        valid?
+    def apply_local_error(attribute, message)
+      if message.is_a?(Array)
+        errors.add(attribute, *message)
+      else
+        errors.add(attribute, message)
       end
     end
   end

data/lib/service_core/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ServiceCore
-  VERSION = "0.2.0"
+  VERSION = "1.0.0".freeze
 end

data/lib/service_core.rb

@@ -1,6 +1,7 @@
-# frozen_string_literal: true
-
 require_relative "service_core/version"
+require_relative "service_core/errors"
+require_relative "service_core/response"
+require_relative "service_core/field_set"
 require_relative "service_core/base"
 require_relative "service_core/step_validation"
 require_relative "service_core/logger"
@@ -17,8 +18,6 @@ module ServiceCore
     include ServiceCore::Logger
   end
 
-  class Error < StandardError; end
-
   class << self
     attr_writer :logger
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_core
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - mayank sehgal
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -19,7 +18,7 @@ dependencies:
         version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +28,7 @@ dependencies:
         version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +38,7 @@ dependencies:
         version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,36 +48,43 @@ dependencies:
         version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
-description: A service pattern implementation for Rails applications.
+        version: '9.0'
+description: ServiceCore provides a four-key response contract (status, data, message,
+  errors) for service objects, with field declarations, validations, step validation,
+  structured logging, and a Hash-compatible Response value object.
 email:
 - sehgalmayank001@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".byebug_history"
 - ".rspec"
 - ".rubocop.yml"
+- ".tool-versions"
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/service_core.rb
 - lib/service_core/base.rb
+- lib/service_core/errors.rb
+- lib/service_core/field_set.rb
 - lib/service_core/logger.rb
 - lib/service_core/output.rb
+- lib/service_core/responder.rb
 - lib/service_core/response.rb
 - lib/service_core/step_validation.rb
 - lib/service_core/version.rb
-- sig/service_core.rbs
 homepage: https://github.com/sehgalmayank001/service-core
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -86,15 +92,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: A Rails service pattern implementation
+summary: A standardised service object pattern for Ruby and Rails
 test_files: []

data/.byebug_history

@@ -1,71 +0,0 @@
-c
-@logger
-c
-defined?(Rails) && Rails.logger ? Rails.logger : ActiveSupport::Logger.new($stdout)
-c
-defined?(Rails) && Rails.logger ? Rails.logger : ActiveSupport::Logger.new($stdout)
-defined?(Rails)
-c
-defined?(Rails)
-c
-ServiceCore.logger
-c
-@logger
-c
-@logger
-c
-self.active
-self.status
-c
-self.active
-name
-c
-name
-n
-self.class.fields_defined
-@fields
-c
-n
-default
-self
-type
-n
-default
-n
-args
-opts
-c
-args
-opts
-c
-service
-c
-service
-c
-service
-c
-self.name
-n
-attributes
-c
-service
-c
-service.fields
-service
-c
-service.name
-c
-send(name)
-@fields
-name
-c
-@fields
-n
-c
-service
-c
-service.name
-service
-c
-service.fields
-service

data/sig/service_core.rbs

@@ -1,4 +0,0 @@
-module ServiceCore
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end