iry 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cabc0965e3b746552dee09d6fcf0356bb0f166114e3cb9d696c00c033742016
-  data.tar.gz: 0171d5388f8a7ee89d942e1ea959e2e309f3ef15fc869dba804dba8e6de0877f
+  metadata.gz: 8c37af75076323e55b59756a3929843bbbca04cd0bc43bc49ae89ef68e9d1665
+  data.tar.gz: 2b4ca6aef3667fc9f6215d1d828d732dac0c8930044e88f8234cf690b5b7a514
 SHA512:
-  metadata.gz: ef0954dca71dbdeacd8588256939faa6a18b16ff85d1b913980c23e5058c54ceaf946959de3bbb0b9f421b5b5b3f57dea5d4d001295d6e2ad17fbfeda688771d
-  data.tar.gz: cd3117ad1717f98fbe96d823920a25742aca1a3f10948f60ae47f9567a31c7e55633d7b2dc3ee8d151cb60e7416bd9cdb840211e8e81cd44d63ced15b199bdc1
+  metadata.gz: 8a9d1bb387cfc7d5809235378f80f84d8961a53cba63c9dddc6f8538352412cb02ab59d87e8fea16d5ac6c87ce1a243541ea421f4a1f14ce568331c8d1c77d70
+  data.tar.gz: 0fe39194ef0b3f17719f9d66a6a7881eafd8cb02e3ef50cd42c154a18875ebc726e31155a570d3fc0687547bf01b158bf7267adb4c19ac3422b9fe5aa86e1394

data/.yardopts

@@ -1 +1 @@
---no-private 'lib/**/*.rb' - 'README.md' 'CHANGELOG.md' VERSION LICENSE '.envrc.example' Gemfile 'Gemfile.lock' 'db/schema.pgsql' 'iry.gemspec'
+--no-private 'lib/**/*.rb' - 'README.md' VERSION LICENSE '.envrc.example' Gemfile 'Gemfile.lock' 'db/schema.pgsql' 'iry.gemspec'

data/README.md

@@ -6,7 +6,7 @@ Convert constraint errors into Rails model validation errors.
 
 ## Documentation
 
-https://rubydoc.info/gems/iry/frames
+https://rubydoc.info/gems/iry
 
 ## Usage
 
@@ -14,7 +14,6 @@ Given the following database schema:
 
 ```sql
 create extension if not exists "pgcrypto";
-create extension if not exists "btree_gist";
 
 create table if not exists users (
     id uuid primary key default gen_random_uuid(),
@@ -24,7 +23,7 @@ create table if not exists users (
 );
 ```
 
-The following constraint can be used on the `User` class:
+Set the following constraint on the `User` class:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -36,14 +35,22 @@ class User < ActiveRecord::Base
 end
 ```
 
+Now one of the saving mechanisms can be used:
+- [`handle_constraints`](#handle_constraints)
+- [`save`](#save)
+- [`save!`](#save!)
+- [`destroy`](#destroy)
+
 When saving a new `User` record or updating it, in case constraint exceptions are raised, these will be rescued and
 validation errors will be applied to the record, like in the following example:
 
 ```ruby
 user = User.create!(unique_text: "some unique text")
+fail_user = User.new(unique_text: "some unique text")
 
-fail_user = User.create(unique_text: "some unique text")
+success = Iry.save(fail_user)
 
+success #=> false
 fail_user.errors.details.fetch(:unique_text) #=> [{error: :taken}]
 ```
 
@@ -62,7 +69,7 @@ The class method `.constraints` is also available, that returns all the constrai
 
 ### [`check_constraint`](https://rubydoc.info/gems/iry/Iry%2FMacros:check_constraint)
 
-```rbs
+```ruby
 check_constraint(key, name: nil, message: :invalid) ⇒ void
 ```
 
@@ -74,7 +81,7 @@ Catches a specific check constraint violation.
 
 ### [`exclusion_constraint`](https://rubydoc.info/gems/iry/Iry%2FMacros:exclusion_constraint)
 
-```rbs
+```ruby
 exclusion_constraint(key, name: nil, message: :taken) ⇒ void
 ```
 
@@ -86,7 +93,7 @@ Catches a specific exclusion constraint violation.
 
 ### [`foreign_key_constraint`](https://rubydoc.info/gems/iry/Iry%2FMacros:foreign_key_constraint)
 
-```rbs
+```ruby
 foreign_key_constraint(key_or_keys, name: nil, message: :required, error_key: nil) ⇒ void
 ```
 
@@ -99,7 +106,7 @@ Catches a specific foreign key constraint violation.
 
 ### [`unique_constraint`](https://rubydoc.info/gems/iry/Iry%2FMacros:unique_constraint)
 
-```rbs
+```ruby
 unique_constraint(key_or_keys, name: nil, message: :taken, error_key: nil) ⇒ void
 ```
 
@@ -110,12 +117,42 @@ Catches a specific foreign key constraint violation.
 - **message** (optional `String` or `Symbol`) error message, defaults to `:taken`
 - **error_key** (optional `Symbol`) which key will have validation errors added to
 
+## Advanced Usage
+
+### [`handle_constraints!`](https://rubydoc.info/gems/iry/Iry.handle_constraints)
+
+```ruby
+.handle_constraints(model) { ... } ⇒ nil, Handlers::Model
+```
+
+Serving as base for `save` and `save!`, it will detects constraint violations, halt the execution of the block, convert
+violations to validation errors and return `nil` when violations are detected, otherwise the model object provided as
+argument.
+
+### [`save`](https://rubydoc.info/gems/iry/Iry.save)
+
+Acts the same as `ActiveRecord::Base#save`, accepting the same arguments and returning the same values.
+In addition, it will return `false` if a constraint violation of the tracked constraints is detected and validation
+errors will be added to `errors`.
+
+### [`save!`](https://rubydoc.info/gems/iry/Iry.save!)
+
+Acts the same as `ActiveRecord::Base#save!`, accepting the same arguments and returning the same values.
+In addition, it will raise `Iry::ConstraintViolation` when constraint violations are detected.
+
+### [`destroy`](https://rubydoc.info/gems/iry/Iry.destroy)
+
+Acts the same as `ActiveRecord::Base#destroy`.
+In addition, it will return `false` if a constraint violation of the tracked constraints is detected and validation
+errors will be added to `errors`.
+
 ## Limitations
 
 - `valid?` will not check for constraints. If calling `valid?` right after a `save` operation, keep in mind `errors`
     are cleared
-- `create!` and `update!` will raise `ActiveRecord::RecordNotSaved` for constraints that are caught by `iry`, instead
-    of `ActiveModel::ValidationError`
+- It is recommended to avoid transactions when using `Iry`, because if a violation is detected, anything after
+    `Iry.save/save!/handle_constraints` will result in `ActiveRecord::StatementInvalid`, since the transaction is
+    aborted
 - Currently only PostgreSQL is supported with the `pg` gem, but it should be simple to add support for other databases.
 
 ## Installation

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.5.0

data/db/schema.pgsql

@@ -7,6 +7,7 @@ create table if not exists users (
   exclude_text text not null default gen_random_uuid()::text,
 	user_id uuid references users (id),
   untracked_text text unique not null default gen_random_uuid()::text,
+  free_text text not null default '',
 	friend_user_id uuid references users (id),
 	created_at timestamp(6) not null,
 	updated_at timestamp(6) not null,

data/lib/iry/handlers/pg.rb

@@ -13,7 +13,7 @@ module Iry
           exclusion\sconstraint|
           foreign\skey\sconstraint
         )
-        \s"(.+)"
+        \s"([^"]+)"
       }x
 
       # When true, the handler is able to handle this exception, representing a constraint error in PostgreSQL.

data/lib/iry/patch.rb

@@ -0,0 +1,13 @@
+module Iry
+  # 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 [Boolean] true if successful
+    def create_or_update(...)
+      result = false
+      Iry.handle_constraints!(self) { result = super }
+      result
+    end
+  end
+end

data/lib/iry.rb

@@ -11,6 +11,7 @@ require_relative "iry/constraint/check"
 require_relative "iry/constraint/exclusion"
 require_relative "iry/constraint/foreign_key"
 require_relative "iry/constraint/unique"
+require_relative "iry/patch"
 
 # Entrypoint of constraint validation, include in a class inheriting {ActiveRecord::Base} and the following class-level
 # methods will be available:
@@ -29,12 +30,28 @@ require_relative "iry/constraint/unique"
 #   end
 #
 #   user = User.create!(email: "user@example.com")
-#   fail_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
-  # Raised when constraint errors have been violated and have been converted to
+  # 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
-  class RecordInvalid < ActiveRecord::RecordInvalid
+  class ConstraintViolation < ActiveRecord::RecordInvalid
+    include Error
+
+    # @!method record
+    #   Inherited from {ActiveRecord::RecordInvalid}, returns the model for
+    #   which the constraint violations have been detected
+    #   @return [Handlers::Model]
+  end
+
+  class StatementInvalid < ActiveRecord::StatementInvalid
+    include Error
   end
 
   # @param klass [Module]
@@ -46,6 +63,7 @@ module Iry
       class_attribute(:constraints)
       self.constraints = {}
       extend(Iry::Macros)
+      include(Iry::Patch)
     end
   end
 
@@ -56,7 +74,32 @@ module Iry
   # @yield block must perform the save operation, usually with `save`
   # @return [nil, Handlers::Model] the `model` or `nil` if a  a constraint is
   #   violated
+  # @example Handle constraints for unique user
+  #   # 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(model, &block)
+    handle_constraints!(model, &block)
+  rescue StatementInvalid
+    return nil
+  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 [Handlers::Model] model object for which constraints should be
+  #   monitored and for which errors should be added to
+  # @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.()
@@ -71,11 +114,12 @@ module Iry
 
     is_handled = handler.handle(err, model)
 
+    # This constraint is not handled by Iry and should raise normally
     if !is_handled
       raise
     end
 
-    return nil
+    raise StatementInvalid.new(err.message, sql: err.sql, binds: err.binds)
   end
 
   # Similar to {ActiveRecord::Base#save} but in case of constraint violations,
@@ -96,12 +140,12 @@ module Iry
   end
 
   # Similar to {ActiveRecord::Base#save!} but in case of constraint violations,
-  # it raises {RecordInvalid} and `errors` are populated.
+  # it raises {ConstraintViolation} and `errors` are populated.
   # Aside from `model`, it takes the same arguments as
   # {ActiveRecord::Base#save!}
   # @param model [Handlers::Model] model to save
   # @return [true]
-  # @raise [RecordInvalid] {RecordInvalid} inherits from
+  # @raise [ConstraintViolation] {ConstraintViolation} inherits from
   #   {ActiveRecord::RecordInvalid} but it's triggered only when a constraint
   #   violation happens
   # @raise [ActiveRecord::RecordInvalid] triggered when a validation error is
@@ -113,6 +157,20 @@ module Iry
       return true
     end
 
-    raise RecordInvalid.new(model)
+    raise ConstraintViolation.new(model)
+  end
+
+  # Similar to {ActiveRecord::Base#destroy} but in case of constraint
+  # violations, `false` is returned and `errors` are populated.
+  # @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
   end
 end

data/package-lock.json

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

data/package.json

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

data/rbi/iry.rbi

@@ -16,15 +16,78 @@
 #   end
 # 
 #   user = User.create!(email: "user@example.com")
-#   fail_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 = T.let(File.read(File.expand_path("../../VERSION", __dir__)).strip.freeze, T.untyped)
 
+  # Inherited from {ActiveRecord::RecordInvalid}, returns the model for
+  # which the constraint violations have been detected
+  sig { returns(Handlers::Model) }
+  def record; end
+
   # _@param_ `klass`
   sig { params(klass: Module).void }
   def self.included(klass); end
 
+  # 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}]
+  # ```
+  sig { params(model: Handlers::Model, block: T.untyped).void }
+  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
+  # {ActiveRecord::Base#save}
+  # 
+  # _@param_ `model` — model to save
+  # 
+  # _@return_ — `true` if successful
+  sig { params(model: Handlers::Model).returns(T::Boolean) }
+  def self.save(model); end
+
+  # 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
+  sig { params(model: Handlers::Model).returns(T::Boolean) }
+  def self.save!(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
+  class ConstraintViolation < ActiveRecord::RecordInvalid
+    include Iry::Error
+  end
+
   # Class-level methods available to classes executing `include Iry`
   module Macros
     # Constraints by name

data/sig/iry.rbs

@@ -15,14 +15,73 @@
 #   end
 # 
 #   user = User.create!(email: "user@example.com")
-#   fail_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
+
+  # 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
+
+  # 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
+  class ConstraintViolation < ActiveRecord::RecordInvalid
+    include Iry::Error
+  end
+
   # Class-level methods available to classes executing `include Iry`
   module Macros
     # Constraints by name

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iry
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Francesco Belladonna
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-09 00:00:00.000000000 Z
+date: 2023-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -89,7 +89,6 @@ extra_rdoc_files: []
 files:
 - ".envrc.example"
 - ".yardopts"
-- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile
@@ -107,6 +106,7 @@ files:
 - lib/iry/handlers/null.rb
 - lib/iry/handlers/pg.rb
 - lib/iry/macros.rb
+- lib/iry/patch.rb
 - lib/iry/version.rb
 - package-lock.json
 - package.json
@@ -122,7 +122,6 @@ metadata:
   allowed_push_host: https://rubygems.org/
   homepage_uri: https://github.com/Fire-Dragon-DoL/iry
   source_code_uri: https://github.com/Fire-Dragon-DoL/iry
-  changelog_uri: https://github.com/Fire-Dragon-DoL/iry/blob/main/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:

data/CHANGELOG.md

@@ -1,15 +0,0 @@
-# [0.2.0](https://github.com/Fire-Dragon-DoL/iry/compare/8a133c2c19b99881619a9e1c7c11076030755f66...v0.2.0) (2023-07-08)
-
-
-### Features
-
-* **constraints:** check constraint is present ([d0cc380](https://github.com/Fire-Dragon-DoL/iry/commit/d0cc3803fdcda45df964f6431890f8831d3641e5))
-* **constraints:** exclusion constraint is present ([1894e85](https://github.com/Fire-Dragon-DoL/iry/commit/1894e85bfa11e272be9b5f0f8efc170f7ce57a48))
-* **constraints:** foreign key constraint is present ([e637b06](https://github.com/Fire-Dragon-DoL/iry/commit/e637b0603bb6fd34e2732426544fc31904bb5409))
-* **deps:** dependency surface is reduced ([2dfc595](https://github.com/Fire-Dragon-DoL/iry/commit/2dfc595ebd221aedb072398e1ace8460208d06ac))
-* **project:** setup ([8a133c2](https://github.com/Fire-Dragon-DoL/iry/commit/8a133c2c19b99881619a9e1c7c11076030755f66))
-* **ruby:** version is forced to >= 2.7 ([9b20ed8](https://github.com/Fire-Dragon-DoL/iry/commit/9b20ed8ec0ae2a9906bdefe28cf674d4700f4d67))
-* **unique-constraint:** test is implemented ([c4266b9](https://github.com/Fire-Dragon-DoL/iry/commit/c4266b910757b6adef18db41dfa5dfd9353c1037))
-
-
-