iry 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cabc0965e3b746552dee09d6fcf0356bb0f166114e3cb9d696c00c033742016
-  data.tar.gz: 0171d5388f8a7ee89d942e1ea959e2e309f3ef15fc869dba804dba8e6de0877f
+  metadata.gz: 4e4fc1d3dfa1e63a0ac7c38443301f2635ac7d60866d5799a1a6a78b5cdb9326
+  data.tar.gz: 7b4a3e8b2118dfb0788f15579e61ca35b1e32277cd571fb53e83c2905e23cc49
 SHA512:
-  metadata.gz: ef0954dca71dbdeacd8588256939faa6a18b16ff85d1b913980c23e5058c54ceaf946959de3bbb0b9f421b5b5b3f57dea5d4d001295d6e2ad17fbfeda688771d
-  data.tar.gz: cd3117ad1717f98fbe96d823920a25742aca1a3f10948f60ae47f9567a31c7e55633d7b2dc3ee8d151cb60e7416bd9cdb840211e8e81cd44d63ced15b199bdc1
+  metadata.gz: 27cc273db8893f605a6d3480305a0e575f214a4c88562a701b0ba1b00b4a98b004735f7f776428b246722c0a26706ba2681405028f0454658085cf562e94fd7b
+  data.tar.gz: 01b82838cf8c8e02432fe038086fa3a96db7ff83a128e5e3ac1aacc5524e2e9a76c908f0af72e85eac19bbed6ccc0972718ba9f49e69ab5d81775fc508a946e6

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,21 @@ class User < ActiveRecord::Base
 end
 ```
 
+Now one of the saving mechanisms can be used:
+- [`handle_constraints`](#handle_constraints)
+- [`save`](#save)
+- [`save!`](#save!)
+
 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 +68,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 +80,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 +92,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 +105,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 +116,36 @@ 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.
+
 ## 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.4.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.rb

@@ -29,12 +29,24 @@ 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
 
   # @param klass [Module]
@@ -56,6 +68,19 @@ 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)
     raise ArgumentError, "Block required" if block.nil?
 
@@ -71,6 +96,7 @@ module Iry
 
     is_handled = handler.handle(err, model)
 
+    # This constraint is not handled by Iry and should raise normally
     if !is_handled
       raise
     end
@@ -96,12 +122,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 +139,6 @@ module Iry
       return true
     end
 
-    raise RecordInvalid.new(model)
+    raise ConstraintViolation.new(model)
   end
 end

data/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "iry",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "iry",
-      "version": "0.3.0",
+      "version": "0.4.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.4.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iry
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Francesco Belladonna