activerecord-scoped_sequence 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f4343e352f4a5cc1b9d051f5d7c9a70b2002d0a2fcc370d4c1279c2c940cf27
+  data.tar.gz: 71978321b77654636cf975ce5a8d02af28423657f5de455e7c3f14ba6546fb5b
+SHA512:
+  metadata.gz: 1698c8de3e04185ee467e6c405cfd2aebce1e1f890f0f0f9f3ce3d7eab4ce3a5baaada28f7e38bea9229b60ec3ff43c8d327554bbf4b6d42dbfbaa8714db1130
+  data.tar.gz: e38cc4f43975d0f99224bdcf09097c52ddec74ce415197e25b4b05b7af018b6f1b5b4c17178ac8985249f340c3a62986cec231a650592778547bb35b808952a1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 activerecord-scoped_sequence contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Active Record Scoped Sequence
+
+`activerecord-scoped_sequence` assigns increasing integer values within the
+scope of a `belongs_to` association. It serializes allocation by locking the
+associated row, so concurrent inserts for one scope cannot receive the same
+generated value.
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem "activerecord-scoped_sequence"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+Add the sequence column and an index covering its scope:
+
+```ruby
+add_column :invoices, :number, :bigint
+add_index :invoices, [:organization_id, :number], unique: true
+```
+
+Declare the sequence on the model:
+
+```ruby
+class Invoice < ApplicationRecord
+  belongs_to :organization
+
+  scoped_sequence :number, scope: :organization
+end
+```
+
+The organization is locked while the next number is assigned by querying the
+maximum invoice number currently persisted for it and adding one. An explicitly
+supplied number is preserved.
+
+## Concurrency and indexes
+
+The lock is acquired in `before_create`, inside Active Record's implicit save
+transaction. Database row locks live until that transaction commits or rolls
+back, so the lock remains held through the insert even after the callback
+returns.
+
+Every writer must use callbacks for allocation. Bulk APIs such as `insert_all`
+bypass the macro. A composite unique index remains strongly recommended as a
+database invariant; it is defensive and is not used as a retry mechanism.
+
+The gem currently supports non-polymorphic `belongs_to` associations with
+single-column keys.

data/lib/active_record/scoped_sequence/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ScopedSequence
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_record/scoped_sequence.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_record/scoped_sequence/version"
+
+module ActiveRecord
+  module ScopedSequence
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :scoped_sequence_definitions, instance_writer: false, default: {}.freeze
+    end
+
+    class_methods do
+      # Defines an integer sequence on +attribute+ scoped to a +belongs_to+
+      # association. The associated row is locked through the record insert.
+      #
+      # The next value is one greater than the maximum value currently persisted
+      # in the scope.
+      def scoped_sequence(attribute, scope:)
+        attribute = attribute.to_s
+        scope = scope.to_sym
+
+        self.scoped_sequence_definitions = scoped_sequence_definitions.merge(
+          attribute => { scope: scope }.freeze
+        ).freeze
+
+        before_create do
+          assign_scoped_sequence(attribute, scope)
+        end
+      end
+    end
+
+    private
+      def assign_scoped_sequence(attribute, scope)
+        reflection = self.class.reflect_on_association(scope)
+
+        unless reflection&.belongs_to?
+          raise ArgumentError, "Scoped sequence scope #{scope.inspect} must name a belongs_to association"
+        end
+        if reflection.polymorphic?
+          raise ArgumentError, "Scoped sequences do not support polymorphic associations"
+        end
+        if reflection.foreign_key.is_a?(Array) || reflection.association_primary_key.is_a?(Array)
+          raise ArgumentError, "Scoped sequences do not support composite association keys"
+        end
+
+        foreign_key = reflection.foreign_key
+        scope_id = _read_attribute(foreign_key)
+        raise ArgumentError, "Scoped sequence association #{scope.inspect} must be persisted" if scope_id.nil?
+
+        primary_key = reflection.association_primary_key
+        reflection.klass.unscoped.where(primary_key => scope_id).lock.take!
+
+        if _read_attribute(attribute).nil?
+          relation = self.class.unscoped.where(foreign_key => scope_id)
+          _write_attribute(attribute, relation.maximum(attribute).to_i + 1)
+        end
+      end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include ActiveRecord::ScopedSequence
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-scoped_sequence
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Auto increments an integer column on a model, scoped to an association.
+  Example: sequential invoice_number column for invoices, scoped to a company (each
+  company has their own invoice 1, invoice 2, etc).'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/active_record/scoped_sequence.rb
+- lib/active_record/scoped_sequence/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Association-scoped integer sequences for Active Record
+test_files: []