iry 0.8.0 → 0.9.1

data/sig/iry.rbs

@@ -1,520 +0,0 @@
-# Entrypoint of constraint validation, include in a class inheriting {ActiveRecord::Base} and the following class-level
-# methods will be available:
-# - {Macros#constraints}
-# - {Macros#check_constraint}
-# - {Macros#exclusion_constraint}
-# - {Macros#foreign_key_constraint}
-# - {Macros#unique_constraint}
-# 
-# @example User unique constraint validation
-#   # The database schema has a unique constraint on email field
-#   class User < ActiveRecord::Base
-#     include Iry
-# 
-#     unique_constraint :email
-#   end
-# 
-#   user = User.create!(email: "user@example.com")
-#   fail_user = User.new(email: "user@example.com")
-#   Iry.save(fail_user)
-#   fail_user.errors.details.fetch(:email) #=> [{error: :taken}]
-module Iry
-  VERSION: String
-
-  # Inherited from {ActiveRecord::RecordInvalid}, returns the model for
-  # which the constraint violations have been detected
-  def record: () -> Handlers::Model
-
-  # _@param_ `klass`
-  def self.included: (Module klass) -> void
-
-  # Executes block and in case of constraints violations on `model`, block is
-  # halted and errors are appended to `model`
-  # 
-  # _@param_ `model` — model object for which constraints should be monitored and for which errors should be added to
-  # 
-  # _@return_ — the `model` or `nil` if a  a constraint is
-  # violated
-  # 
-  # Handle constraints for unique user
-  # ```ruby
-  # # The database schema has a unique constraint on email field
-  # class User < ActiveRecord::Base
-  #   include Iry
-  # 
-  #   unique_constraint :email
-  # end
-  # 
-  # user = User.create!(email: "user@example.com")
-  # fail_user = User.new(email: "user@example.com")
-  # result = Iry.handle_constraints(fail_user) { fail_user.save }
-  # result #=> nil
-  # fail_user.errors.details.fetch(:email) #=> [{error: :taken}]
-  # ```
-  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
-  # {ActiveRecord::Base#save}
-  # 
-  # _@param_ `model` — model to save
-  # 
-  # _@return_ — `true` if successful
-  def self.save: (Handlers::Model model) -> bool
-
-  # Similar to {ActiveRecord::Base#save!} but in case of constraint violations,
-  # it raises {ConstraintViolation} and `errors` are populated.
-  # Aside from `model`, it takes the same arguments as
-  # {ActiveRecord::Base#save!}
-  # 
-  # _@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, 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
-    def constraints: () -> ::Hash[String, Constraint]
-
-    # Tracks check constraint for the given key and convert constraint errors into validation errors
-    # 
-    # _@param_ `key` — key to apply validation errors to
-    # 
-    # _@param_ `message` — the validation error message
-    # 
-    # _@param_ `name` — constraint name. If omitted, it will be inferred using table name + key
-    def check_constraint: (Symbol key, ?name: String?, ?message: (Symbol | String)) -> void
-
-    # Tracks exclusion constraint for the given key and convert constraint errors into validation errors
-    # 
-    # _@param_ `key` — key to apply validation errors to
-    # 
-    # _@param_ `message` — the validation error message
-    # 
-    # _@param_ `name` — constraint name. If omitted, it will be inferred using table name + key
-    def exclusion_constraint: (Symbol key, ?name: String?, ?message: (Symbol | String)) -> void
-
-    # Tracks foreign key constraint for the given key (or keys) and convert constraint errors into validation errors
-    # 
-    # _@param_ `key_or_keys` — key or array of keys to track the foreign key constraint of
-    # 
-    # _@param_ `message` — the validation error message
-    # 
-    # _@param_ `name` — constraint name. If omitted, it will be inferred using table name + keys
-    # 
-    # _@param_ `error_key` — key to which the validation error will be applied to. If omitted, it will be applied to the first key
-    def foreign_key_constraint: (
-                                  (Symbol | ::Array[Symbol]) key_or_keys,
-                                  ?name: String?,
-                                  ?message: (Symbol | String),
-                                  ?error_key: Symbol?
-                                ) -> void
-
-    # Tracks uniqueness constraint for the given key (or keys) and convert constraint errors into validation errors
-    # 
-    # _@param_ `key_or_keys` — key or array of keys to track the uniqueness constraint of
-    # 
-    # _@param_ `message` — the validation error message
-    # 
-    # _@param_ `name` — constraint name. If omitted, it will be inferred using table name + keys
-    # 
-    # _@param_ `error_key` — key to which the validation error will be applied to. If omitted, it will be applied to the first key
-    def unique_constraint: (
-                             (Symbol | ::Array[Symbol]) key_or_keys,
-                             ?name: String?,
-                             ?message: (Symbol | String),
-                             ?error_key: Symbol?
-                           ) -> void
-  end
-
-  module Handlers
-    # Interface for handlers of different database types
-    # @abstract
-    module Handler
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # _@param_ `err` — possible constraint error to handle
-      # 
-      # _@return_ — true if this database handler is the correct one for this exception
-      def handle?: (ActiveRecord::StatementInvalid err) -> bool
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # _@param_ `err` — possible constraint error to handle
-      # 
-      # _@param_ `model`
-      # 
-      # _@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}
-    # @abstract
-    module ModelClass
-      def table_name: () -> String
-
-      def constraints: () -> ::Hash[String, Constraint]
-    end
-
-    # Interface of the model that should be used to handle constraints.
-    # This object is an instance of {ActiveRecord::Base}
-    # @abstract
-    module Model
-      # sord warn - ActiveModel::Errors wasn't able to be resolved to a constant in this project
-      def errors: () -> ActiveModel::Errors
-
-      def class: () -> ModelClass
-    end
-
-    # PostgreSQL handler through `pg` gem
-    # @private
-    module PG
-      extend Iry::Handlers::PG
-      REGEX: Regexp
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # When true, the handler is able to handle this exception, representing a constraint error in PostgreSQL.
-      # This method must ensure not to raise exception in case the postgresql adapter is missing and as such, the
-      # postgres constant is undefined
-      # 
-      # _@param_ `err`
-      def handle?: (ActiveRecord::StatementInvalid err) -> bool
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # Appends constraint errors as model errors
-      # 
-      # _@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
-      # When true, the handler is able to handle this exception, representing a constraint error in PostgreSQL.
-      # This method must ensure not to raise exception in case the postgresql adapter is missing and as such, the
-      # postgres constant is undefined
-      # 
-      # _@param_ `err`
-      def self.handle?: (ActiveRecord::StatementInvalid err) -> bool
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # Appends constraint errors as model errors
-      # 
-      # _@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
-
-    # Catch-all handler for unrecognized database adapters
-    # @private
-    module Null
-      extend Iry::Handlers::Null
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # Returns always true, catching any unhandled database exception
-      # 
-      # _@param_ `err`
-      def handle?: ((StandardError | ActiveRecord::StatementInvalid) err) -> bool
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # Return always false, failing to handle any constraint
-      # 
-      # _@param_ `err`
-      # 
-      # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      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
-      # 
-      # _@param_ `err`
-      def self.handle?: ((StandardError | ActiveRecord::StatementInvalid) err) -> bool
-
-      # sord warn - ActiveRecord::StatementInvalid wasn't able to be resolved to a constant in this project
-      # Return always false, failing to handle any constraint
-      # 
-      # _@param_ `err`
-      # 
-      # _@param_ `model` — should inherit {ActiveRecord::Base} and`include Iry` to match the interface
-      def self.handle: (ActiveRecord::StatementInvalid err, Model model) -> void
-    end
-  end
-
-  # Main function to kick-off **Iry** constraint-checking mechanism
-  # If interested in adding support for other databases beside Postgres, modify this file.
-  # @private
-  module Callbacks
-    extend Iry::Callbacks
-
-    # _@param_ `model`
-    def around_save: (Handlers::Model model) -> void
-
-    # _@param_ `model`
-    def self.around_save: (Handlers::Model model) -> void
-  end
-
-  # Interface representing a constraint.
-  # 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) -> ActiveModel::Error
-
-    # Name of the constraint to be caught from the database
-    def name: () -> String
-
-    # Message to be attached as validation error to the model
-    # (see Handlers::Model)
-    def message: () -> (Symbol | String)
-
-    class Check
-      # Infers the check constraint name based on key and table name
-      # 
-      # _@param_ `key`
-      # 
-      # _@param_ `table_name`
-      def self.infer_name: (Symbol key, String table_name) -> String
-
-      # _@param_ `key` — key to apply error message for check constraint to
-      # 
-      # _@param_ `message` — the validation error message
-      # 
-      # _@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) -> ActiveModel::Error
-
-      attr_accessor key: Symbol
-
-      attr_accessor message: (Symbol | String)
-
-      attr_accessor name: String
-    end
-
-    class Unique
-      MAX_INFER_NAME_BYTE_SIZE: untyped
-
-      # Infers the unique constraint name based on keys and table name
-      # 
-      # _@param_ `keys`
-      # 
-      # _@param_ `table_name`
-      def self.infer_name: (::Array[Symbol] keys, String table_name) -> String
-
-      # _@param_ `keys` — array of keys to track the uniqueness constraint of
-      # 
-      # _@param_ `message` — the validation error message
-      # 
-      # _@param_ `name` — constraint name
-      # 
-      # _@param_ `error_key` — key to which the validation error will be applied to
-      def initialize: (
-                        ::Array[Symbol] keys,
-                        name: String,
-                        error_key: Symbol,
-                        ?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) -> ActiveModel::Error
-
-      attr_accessor keys: ::Array[Symbol]
-
-      attr_accessor message: (Symbol | String)
-
-      attr_accessor name: String
-
-      attr_accessor error_key: Symbol
-    end
-
-    class Exclusion
-      # Infers the exclusion constraint name based on key and table name
-      # 
-      # _@param_ `key`
-      # 
-      # _@param_ `table_name`
-      def self.infer_name: (Symbol key, String table_name) -> String
-
-      # _@param_ `key` — key to apply error message for exclusion constraint to
-      # 
-      # _@param_ `message` — the validation error message
-      # 
-      # _@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) -> ActiveModel::Error
-
-      attr_accessor key: Symbol
-
-      attr_accessor message: (Symbol | String)
-
-      attr_accessor name: String
-    end
-
-    class ForeignKey
-      # Infers the unique constraint name based on keys and table name
-      # 
-      # _@param_ `keys`
-      # 
-      # _@param_ `table_name`
-      def self.infer_name: (::Array[Symbol] keys, String table_name) -> String
-
-      # _@param_ `keys` — array of keys to track the uniqueness constraint of
-      # 
-      # _@param_ `message` — the validation error message
-      # 
-      # _@param_ `name` — constraint name
-      # 
-      # _@param_ `error_key` — key to which the validation error will be applied to
-      def initialize: (
-                        ::Array[Symbol] keys,
-                        name: String,
-                        error_key: Symbol,
-                        ?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) -> ActiveModel::Error
-
-      attr_accessor keys: ::Array[Symbol]
-
-      attr_accessor message: (Symbol | String)
-
-      attr_accessor name: String
-
-      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