iry 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c37af75076323e55b59756a3929843bbbca04cd0bc43bc49ae89ef68e9d1665
-  data.tar.gz: 2b4ca6aef3667fc9f6215d1d828d732dac0c8930044e88f8234cf690b5b7a514
+  metadata.gz: 592290e30f1db830217241ebde319fbf952ee459ac05c3bc1e87b4b47a73e143
+  data.tar.gz: '09cabb7faf8e78a91e7d2443bdfd5466d7e8f63bc90fcfeb2abdb72f93bd79bf'
 SHA512:
-  metadata.gz: 8a9d1bb387cfc7d5809235378f80f84d8961a53cba63c9dddc6f8538352412cb02ab59d87e8fea16d5ac6c87ce1a243541ea421f4a1f14ce568331c8d1c77d70
-  data.tar.gz: 0fe39194ef0b3f17719f9d66a6a7881eafd8cb02e3ef50cd42c154a18875ebc726e31155a570d3fc0687547bf01b158bf7267adb4c19ac3422b9fe5aa86e1394
+  metadata.gz: 915d87f39809daa1a0a76ea66c4718e20afe6dbef4ced1853df47e9457927a464a06204cd4c0abd71dad861d8df6f23c974b2a75796ff7136b17f94875fb36ae
+  data.tar.gz: f8b10f525eab24f478a3bb6ee2c1039258b65d532eb5475d584f68bec23cf6c2e305e47033b4621dfe49be563da584c488683905d12c9abf529c07ec194d46bc

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

data/lib/iry/constraint/check.rb

@@ -30,7 +30,7 @@ module Iry
       end
 
       # @param model [Handlers::Model]
-      # @return [void]
+      # @return [ActiveModel::Error]
       def apply(model)
         model.errors.add(key, message)
       end

data/lib/iry/constraint/exclusion.rb

@@ -30,7 +30,7 @@ module Iry
       end
 
       # @param model [Handlers::Model]
-      # @return [void]
+      # @return [ActiveModel::Error]
       def apply(model)
         model.errors.add(key, message)
       end

data/lib/iry/constraint/foreign_key.rb

@@ -35,7 +35,7 @@ module Iry
       end
 
       # @param model [Handlers::Model]
-      # @return [void]
+      # @return [ActiveModel::Error]
       def apply(model)
         model.errors.add(error_key, message)
       end

data/lib/iry/constraint/unique.rb

@@ -35,7 +35,7 @@ module Iry
       end
 
       # @param model [Handlers::Model]
-      # @return [void]
+      # @return [ActiveModel::Error]
       def apply(model)
         model.errors.add(error_key, message)
       end

data/lib/iry/constraint.rb

@@ -6,7 +6,7 @@ module Iry
     # Sets validation errors on the model
     # @abstract
     # @param model [Handlers::Model]
-    # @return [void]
+    # @return [ActiveModel::Error]
     def apply(model)
     end
 

data/lib/iry/handlers/null.rb

@@ -15,9 +15,9 @@ module Iry
       # Return always false, failing to handle any constraint
       # @param err [ActiveRecord::StatementInvalid]
       # @param model [Model] should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      # @return [Boolean]
+      # @return [nil, ActiveModel::Error]
       def handle(err, model)
-        return false
+        return nil
       end
     end
   end

data/lib/iry/handlers/pg.rb

@@ -36,7 +36,9 @@ module Iry
       # Appends constraint errors as model errors
       # @param err [ActiveRecord::StatementInvalid]
       # @param model [Model] should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      # @return [void]
+      # @return [nil, ActiveModel::Error] if handled constraint, returns the
+      #   error attached to the model. If constraint wasn't handled or handling
+      #   failed, `nil` is returned
       def handle(err, model)
         pgerr = err.cause
         constraint_name_msg = pgerr.result.error_field(::PG::Constants::PG_DIAG_MESSAGE_PRIMARY)
@@ -44,12 +46,10 @@ module Iry
         constraint_name = match[1]
         constraint = model.class.constraints[constraint_name]
         if constraint.nil?
-          return false
+          return nil
         end
 
-        constraint.apply(model)
-
-        return true
+        return constraint.apply(model)
       end
     end
   end

data/lib/iry/handlers.rb

@@ -12,7 +12,8 @@ module Iry
       # @abstract
       # @param err [ActiveRecord::StatementInvalid] possible constraint error to handle
       # @param model [Model]
-      # @return [Boolean] true if this database handler handled the constraint error
+      # @return [nil, ActiveModel::Error] `nil` if couldn't handle the error,
+      #   otherwise the {ActiveModel::Error} added to the model
       def handle(err, model)
       end
     end

data/lib/iry/patch.rb

@@ -6,7 +6,7 @@ module Iry
     # @return [Boolean] true if successful
     def create_or_update(...)
       result = false
-      Iry.handle_constraints!(self) { result = super }
+      TransformConstraints.nested_constraints!(self) { result = super }
       result
     end
   end

data/lib/iry/transform_constraints.rb

@@ -0,0 +1,139 @@
+module Iry
+  # Implementation of {Iry} methods, helps ensuring the main module focus on
+  # documentation
+  module TransformConstraints
+    extend self
+
+    # @param model [Handlers::Model]
+    # @yield
+    # @return [nil, Handlers::Model]
+    def handle_constraints(model, &block)
+      handle_constraints!(model, &block)
+    rescue StatementInvalid
+      return nil
+    end
+
+    # @param model [Handlers::Model]
+    # @yield
+    # @return [Handlers::Model]
+    def handle_constraints!(model, &block)
+      # Allows checking if Iry has been activated (handling).
+      # Number is used to support nested handle_constraints!
+      Thread.current[:iry] ||= 0
+      Thread.current[:iry] += 1
+
+      nested_constraints!(model, &block)
+    rescue StatementInvalid => err
+      # Imports errors from "nested" models back into the parent, to ensure
+      # `errors` is populated and the record is considered invalid
+
+      # Skip if error has been added to the same object being handled
+      if err.record.object_id == model.object_id
+        raise
+      end
+
+      # Adds the error only if it hasn't been added already
+      already_imported = model
+        .errors
+        .each
+        .lazy
+        .select { |ae| ae.respond_to?(:inner_error) }
+        .map { |ae| ae.inner_error }
+        .include?(err.error)
+      if !already_imported
+        model.errors.import(err.error)
+      end
+
+      raise
+    ensure
+      # "Pop" handle_constraints! usage, when 0, no constraint handling should
+      # happen
+      Thread.current[:iry] -= 1
+    end
+
+    # Tracks constraints of models saved as a consequence of saving another
+    # model. This usually represents a situation of model using
+    # `accepts_nested_attributes_for`
+    # @param model [Handlers::Model]
+    # @yield
+    # @return [Handlers::Model]
+    # @private
+    def nested_constraints!(model, &block)
+      raise ArgumentError, "Block required" if block.nil?
+
+      block.()
+
+      return model
+    rescue ActiveRecord::StatementInvalid => err
+      # Exit immediately if Iry hasn't been activated
+      if Thread.current[:iry].nil? || Thread.current[:iry] == 0
+        raise
+      end
+
+      # Exception might be an unknown constraint that is not handled by Iry
+      # yet. If that's the case, Null handler will ensure that everything
+      # proceeds as if Iry wasn't involved
+      handler = Handlers::Null
+      case
+      when Handlers::PG.handle?(err)
+        handler = Handlers::PG
+      end
+
+      model_error = handler.handle(err, model)
+
+      # This constraint is not handled by Iry and should raise normally
+      if model_error.nil?
+        raise
+      end
+
+      raise(
+        StatementInvalid.new(
+          err.message,
+          sql: err.sql,
+          binds: err.binds,
+          record: model,
+          error: model_error
+        )
+      )
+    end
+
+    # @param model [Handlers::Model]
+    # @return [Boolean]
+    def save(model, ...)
+      success = nil
+      constraint_model = handle_constraints(model) { success = model.save(...) }
+
+      if constraint_model
+        return success
+      end
+
+      return false
+    end
+
+    # @param model [Handlers::Model]
+    # @return [true]
+    # @raise [ConstraintViolation]
+    # @raise [ActiveRecord::RecordInvalid]
+    def save!(model, ...)
+      constraint_model = handle_constraints(model) { model.save!(...) }
+
+      if constraint_model
+        return true
+      end
+
+      raise ConstraintViolation.new(model)
+    end
+
+    # @param model [Handlers::Model]
+    # @return [Handlers::Model]
+    def destroy(model)
+      constraint_result = handle_constraints(model) { model.destroy }
+
+      if constraint_result.nil?
+        return false
+      end
+
+      return constraint_result
+    end
+  end
+end

data/lib/iry.rb

@@ -12,6 +12,7 @@ require_relative "iry/constraint/exclusion"
 require_relative "iry/constraint/foreign_key"
 require_relative "iry/constraint/unique"
 require_relative "iry/patch"
+require_relative "iry/transform_constraints"
 
 # Entrypoint of constraint validation, include in a class inheriting {ActiveRecord::Base} and the following class-level
 # methods will be available:
@@ -40,7 +41,8 @@ module Iry
   end
 
   # Raised when constraints have been violated and have been converted to
-  # model errors
+  # model errors, on {ActiveRecord::Base#save!} calls, to simulate a behavior
+  # similar to {ActiveRecord::RecordInvalid} when it's raised
   class ConstraintViolation < ActiveRecord::RecordInvalid
     include Error
 
@@ -50,8 +52,26 @@ module Iry
     #   @return [Handlers::Model]
   end
 
+  # Raised when constraints errors happen and go through Iry, even if these
+  # are not handled. This class inherits from {ActiveRecord::StatementInvalid}
+  # to maximize compatibility with existing code
   class StatementInvalid < ActiveRecord::StatementInvalid
     include Error
+
+    # @return [Handlers::Model] model affected by the constraint violation
+    attr_reader :record
+    # @return [ActiveModel::Error] error attached to the `record` for the
+    #   constraint violation
+    attr_reader :error
+
+    # @param message [nil, String]
+    # @param record [Handlers::Model]
+    # @param error [ActiveModel::Error]
+    def initialize(message = nil, record:, error:, **kwargs)
+      @record = record
+      @error = error
+      super(message, **kwargs)
+    end
   end
 
   # @param klass [Module]
@@ -88,9 +108,7 @@ module Iry
   #   result #=> nil
   #   fail_user.errors.details.fetch(:email) #=> [{error: :taken}]
   def self.handle_constraints(model, &block)
-    handle_constraints!(model, &block)
-  rescue StatementInvalid
-    return nil
+    TransformConstraints.handle_constraints(model, &block)
   end
 
   # Executes block and in case of constraints violations on `model`, block is
@@ -100,26 +118,7 @@ module Iry
   # @yield block must perform the save operation, usually with `save`
   # @return [Handlers::Model] returns `model` parameter
   def self.handle_constraints!(model, &block)
-    raise ArgumentError, "Block required" if block.nil?
-
-    block.()
-
-    return model
-  rescue ActiveRecord::StatementInvalid => err
-    handler = Handlers::Null
-    case
-    when Handlers::PG.handle?(err)
-      handler = Handlers::PG
-    end
-
-    is_handled = handler.handle(err, model)
-
-    # This constraint is not handled by Iry and should raise normally
-    if !is_handled
-      raise
-    end
-
-    raise StatementInvalid.new(err.message, sql: err.sql, binds: err.binds)
+    TransformConstraints.handle_constraints!(model, &block)
   end
 
   # Similar to {ActiveRecord::Base#save} but in case of constraint violations,
@@ -129,14 +128,7 @@ module Iry
   # @param model [Handlers::Model] model to save
   # @return [Boolean] `true` if successful
   def self.save(model, ...)
-    success = nil
-    constraint_model = handle_constraints(model) { success = model.save(...) }
-
-    if constraint_model
-      return success
-    end
-
-    return false
+    TransformConstraints.save(model, ...)
   end
 
   # Similar to {ActiveRecord::Base#save!} but in case of constraint violations,
@@ -151,13 +143,7 @@ module Iry
   # @raise [ActiveRecord::RecordInvalid] triggered when a validation error is
   #   raised, but not a constraint violation
   def self.save!(model, ...)
-    constraint_model = handle_constraints(model) { model.save!(...) }
-
-    if constraint_model
-      return true
-    end
-
-    raise ConstraintViolation.new(model)
+    TransformConstraints.save!(model, ...)
   end
 
   # Similar to {ActiveRecord::Base#destroy} but in case of constraint
@@ -165,12 +151,6 @@ module Iry
   # @param model [Handlers::Model] model to destroy
   # @return [Handlers::Model] the destroyed model
   def self.destroy(model)
-    constraint_result = handle_constraints(model) { model.destroy }
-
-    if constraint_result.nil?
-      return false
-    end
-
-    return constraint_result
+    TransformConstraints.destroy(model)
   end
 end

data/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "iry",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "iry",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "license": "MIT",
       "devDependencies": {
         "conventional-changelog-cli": ">= 3.0.0",

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iry",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Transform database constraint errors into activerecord validation errors",
   "private": true,
   "main": "index.js",

data/rbi/iry.rbi

@@ -57,6 +57,15 @@ module Iry
   sig { params(model: Handlers::Model, block: T.untyped).void }
   def self.handle_constraints(model, &block); end
 
+  # Executes block and in case of constraints violations on `model`, block is
+  # halted, errors are appended to `model` and {StatementInvalid} is raised
+  # 
+  # _@param_ `model` — model object for which constraints should be monitored and for which errors should be added to
+  # 
+  # _@return_ — returns `model` parameter
+  sig { params(model: Handlers::Model, block: T.untyped).returns(Handlers::Model) }
+  def self.handle_constraints!(model, &block); end
+
   # Similar to {ActiveRecord::Base#save} but in case of constraint violations,
   # `false` is returned and `errors` are populated.
   # Aside from `model`, it takes the same arguments as
@@ -77,17 +86,71 @@ module Iry
   sig { params(model: Handlers::Model).returns(T::Boolean) }
   def self.save!(model); end
 
+  # Similar to {ActiveRecord::Base#destroy} but in case of constraint
+  # violations, `false` is returned and `errors` are populated.
+  # 
+  # _@param_ `model` — model to destroy
+  # 
+  # _@return_ — the destroyed model
+  sig { params(model: Handlers::Model).returns(Handlers::Model) }
+  def self.destroy(model); end
+
   # Included in all exceptions triggered by Iry, this allows to rescue any
   # gem-related exception by rescuing {Iry::Error}
   module Error
   end
 
   # Raised when constraints have been violated and have been converted to
-  # model errors
+  # model errors, on {ActiveRecord::Base#save!} calls, to simulate a behavior
+  # similar to {ActiveRecord::RecordInvalid} when it's raised
   class ConstraintViolation < ActiveRecord::RecordInvalid
     include Iry::Error
   end
 
+  # Raised when constraints errors happen and go through Iry, even if these
+  # are not handled. This class inherits from {ActiveRecord::StatementInvalid}
+  # to maximize compatibility with existing code
+  class StatementInvalid < ActiveRecord::StatementInvalid
+    include Iry::Error
+
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
+    # sord omit - no YARD type given for "**kwargs", using untyped
+    # _@param_ `message`
+    # 
+    # _@param_ `record`
+    # 
+    # _@param_ `error`
+    sig do
+      params(
+        message: T.nilable(String),
+        record: Handlers::Model,
+        error: ActiveModel::Error,
+        kwargs: T.untyped
+      ).void
+    end
+    def initialize(message = nil, record:, error:, **kwargs); end
+
+    # _@return_ — model affected by the constraint violation
+    sig { returns(Handlers::Model) }
+    attr_reader :record
+
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
+    # _@return_ — error attached to the `record` for the
+    # constraint violation
+    sig { returns(ActiveModel::Error) }
+    attr_reader :error
+  end
+
+  # Overrides private API method {ActiveRecord#create_or_update} to handle
+  # constraints and attach errors to the including model
+  module Patch
+    # Takes attributes as named arguments
+    # 
+    # _@return_ — true if successful
+    sig { returns(T::Boolean) }
+    def create_or_update; end
+  end
+
   # Class-level methods available to classes executing `include Iry`
   module Macros
     # Constraints by name
@@ -169,8 +232,9 @@ module Iry
       # 
       # _@param_ `model`
       # 
-      # _@return_ — true if this database handler handled the constraint error
-      sig { params(err: ActiveRecord::StatementInvalid, model: Model).returns(T::Boolean) }
+      # _@return_ — `nil` if couldn't handle the error,
+      # otherwise the {ActiveModel::Error} added to the model
+      sig { params(err: ActiveRecord::StatementInvalid, model: Model).void }
       def handle(err, model); end
     end
 
@@ -207,7 +271,7 @@ module Iry
     exclusion\sconstraint|
     foreign\skey\sconstraint
   )
-  \s"(.+)"
+  \s"([^"]+)"
 }x, T.untyped)
 
       # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
@@ -225,6 +289,10 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # 
+      # _@return_ — if handled constraint, returns the
+      # error attached to the model. If constraint wasn't handled or handling
+      # failed, `nil` is returned
       sig { params(err: ActiveRecord::StatementInvalid, model: Model).void }
       def handle(err, model); end
 
@@ -243,6 +311,10 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # 
+      # _@return_ — if handled constraint, returns the
+      # error attached to the model. If constraint wasn't handled or handling
+      # failed, `nil` is returned
       sig { params(err: ActiveRecord::StatementInvalid, model: Model).void }
       def self.handle(err, model); end
     end
@@ -265,7 +337,7 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      sig { params(err: ActiveRecord::StatementInvalid, model: Model).returns(T::Boolean) }
+      sig { params(err: ActiveRecord::StatementInvalid, model: Model).void }
       def handle(err, model); end
 
       # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
@@ -281,7 +353,7 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      sig { params(err: ActiveRecord::StatementInvalid, model: Model).returns(T::Boolean) }
+      sig { params(err: ActiveRecord::StatementInvalid, model: Model).void }
       def self.handle(err, model); end
     end
   end
@@ -305,10 +377,11 @@ module Iry
   # A constraint has a name and can apply errors to an object inheriting from {ActiveRecord::Base}
   # @abstract
   module Constraint
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
     # Sets validation errors on the model
     # 
     # _@param_ `model`
-    sig { params(model: Handlers::Model).void }
+    sig { params(model: Handlers::Model).returns(ActiveModel::Error) }
     def apply(model); end
 
     # Name of the constraint to be caught from the database
@@ -337,8 +410,9 @@ module Iry
       sig { params(key: Symbol, name: String, message: T.any(Symbol, String)).void }
       def initialize(key, name:, message: :invalid); end
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      sig { params(model: Handlers::Model).void }
+      sig { params(model: Handlers::Model).returns(ActiveModel::Error) }
       def apply(model); end
 
       sig { returns(Symbol) }
@@ -377,8 +451,9 @@ module Iry
       end
       def initialize(keys, name:, error_key:, message: :taken); end
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      sig { params(model: Handlers::Model).void }
+      sig { params(model: Handlers::Model).returns(ActiveModel::Error) }
       def apply(model); end
 
       sig { returns(T::Array[Symbol]) }
@@ -411,8 +486,9 @@ module Iry
       sig { params(key: Symbol, name: String, message: T.any(Symbol, String)).void }
       def initialize(key, name:, message: :taken); end
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      sig { params(model: Handlers::Model).void }
+      sig { params(model: Handlers::Model).returns(ActiveModel::Error) }
       def apply(model); end
 
       sig { returns(Symbol) }
@@ -451,8 +527,9 @@ module Iry
       end
       def initialize(keys, name:, error_key:, message: :required); end
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      sig { params(model: Handlers::Model).void }
+      sig { params(model: Handlers::Model).returns(ActiveModel::Error) }
       def apply(model); end
 
       sig { returns(T::Array[Symbol]) }
@@ -468,4 +545,66 @@ module Iry
       attr_accessor :error_key
     end
   end
+
+  # Implementation of {Iry} methods, helps ensuring the main module focus on
+  # documentation
+  module TransformConstraints
+    extend Iry::TransformConstraints
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).void }
+    def handle_constraints(model, &block); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).returns(Handlers::Model) }
+    def handle_constraints!(model, &block); end
+
+    # Tracks constraints of models saved as a consequence of saving another
+    # model. This usually represents a situation of model using
+    # `accepts_nested_attributes_for`
+    # 
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).returns(Handlers::Model) }
+    def nested_constraints!(model, &block); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(T::Boolean) }
+    def save(model); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(T::Boolean) }
+    def save!(model); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(Handlers::Model) }
+    def destroy(model); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).void }
+    def self.handle_constraints(model, &block); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).returns(Handlers::Model) }
+    def self.handle_constraints!(model, &block); end
+
+    # Tracks constraints of models saved as a consequence of saving another
+    # model. This usually represents a situation of model using
+    # `accepts_nested_attributes_for`
+    # 
+    # _@param_ `model`
+    sig { params(model: Handlers::Model, block: T.untyped).returns(Handlers::Model) }
+    def self.nested_constraints!(model, &block); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(T::Boolean) }
+    def self.save(model); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(T::Boolean) }
+    def self.save!(model); end
+
+    # _@param_ `model`
+    sig { params(model: Handlers::Model).returns(Handlers::Model) }
+    def self.destroy(model); end
+  end
 end

data/sig/iry.rbs

@@ -53,6 +53,14 @@ module Iry
   # ```
   def self.handle_constraints: (Handlers::Model model) -> void
 
+  # Executes block and in case of constraints violations on `model`, block is
+  # halted, errors are appended to `model` and {StatementInvalid} is raised
+  # 
+  # _@param_ `model` — model object for which constraints should be monitored and for which errors should be added to
+  # 
+  # _@return_ — returns `model` parameter
+  def self.handle_constraints!: (Handlers::Model model) -> Handlers::Model
+
   # Similar to {ActiveRecord::Base#save} but in case of constraint violations,
   # `false` is returned and `errors` are populated.
   # Aside from `model`, it takes the same arguments as
@@ -71,17 +79,64 @@ module Iry
   # _@param_ `model` — model to save
   def self.save!: (Handlers::Model model) -> bool
 
+  # Similar to {ActiveRecord::Base#destroy} but in case of constraint
+  # violations, `false` is returned and `errors` are populated.
+  # 
+  # _@param_ `model` — model to destroy
+  # 
+  # _@return_ — the destroyed model
+  def self.destroy: (Handlers::Model model) -> Handlers::Model
+
   # Included in all exceptions triggered by Iry, this allows to rescue any
   # gem-related exception by rescuing {Iry::Error}
   module Error
   end
 
   # Raised when constraints have been violated and have been converted to
-  # model errors
+  # model errors, on {ActiveRecord::Base#save!} calls, to simulate a behavior
+  # similar to {ActiveRecord::RecordInvalid} when it's raised
   class ConstraintViolation < ActiveRecord::RecordInvalid
     include Iry::Error
   end
 
+  # Raised when constraints errors happen and go through Iry, even if these
+  # are not handled. This class inherits from {ActiveRecord::StatementInvalid}
+  # to maximize compatibility with existing code
+  class StatementInvalid < ActiveRecord::StatementInvalid
+    include Iry::Error
+
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
+    # sord omit - no YARD type given for "**kwargs", using untyped
+    # _@param_ `message`
+    # 
+    # _@param_ `record`
+    # 
+    # _@param_ `error`
+    def initialize: (
+                      ?String? message,
+                      record: Handlers::Model,
+                      error: ActiveModel::Error,
+                      **untyped kwargs
+                    ) -> void
+
+    # _@return_ — model affected by the constraint violation
+    attr_reader record: Handlers::Model
+
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
+    # _@return_ — error attached to the `record` for the
+    # constraint violation
+    attr_reader error: ActiveModel::Error
+  end
+
+  # Overrides private API method {ActiveRecord#create_or_update} to handle
+  # constraints and attach errors to the including model
+  module Patch
+    # Takes attributes as named arguments
+    # 
+    # _@return_ — true if successful
+    def create_or_update: () -> bool
+  end
+
   # Class-level methods available to classes executing `include Iry`
   module Macros
     # Constraints by name
@@ -153,8 +208,9 @@ module Iry
       # 
       # _@param_ `model`
       # 
-      # _@return_ — true if this database handler handled the constraint error
-      def handle: (ActiveRecord::StatementInvalid err, Model model) -> bool
+      # _@return_ — `nil` if couldn't handle the error,
+      # otherwise the {ActiveModel::Error} added to the model
+      def handle: (ActiveRecord::StatementInvalid err, Model model) -> void
     end
 
     # Interface of the model class. This class is usually inherits from {ActiveRecord::Base}
@@ -195,6 +251,10 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # 
+      # _@return_ — if handled constraint, returns the
+      # error attached to the model. If constraint wasn't handled or handling
+      # failed, `nil` is returned
       def handle: (ActiveRecord::StatementInvalid err, Model model) -> void
 
       # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
@@ -211,6 +271,10 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # 
+      # _@return_ — if handled constraint, returns the
+      # error attached to the model. If constraint wasn't handled or handling
+      # failed, `nil` is returned
       def self.handle: (ActiveRecord::StatementInvalid err, Model model) -> void
     end
 
@@ -231,7 +295,7 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      def handle: (ActiveRecord::StatementInvalid err, Model model) -> bool
+      def handle: (ActiveRecord::StatementInvalid err, Model model) -> void
 
       # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
       # Returns always true, catching any unhandled database exception
@@ -245,7 +309,7 @@ module Iry
       # _@param_ `err`
       # 
       # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      def self.handle: (ActiveRecord::StatementInvalid err, Model model) -> bool
+      def self.handle: (ActiveRecord::StatementInvalid err, Model model) -> void
     end
   end
 
@@ -266,10 +330,11 @@ module Iry
   # A constraint has a name and can apply errors to an object inheriting from {ActiveRecord::Base}
   # @abstract
   module Constraint
+    # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
     # Sets validation errors on the model
     # 
     # _@param_ `model`
-    def apply: (Handlers::Model model) -> void
+    def apply: (Handlers::Model model) -> ActiveModel::Error
 
     # Name of the constraint to be caught from the database
     def name: () -> String
@@ -293,8 +358,9 @@ module Iry
       # _@param_ `name` — constraint name
       def initialize: (Symbol key, name: String, ?message: (Symbol | String)) -> void
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      def apply: (Handlers::Model model) -> void
+      def apply: (Handlers::Model model) -> ActiveModel::Error
 
       attr_accessor key: Symbol
 
@@ -325,8 +391,9 @@ module Iry
                         ?message: (Symbol | String)
                       ) -> void
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      def apply: (Handlers::Model model) -> void
+      def apply: (Handlers::Model model) -> ActiveModel::Error
 
       attr_accessor keys: ::Array[Symbol]
 
@@ -352,8 +419,9 @@ module Iry
       # _@param_ `name` — constraint name
       def initialize: (Symbol key, name: String, ?message: (Symbol | String)) -> void
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      def apply: (Handlers::Model model) -> void
+      def apply: (Handlers::Model model) -> ActiveModel::Error
 
       attr_accessor key: Symbol
 
@@ -384,8 +452,9 @@ module Iry
                         ?message: (Symbol | String)
                       ) -> void
 
+      # sord warn - ActiveModel::Error wasn't able to be resolved to a constant in this project
       # _@param_ `model`
-      def apply: (Handlers::Model model) -> void
+      def apply: (Handlers::Model model) -> ActiveModel::Error
 
       attr_accessor keys: ::Array[Symbol]
 
@@ -396,4 +465,54 @@ module Iry
       attr_accessor error_key: Symbol
     end
   end
+
+  # Implementation of {Iry} methods, helps ensuring the main module focus on
+  # documentation
+  module TransformConstraints
+    extend Iry::TransformConstraints
+
+    # _@param_ `model`
+    def handle_constraints: (Handlers::Model model) -> void
+
+    # _@param_ `model`
+    def handle_constraints!: (Handlers::Model model) -> Handlers::Model
+
+    # Tracks constraints of models saved as a consequence of saving another
+    # model. This usually represents a situation of model using
+    # `accepts_nested_attributes_for`
+    # 
+    # _@param_ `model`
+    def nested_constraints!: (Handlers::Model model) -> Handlers::Model
+
+    # _@param_ `model`
+    def save: (Handlers::Model model) -> bool
+
+    # _@param_ `model`
+    def save!: (Handlers::Model model) -> bool
+
+    # _@param_ `model`
+    def destroy: (Handlers::Model model) -> Handlers::Model
+
+    # _@param_ `model`
+    def self.handle_constraints: (Handlers::Model model) -> void
+
+    # _@param_ `model`
+    def self.handle_constraints!: (Handlers::Model model) -> Handlers::Model
+
+    # Tracks constraints of models saved as a consequence of saving another
+    # model. This usually represents a situation of model using
+    # `accepts_nested_attributes_for`
+    # 
+    # _@param_ `model`
+    def self.nested_constraints!: (Handlers::Model model) -> Handlers::Model
+
+    # _@param_ `model`
+    def self.save: (Handlers::Model model) -> bool
+
+    # _@param_ `model`
+    def self.save!: (Handlers::Model model) -> bool
+
+    # _@param_ `model`
+    def self.destroy: (Handlers::Model model) -> Handlers::Model
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iry
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Francesco Belladonna
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-11 00:00:00.000000000 Z
+date: 2023-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -107,6 +107,7 @@ files:
 - lib/iry/handlers/pg.rb
 - lib/iry/macros.rb
 - lib/iry/patch.rb
+- lib/iry/transform_constraints.rb
 - lib/iry/version.rb
 - package-lock.json
 - package.json