auto_increment 1.6.2 → 1.7.1

data/README.md

@@ -1,66 +1,286 @@
 # auto_increment
 
-[![CircleCI](https://dl.circleci.com/status-badge/img/gh/felipediesel/auto_increment/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/felipediesel/auto_increment/tree/master)
-[![Code Climate](https://codeclimate.com/github/felipediesel/auto_increment/badges/gpa.svg)](https://codeclimate.com/github/felipediesel/auto_increment)
+![CI status](https://github.com/felipediesel/auto_increment/actions/workflows/ci.yml/badge.svg?branch=main)
 
-auto_increment provides automatic incrementation for a integer or string fields in Rails.
+[![Maintainability](https://qlty.sh/gh/felipediesel/projects/auto_increment/maintainability.svg)](https://qlty.sh/gh/felipediesel/projects/auto_increment)
 
-## Installation
+`auto_increment` automatically generates sequential values for Active Record attributes.
+
+Common use cases:
+
+- Invoice numbers (`1`, `2`, `3`)
+- Customer numbers (`1000`, `1001`, `1002`)
+- Per-account sequences
+- Letter sequences (`A`, `B`, ..., `Z`, `AA`, `AB`)
+
+## Quick Start
+
+Without the gem:
+
+```rb
+class Invoice < ApplicationRecord
+  before_create :set_number
+
+  private
+
+  def set_number
+    self.number = Invoice.maximum(:number).to_i + 1
+  end
+end
+```
+
+With `auto_increment`:
+
+```rb
+class Invoice < ApplicationRecord
+  auto_increment :number
+end
+```
 
-You can use auto_increment as a gem from Rails 4.2 to Rails 6.1.
+```rb
+Invoice.create!.number #=> 1
+Invoice.create!.number #=> 2
+Invoice.create!.number #=> 3
+```
+
+## Installation
 
-To use the gem version, put the following gem requirement in your `Gemfile`:
+Add the gem to your Gemfile:
 
 ```rb
 gem "auto_increment"
 ```
 
+Then run:
+
+```sh
+bundle install
+```
+
 ## Usage
 
-To work with a auto increment column you used to do something like this in your model:
+The target column must exist in your database.
 
 ```rb
-before_create :set_code
-def set_code
-  max_code = Operation.maximum(:code)
-  self.code = max_code.to_i + 1
+class Invoice < ApplicationRecord
+  auto_increment :number
 end
 ```
 
-Looks fine, but not when you need to do it over and over again. In fact auto_increment does it under the cover.
+### Integer Sequences
 
-All you need to do is this:
+```rb
+class Invoice < ApplicationRecord
+  auto_increment :number
+end
+```
+
+Generated values:
+
+```text
+1
+2
+3
+4
+...
+```
+
+### Custom Starting Value
+
+```rb
+class Invoice < ApplicationRecord
+  auto_increment :number, initial: 1000
+end
+```
+
+Generated values:
+
+```text
+1000
+1001
+1002
+...
+```
+
+### String Sequences
+
+```rb
+class User < ApplicationRecord
+  auto_increment :code, initial: "A"
+end
+```
+
+Generated values:
+
+```text
+A
+B
+C
+...
+Z
+AA
+AB
+...
+```
+
+String sequences follow Ruby's [`String#next`](https://ruby-doc.org/3.4/String.html#method-i-next) logic. The column type is inferred from the database schema.
+
+> **Deprecation**: Explicitly passing an initial value whose type differs from the database column type is deprecated. For example, `auto_increment :ref, initial: 1` on a `string` column will emit a warning. When `initial` is not set, the default is automatically inferred from the column type (`"1"` for string columns, `1` for integer columns).
+
+### Scoped Sequences
+
+Generate independent sequences within a scope:
+
+```rb
+class Invoice < ApplicationRecord
+  auto_increment :number, scope: :account_id
+end
+```
+
+Result:
+
+```text
+Account 1: 1, 2, 3
+Account 2: 1, 2, 3
+```
+
+Multiple scopes are also supported:
+
+```rb
+class Invoice < ApplicationRecord
+  auto_increment :number,
+    scope: [:account_id, :year]
+end
+```
+
+Result:
+
+```text
+Account 1, 2026: 1, 2, 3
+Account 1, 2027: 1, 2, 3
+Account 2, 2026: 1, 2, 3
+```
+
+### Using Model Scopes
+
+`model_scope` applies one or more Active Record scopes before calculating the maximum value.
+
+This is useful when:
+
+- Bypassing a `default_scope`
+- Including archived records
+- Restricting the sequence to a subset of records
+
+```rb
+class User < ApplicationRecord
+  default_scope -> { where(active: true) }
+
+  scope :unscoped_all, -> { unscoped }
+
+  auto_increment :code,
+    scope: :account_id,
+    model_scope: :unscoped_all
+end
+```
+
+In this example, the sequence is calculated using all records, including inactive ones.
+
+### Callback Timing
+
+By default, values are assigned during `before_create`.
 
 ```rb
 auto_increment :code
 ```
 
-And your code field will be incremented
+You can change when the value is generated:
 
-## Customizing
+| Option        | Callback            |
+| ------------- | ------------------- |
+| `:create`     | `before_create`     |
+| `:save`       | `before_save`       |
+| `:validation` | `before_validation` |
 
-So you have a different column or need a scope. auto_increment provides options. You can use it like this:
+Example:
 
 ```rb
-auto_increment :letter, scope: [:account_id, :job_id], model_scope: :in_account, initial: 'C', force: true, lock: false, before: :create
+class Account < ApplicationRecord
+  auto_increment :code, before: :validation
+
+  validates :code, presence: true
+end
 ```
 
-First argument is the column that will be incremented. Can be integer or string.
+### Overwriting Existing Values
+
+By default, manually assigned nonblank values are preserved. Blank values (as defined by Active Support, including `nil`, `false`, `0`, and `""`) are treated as unset and will be generated.
+
+```rb
+invoice.number = 500
+invoice.save
+```
+
+To always generate a new value:
+
+```rb
+auto_increment :number, force: true
+```
+
+### Concurrency
+
+To request a database row lock while calculating the next value, enable locking:
+
+```rb
+auto_increment :number, lock: true
+```
+
+The lock is applied to the query used to find the current maximum. Its behavior depends on the database adapter and query; this option does not guarantee unique values under concurrent inserts. Add a unique database index on the generated column (or on the generated column together with its scope columns) to enforce uniqueness.
+
+## Options
+
+```rb
+auto_increment :number,
+  scope: [:account_id, :year],
+  model_scope: :unscoped_all,
+  initial: 1000,
+  force: true,
+  lock: true,
+  before: :validation
+```
+
+| Option        | Description                                                        | Default   |
+| ------------- | ------------------------------------------------------------------ | --------- |
+| `column`      | Column to increment. Can be integer or string.                     | `:code`   |
+| `initial`     | Starting value. Should match the database column type (`Integer` for integer columns, `String` for string columns); a mismatch is deprecated. When omitted, inferred from the column type. | `1` or `"1"` (inferred) |
+| `scope`       | Restricts the sequence to matching column values.                  | `nil`     |
+| `model_scope` | Applies Active Record scopes before calculating the maximum value. | `nil`     |
+| `force`       | Overwrites an already assigned value.                              | `false`   |
+| `lock`        | Enables locking when calculating the next value.                   | `false`   |
+| `before`      | Callback timing (`:create`, `:save`, `:validation`).               | `:create` |
+
+## How It Works
+
+When a record is created, `auto_increment`:
+
+1. Builds a query for the target column.
+2. Applies any configured scopes.
+3. Applies any configured model scopes.
+4. Finds the current maximum value.
+5. Calculates the next value.
+6. Assigns the value during the configured callback.
 
-- scope: you can define columns that will be scoped and you can use as many as you want (default: nil)
-- model_scope: you can define model scopes that will be executed and you can use as many as you want (default: nil)
-- initial: initial value of column (default: 1)
-- force: you can set a value before create and auto_increment will not change that, but if you do want this, set force to true (default: false)
-- lock: you can set a lock on the max query. (default: false)
-- before: you can choose a different callback to be used (:create, :save, :validation) (default: create)
+The generated value is stored in a normal database column and can be queried, indexed, and validated like any other attribute.
 
 ## Compatibility
 
-Tested with Rails 6.1, 6 in Ruby 2.7.7.
-Tested with Rails 7.1, 7, 6.1, 6 in Ruby 3.2.2.
+| Ruby | Rails              |
+| ---- | ------------------ |
+| 3.3  | 7.1, 7.2           |
+| 3.4  | 7.1, 7.2, 8.0, 8.1 |
+| 4.0  | 7.2, 8.0, 8.1      |
 
-For older versions, use version 1.5.2.
+This release supports Rails 7.1 and newer. The older 1.6.2 release supports Rails 6.1 and 7.0; for earlier Rails versions, see the [changelog](CHANGELOG.md) for the releases that added support.
 
 ## License
 
-[MIT License](LICENSE.txt)
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'rspec/core/rake_task'
-require 'bundler/gem_tasks'
+require "rspec/core/rake_task"
+require "bundler/gem_tasks"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/auto_increment.gemspec

@@ -1,37 +1,25 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.push File.expand_path('lib', __dir__)
-require 'auto_increment/version'
+$LOAD_PATH.push File.expand_path("lib", __dir__)
+require "auto_increment/version"
 
 Gem::Specification.new do |s|
-  s.name        = 'auto_increment'
-  s.version     = AutoIncrement::VERSION.dup
-  s.licenses    = 'MIT'
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ['Felipe Diesel']
-  s.email       = ['diesel@hey.com']
-  s.homepage    = 'http://github.com/felipediesel/auto_increment'
-  s.summary     = 'Auto increment a string or integer column'
-  s.description = 'Automaticaly increments an ActiveRecord column'
+  s.name = "auto_increment"
+  s.version = AutoIncrement::VERSION.dup
+  s.licenses = "MIT"
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Felipe Diesel"]
+  s.email = ["felipediesel@gmail.com"]
+  s.homepage = "https://github.com/felipediesel/auto_increment"
+  s.summary = "Auto increment a string or integer column"
+  s.description = "Automatically generates sequential values for string or integer Active Record columns."
+  s.metadata["source_code_uri"] = "https://github.com/felipediesel/auto_increment"
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.require_paths = ['lib']
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
 
-  s.add_dependency 'activerecord', '>= 6.0'
-  s.add_dependency 'activesupport', '>= 6.0'
+  s.add_dependency "activerecord", ">= 7.1"
+  s.add_dependency "activesupport", ">= 7.1"
 
-  s.add_development_dependency 'bundler'
-  s.add_development_dependency 'rake'
-
-  s.add_development_dependency 'appraisal'
-  s.add_development_dependency 'database_cleaner'
-  s.add_development_dependency 'fuubar'
-  s.add_development_dependency 'guard'
-  s.add_development_dependency 'guard-rspec'
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'rspec-nc'
-  s.add_development_dependency 'rubocop'
-
-  s.add_development_dependency 'sqlite3', '>= 1.3.13'
+  s.metadata["rubygems_mfa_required"] = "true"
 end

data/gemfiles/rails_7_1.gemfile

@@ -2,7 +2,19 @@
 
 source "https://rubygems.org"
 
-gem "activerecord", "7.1.2"
-gem "activesupport", "7.1.2"
+gem "activerecord", "7.1.6"
+gem "activesupport", "7.1.6"
+
+group :development do
+  gem "appraisal"
+  gem "database_cleaner"
+  gem "fuubar"
+  gem "guard"
+  gem "guard-rspec"
+  gem "rake"
+  gem "rspec"
+  gem "sqlite3", "~> 2.10.2"
+  gem "standard"
+end
 
 gemspec path: "../"

data/gemfiles/rails_7_1.gemfile.lock

@@ -1,56 +1,62 @@
 PATH
   remote: ..
   specs:
-    auto_increment (1.5.2)
-      activerecord (>= 6.0)
-      activesupport (>= 6.0)
+    auto_increment (1.7.1)
+      activerecord (>= 7.1)
+      activesupport (>= 7.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.1.2)
-      activesupport (= 7.1.2)
-    activerecord (7.1.2)
-      activemodel (= 7.1.2)
-      activesupport (= 7.1.2)
+    activemodel (7.1.6)
+      activesupport (= 7.1.6)
+    activerecord (7.1.6)
+      activemodel (= 7.1.6)
+      activesupport (= 7.1.6)
       timeout (>= 0.4.0)
-    activesupport (7.1.2)
+    activesupport (7.1.6)
       base64
+      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
       minitest (>= 5.1)
       mutex_m
+      securerandom (>= 0.3)
       tzinfo (~> 2.0)
     appraisal (2.5.0)
       bundler
       rake
       thor (>= 0.14.0)
-    ast (2.4.2)
-    base64 (0.2.0)
-    bigdecimal (3.1.5)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (4.1.2)
     coderay (1.1.3)
-    concurrent-ruby (1.2.2)
-    connection_pool (2.4.1)
-    database_cleaner (2.0.2)
+    concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
+    database_cleaner (2.1.0)
       database_cleaner-active_record (>= 2, < 3)
-    database_cleaner-active_record (2.1.0)
+    database_cleaner-active_record (2.2.2)
       activerecord (>= 5.a)
-      database_cleaner-core (~> 2.0.0)
-    database_cleaner-core (2.0.1)
-    diff-lcs (1.5.0)
-    drb (2.2.0)
-      ruby2_keywords
-    ffi (1.16.3)
-    formatador (1.1.0)
+      database_cleaner-core (~> 2.0)
+    database_cleaner-core (2.1.0)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    formatador (1.2.3)
+      reline
     fuubar (2.5.1)
       rspec-core (~> 3.0)
       ruby-progressbar (~> 1.4)
-    guard (2.18.1)
+    guard (2.20.2)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
+      logger (~> 1.6)
       lumberjack (>= 1.0.12, < 2.0)
       nenv (~> 0.1)
       notiffany (~> 0.0)
@@ -62,94 +68,118 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.14.1)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
-    json (2.7.1)
-    language_server-protocol (3.17.0.3)
-    listen (3.8.0)
+    io-console (0.9.5)
+    json (3.1.0)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    listen (3.10.1)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    lumberjack (1.2.10)
-    method_source (1.0.0)
-    minitest (5.20.0)
-    mutex_m (0.2.0)
+    logger (1.7.0)
+    lumberjack (1.4.2)
+    method_source (1.1.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    mutex_m (0.3.0)
     nenv (0.3.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    parallel (1.24.0)
-    parser (3.2.2.4)
+    parallel (2.3.0)
+    parser (3.3.13.0)
       ast (~> 2.4.1)
       racc
-    pry (0.14.2)
+    prism (1.9.0)
+    pry (0.16.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    racc (1.7.3)
+      reline (>= 0.6.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
+    rake (13.4.2)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    regexp_parser (2.8.3)
-    rexml (3.2.6)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.3)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.7)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.6)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.6)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.9)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-nc (0.3.0)
-      rspec (>= 3)
-      terminal-notifier (>= 1.4)
-    rspec-support (3.12.1)
-    rubocop (1.59.0)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
-      parser (>= 3.2.2.4)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.8)
+    rubocop (1.91.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.51.0)
+      parser (>= 3.3.7.2)
+      prism (>= 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    ruby2_keywords (0.0.5)
+    securerandom (0.4.1)
     shellany (0.0.1)
-    sqlite3 (1.4.2)
-    terminal-notifier (2.0.0)
-    thor (1.3.0)
-    timeout (0.4.1)
+    sqlite3 (2.10.2-arm64-darwin)
+    sqlite3 (2.10.2-x86_64-linux-gnu)
+    standard (1.57.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.91.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    thor (1.5.0)
+    timeout (0.6.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.5.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
 
 PLATFORMS
-  arm64-darwin-23
+  arm64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
-  activerecord (= 7.1.2)
-  activesupport (= 7.1.2)
+  activerecord (= 7.1.6)
+  activesupport (= 7.1.6)
   appraisal
   auto_increment!
-  bundler
   database_cleaner
   fuubar
   guard
   guard-rspec
   rake
   rspec
-  rspec-nc
-  rubocop
-  sqlite3 (>= 1.3.13)
+  sqlite3 (~> 2.10.2)
+  standard
 
 BUNDLED WITH
    2.4.22

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,20 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "7.2.3.1"
+gem "activesupport", "7.2.3.1"
+
+group :development do
+  gem "appraisal"
+  gem "database_cleaner"
+  gem "fuubar"
+  gem "guard"
+  gem "guard-rspec"
+  gem "rake"
+  gem "rspec"
+  gem "sqlite3", "~> 2.10.2"
+  gem "standard"
+end
+
+gemspec path: "../"