concerns_on_rails 1.9.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01db047d91e470c1c2bb03f6fbe95be1eea7592199d9a548b6ac5dbacc84452
-  data.tar.gz: f47e6149addbee52badc7ae4d56fbc66c636adc75d5a32f7742a57d18eda1cd8
+  metadata.gz: a34c6e186b582806890012bb0f8bf049c1fd0f56f74007af7669cdb5ae713eb2
+  data.tar.gz: 298f957409be23ecfd9bbd0de46161ac56af7a01a6a300d29cf3bff9ca2b94d3
 SHA512:
-  metadata.gz: 1a856b89dd65fc126612d33aa276cfe49949484594a6d9c1cca2af01e91474883b1eb170e3f36647a125375ed645914cff6a1564cac3f955e2d7066a7c3c0e37
-  data.tar.gz: 2056b850ffddb607084f672018498b4f366a0ab7c0f97bf22e806355031eae146c256f2f62c4bc3ef5e769ee75a3bd05d2bfc56864a5994ea9b204a1a9b730ab
+  metadata.gz: 6a96e094791d487cd9a534e4263de4bd902af9b533a8607ceb20906d4b38827c82ee0b370cb885d8a5800aef8a03a9b84cc718dc00074da1c0b1f35ade4fc2b3
+  data.tar.gz: e803d31da5694c6ad1a0ea28d928f9d552e75ded84420aa94cb816538e4cbe9b4a228f2b9dfa9428a8091b369444909d750523d2c5a0e9edae1f2df6fec95a78

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 <!-- CHANGELOG.md -->
 
+## 1.10.0 (2026-06-03)
+
+### Added
+- **Models::Addressable**: Declarative postal-address normalization + format validation via a single `addressable_by` macro. Maps the canonical parts (`line1` / `line2` / `city` / `state` / `postal_code` / `country`) onto real columns — any subset works, missing columns are skipped, and required parts are schema-checked. Normalizes in `before_validation` (strip + squish, postal-code upcasing with canonical CA spacing, 2-letter country/state codes upcased) and validates required-part presence, ISO 3166-1 alpha-2 country codes, per-country postal formats (US/CA/GB/AU/DE/FR + a permissive fallback), and opt-in US/CA state codes. Offline and dependency-free; layer real deliverability checks via the opt-in `verify_with:` callable. Adds helpers `full_address`, `address_lines`, `address_present?`, `address_complete?`, and `address_attributes`.
+
+### Internal
+- Added `ConcernsOnRails::Support::AddressData` — ISO 3166-1 alpha-2 country codes, per-country postal-format patterns, US state / CA province sets, and the case-insensitive lookups (`valid_country?`, `postal_format_for`, `valid_state?`, `normalize_postal`) backing the Addressable concern.
+
 ## 1.9.0 (2026-05-25)
 
 ### Added

data/README.md

@@ -2,7 +2,7 @@
 
 > 🇻🇳 **Hoàng Sa and Trường Sa belong to Việt Nam.**
 
-A plug-and-play collection of reusable ActiveSupport concerns for Rails **models** and **controllers** — slugs, soft delete, scheduled publish, expiry, pagination, filtering, JSON envelopes, and more. One `include`, one declarative macro, done.
+A plug-and-play collection of reusable ActiveSupport concerns for Rails **models** and **controllers** — slugs, soft delete, scheduled publish, expiry, sequential reference numbers, pagination, filtering, JSON envelopes, and more. One `include`, one declarative macro, done.
 
 ```ruby
 class Article < ApplicationRecord
@@ -36,7 +36,9 @@ Article.published.without_deleted.find("hello-world")
   - [Searchable](#-searchable) — LIKE/ILIKE search across configured columns
   - [Activatable](#-activatable) — boolean active/inactive toggle
   - [Tokenizable](#-tokenizable) — security tokens with timing-safe lookup
+  - [Sequenceable](#-sequenceable) — ordered, human-friendly reference numbers
   - [Stateable](#-stateable) — lightweight string-backed state machine
+  - [Addressable](#-addressable) — postal address normalization + format validation
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -53,7 +55,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Twelve model concerns + six controller concerns**, all production-ready
+- **Fourteen model concerns + six controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -66,7 +68,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.9"
+gem "concerns_on_rails", "~> 1.11"
 ```
 
 Or pull the latest from GitHub:
@@ -577,6 +579,70 @@ User.authenticate_by_api_token(token)     # timing-safe; returns user or nil
 
 ---
 
+## 🧾 Sequenceable
+
+Ordered, human-friendly reference numbers — invoice numbers, order numbers, ticket IDs, support cases. Unlike the *random* identifiers from [Hashable](#-hashable) / [Tokenizable](#-tokenizable), `Sequenceable` produces *sequential* ones backed by an integer column that is the source of truth.
+
+```ruby
+class Invoice < ApplicationRecord
+  include ConcernsOnRails::Sequenceable
+
+  sequenceable_by :sequence,        # integer column — the source of truth
+    into:    :number,               # optional string column for the formatted value
+    prefix:  "INV-",
+    padding: 5,
+    scope:   :account_id,           # one independent counter per account
+    reset:   :year                  # restart numbering each calendar year
+end
+
+invoice = Invoice.create!(account_id: 1)
+invoice.sequence            # => 1, 2, 3 ... (per account, per year)
+invoice.number              # => "INV-2026-00001"
+invoice.formatted_sequence  # => "INV-2026-00001"
+
+Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without creating)
+```
+
+**Options**
+
+| Option               | Default     | Purpose                                                                                  |
+|----------------------|-------------|------------------------------------------------------------------------------------------|
+| `field` (positional) | `:sequence` | Integer column holding the sequence — the source of truth.                               |
+| `into:`              | `nil`       | String column to persist the formatted reference into (immutable display value).          |
+| `prefix:`            | `""`        | Prepended to the formatted value.                                                        |
+| `padding:`           | `0`         | Zero-pad width of the numeric portion (`0` = no padding).                                |
+| `separator:`         | `"-"`       | Joins prefix / period token / number in the default format.                              |
+| `start_at:`          | `1`         | First value when the scope/period has no rows yet.                                       |
+| `scope:`             | `nil`       | Column (or array of columns) the counter is scoped to — e.g. one sequence per `account_id`. |
+| `reset:`             | `:never`    | `:never` / `:year` / `:month` / `:day` — restart numbering each period (needs `created_at`). |
+| `template:`          | `nil`       | `->(seq, record) { ... }` full custom formatter; overrides `prefix` / `padding` / period. |
+
+**Default format**
+
+| `reset:`  | Example               | Shape                            |
+|-----------|-----------------------|----------------------------------|
+| `:never`  | `INV-00001`           | `prefix + padded`                |
+| `:year`   | `INV-2026-00001`      | `prefix + YYYY + sep + padded`   |
+| `:month`  | `INV-202606-00001`    | `prefix + YYYYMM + sep + padded` |
+| `:day`    | `INV-20260604-00001`  | `prefix + YYYYMMDD + sep + padded` |
+
+**Generated API**
+
+| Method                            | What it does                                                                          |
+|-----------------------------------|---------------------------------------------------------------------------------------|
+| `formatted_<field>`               | The formatted string — the persisted `into:` value when set, otherwise computed.      |
+| `Model.next_<field>(scope_attrs)` | Peek the next integer for a scope without creating a record.                           |
+
+**Notes**
+- The next value is `MAX(<field>) + 1` within the scope (and period), so numbering is dense and ordered — not random.
+- Caller-supplied values are respected: `Invoice.create!(sequence: 100)` is not overwritten (and its `into:` string is still formatted from `100`).
+- Generation reads `MAX` then inserts, so two concurrent inserts can race. It's **best-effort** — add a **scoped unique index** on `<field>` (and on `into:`) for a real guarantee, the same way you would for any `MAX`-based numbering.
+- `reset:` requires a `created_at` column; the period is taken from each row's creation time.
+- For fixed-width display (`00042`), make the `into:` column a **string** — integer columns drop leading zeros.
+- Distinct from `Hashable` / `Tokenizable`, which generate *random* values; reach for those when the identifier must be unguessable.
+
+---
+
 ## 🔄 Stateable
 
 Lightweight string-backed state machine — the 80% of AASM without the dependency.
@@ -630,6 +696,77 @@ stateable_by :state, states: %i[open closed], prefix: true
 
 ---
 
+## 🏠 Addressable
+
+Normalize and format-validate a postal address spread across several columns — one macro for whitespace cleanup, postal-code and ISO country-code checks, required-part presence, and a `full_address` helper. No external geocoding service required.
+
+```ruby
+class Location < ApplicationRecord
+  include ConcernsOnRails::Addressable
+
+  addressable_by   # standard columns: line1, line2, city, state, postal_code, country
+end
+
+loc = Location.create(line1: "  1 Infinite  Loop ", city: "Cupertino",
+                      state: "ca", postal_code: "95014", country: "us")
+loc.line1         # => "1 Infinite Loop"   (stripped + squished)
+loc.state         # => "CA"                (2-letter code upcased)
+loc.country       # => "US"
+loc.full_address  # => "1 Infinite Loop, Cupertino, CA, 95014, US"
+```
+
+Map onto your own column names and tune behavior:
+
+```ruby
+class Place < ApplicationRecord
+  include ConcernsOnRails::Addressable
+
+  addressable_by line1: :street, postal_code: :zip, country: :country_code,
+                 required:        %i[line1 city postal_code country],
+                 default_country: "GB",                       # country used when the record has none
+                 validate_state:  true,                       # opt-in US/CA state-code check
+                 verify_with:     ->(rec) { Usps.verify(rec) } # opt-in external verifier
+end
+```
+
+**Options**
+
+| Option            | Default                              | Purpose                                                              |
+|-------------------|--------------------------------------|---------------------------------------------------------------------|
+| `line1:` … `country:` | same-named columns               | Map each canonical part to a real column. Missing columns are skipped. |
+| `required:`       | `%i[line1 city postal_code country]` | Parts (by canonical name) that must be present. Each must map to an existing column. |
+| `default_country:`| `"US"`                               | Country used to pick the postal-code format when the record has no recognized country. |
+| `validate_state:` | `false`                              | When `true`, validates the state against US / CA code sets.         |
+| `verify_with:`    | `nil`                                | A callable for real-world verification (see below).                 |
+
+**What it normalizes** (in `before_validation`)
+- Text parts: `strip` + `squish`.
+- `postal_code`: squish + upcase, with canonical spacing for CA (`A1A1A1` → `A1A 1A1`).
+- `country` / `state`: upcased when they look like a 2-letter code (full names left alone).
+
+**What it validates**
+- Presence of every `required:` part.
+- `country`: a 2-letter value must be a real ISO 3166-1 alpha-2 code.
+- `postal_code`: matched against a per-country pattern (US, CA, GB, AU, DE, FR) with a permissive fallback for everything else.
+- `state`: only when `validate_state: true` and the country is US/CA.
+
+**External verification (`verify_with:`)** — runs **only after** structural validation passes, so you never spend an API call on an obviously-broken address. The callable receives the record and may either add to `record.errors` itself, or return:
+
+| Return value      | Effect                                          |
+|-------------------|-------------------------------------------------|
+| `true` / `nil`    | success                                         |
+| `false`           | adds a generic `:base` error                    |
+| `String`          | added as a `:base` error                        |
+| `Array`           | each element added as a `:base` error           |
+
+**Notes**
+- Scope is **format/structure only** — it checks shape, not real-world deliverability. Plug a USPS/Google/Smarty client into `verify_with:` for that.
+- Error messages are plain English strings — no host-app i18n setup required.
+- Partial schemas just work: a model without a `line2` (or any other) column simply omits that part.
+- Pairs with [Normalizable](#-normalizable) when you also have non-address fields to clean up.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -884,7 +1021,7 @@ Both forms reference the same module, so you can freely mix them.
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.9.0.gem       # install locally
+gem install ./concerns_on_rails-1.11.0.gem      # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -14,4 +14,6 @@ module ConcernsOnRails
   Activatable   = Models::Activatable
   Tokenizable   = Models::Tokenizable
   Stateable     = Models::Stateable
+  Addressable   = Models::Addressable
+  Sequenceable  = Models::Sequenceable
 end

data/lib/concerns_on_rails/models/addressable.rb

@@ -0,0 +1,212 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Declarative normalization + format validation for a postal address spread
+    # across several columns. One macro wires up whitespace cleanup, postal-code
+    # and ISO country-code checks, required-part presence, and a `full_address`
+    # helper — no external geocoding service required.
+    #
+    #   class Location < ApplicationRecord
+    #     include ConcernsOnRails::Addressable
+    #
+    #     addressable_by                      # standard line1/line2/city/state/postal_code/country columns
+    #     # addressable_by line1: :street, postal_code: :zip, country: :country_code,
+    #     #                required: %i[line1 city postal_code], default_country: "GB",
+    #     #                validate_state: true, verify_with: ->(rec) { Usps.verify(rec) }
+    #   end
+    #
+    # Scope is *format/structure* only — it checks shape, not real-world
+    # deliverability. Layer a real verifier on via `verify_with:`. Relates to
+    # the per-field Normalizable concern.
+    module Addressable
+      extend ActiveSupport::Concern
+
+      # Canonical address part => default column name.
+      DEFAULT_FIELDS = {
+        line1: :line1, line2: :line2, city: :city,
+        state: :state, postal_code: :postal_code, country: :country
+      }.freeze
+
+      # Parts required by default (each must map to an existing column).
+      DEFAULT_REQUIRED = %i[line1 city postal_code country].freeze
+
+      included do
+        class_attribute :addressable_fields, instance_accessor: false, default: {}
+        class_attribute :addressable_required, instance_accessor: false, default: [].freeze
+        class_attribute :addressable_default_country, instance_accessor: false, default: "US"
+        class_attribute :addressable_validate_state, instance_accessor: false, default: false
+        class_attribute :addressable_verifier, instance_accessor: false, default: nil
+
+        before_validation :normalize_address
+        validate :validate_address
+      end
+
+      # Defined as a real module (not `class_methods do`) so the public macro and
+      # its private helpers share one `private` and aren't constrained by
+      # Metrics/BlockLength. ActiveSupport::Concern auto-extends `ClassMethods`.
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the address. Column overrides are passed as `part: :column`
+        # keyword pairs; everything else tunes behavior. See the module docs.
+        def addressable_by(required: DEFAULT_REQUIRED, default_country: "US",
+                           validate_state: false, verify_with: nil, **mapping)
+          self.addressable_fields = resolve_addressable_fields(mapping)
+          self.addressable_required = Array(required).map(&:to_sym)
+          self.addressable_default_country = default_country.to_s.upcase
+          self.addressable_validate_state = validate_state
+          self.addressable_verifier = verify_with
+          ensure_required_columns!
+        end
+
+        private
+
+        def resolve_addressable_fields(mapping)
+          unknown = mapping.keys.map(&:to_sym) - DEFAULT_FIELDS.keys
+          raise ArgumentError, "ConcernsOnRails::Models::Addressable: unknown address part(s): #{unknown.join(', ')}" if unknown.any?
+
+          overrides = mapping.to_h { |part, column| [part.to_sym, column.to_sym] }
+          ensure_columns!("ConcernsOnRails::Models::Addressable", overrides.values)
+          DEFAULT_FIELDS.merge(overrides).select { |_part, column| column_names.include?(column.to_s) }
+        end
+
+        def ensure_required_columns!
+          missing = addressable_required.reject { |part| addressable_fields.key?(part) }
+          return if missing.empty?
+
+          raise ArgumentError,
+                "ConcernsOnRails::Models::Addressable: required address part(s) #{missing.join(', ')} " \
+                "have no matching column (table: #{table_name})"
+        end
+      end
+
+      # --- Normalization (before_validation) ------------------------------------
+
+      def normalize_address
+        country = resolved_country
+        self.class.addressable_fields.each do |part, column|
+          value = self[column]
+          next unless value.is_a?(String)
+
+          self[column] = normalize_part(part, country, value)
+        end
+      end
+
+      # --- Validation -----------------------------------------------------------
+
+      def validate_address
+        validate_required_parts
+        validate_country_code
+        validate_postal_code
+        validate_state_code if self.class.addressable_validate_state
+        run_address_verifier if self.class.addressable_verifier && errors.empty?
+      end
+
+      # --- Public helpers -------------------------------------------------------
+
+      # The present parts joined into a single line, in canonical order.
+      def full_address(separator: ", ")
+        address_lines.join(separator)
+      end
+
+      # The present parts as an ordered array (handy for multi-line rendering).
+      def address_lines
+        ordered_parts.filter_map { |part| self[self.class.addressable_fields[part]].presence }
+      end
+
+      # True when any configured part has a value.
+      def address_present?
+        ordered_parts.any? { |part| self[self.class.addressable_fields[part]].present? }
+      end
+
+      # True when every required part has a value (presence only, no format check).
+      def address_complete?
+        self.class.addressable_required.all? do |part|
+          (column = self.class.addressable_fields[part]) && self[column].present?
+        end
+      end
+
+      # `{ part => value }` for the present parts (handy for serializers / verifiers).
+      def address_attributes
+        self.class.addressable_fields.each_with_object({}) do |(part, column), acc|
+          value = self[column]
+          acc[part] = value if value.present?
+        end
+      end
+
+      private
+
+      def ordered_parts
+        DEFAULT_FIELDS.keys.select { |part| self.class.addressable_fields.key?(part) }
+      end
+
+      # The 2-letter country code driving postal/state checks: the record's own
+      # country when it's a recognized code, otherwise the configured default.
+      def resolved_country
+        column = self.class.addressable_fields[:country]
+        value = column && self[column]
+        return self.class.addressable_default_country unless value.is_a?(String)
+
+        code = value.strip.upcase
+        ConcernsOnRails::Support::AddressData.valid_country?(code) ? code : self.class.addressable_default_country
+      end
+
+      def normalize_part(part, country, value)
+        squished = value.strip.squish
+        case part
+        when :postal_code then ConcernsOnRails::Support::AddressData.normalize_postal(country, value)
+        when :country, :state then squished.length == 2 ? squished.upcase : squished
+        else squished
+        end
+      end
+
+      def validate_required_parts
+        fields = self.class.addressable_fields
+        self.class.addressable_required.each do |part|
+          column = fields[part]
+          errors.add(column, "can't be blank") if column && self[column].blank?
+        end
+      end
+
+      def validate_country_code
+        column = self.class.addressable_fields[:country]
+        value = column && self[column]
+        return unless value.is_a?(String) && value.length == 2
+        return if ConcernsOnRails::Support::AddressData.valid_country?(value)
+
+        errors.add(column, "is not a valid ISO 3166-1 country code")
+      end
+
+      def validate_postal_code
+        column = self.class.addressable_fields[:postal_code]
+        value = column && self[column]
+        return if value.blank?
+
+        format = ConcernsOnRails::Support::AddressData.postal_format_for(resolved_country)
+        errors.add(column, "is not a valid postal code") unless value.to_s.match?(format)
+      end
+
+      def validate_state_code
+        column = self.class.addressable_fields[:state]
+        value = column && self[column]
+        return if value.blank?
+        return if ConcernsOnRails::Support::AddressData.valid_state?(resolved_country, value)
+
+        errors.add(column, "is not a valid state/province")
+      end
+
+      def run_address_verifier
+        apply_verifier_result(self.class.addressable_verifier.call(self))
+      end
+
+      def apply_verifier_result(result)
+        case result
+        when false then errors.add(:base, "address could not be verified")
+        when String then errors.add(:base, result)
+        when Array then result.each { |message| errors.add(:base, message) }
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/sequenceable.rb

@@ -0,0 +1,135 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Generates ordered, human-friendly sequential reference numbers — invoice
+    # numbers, order numbers, ticket numbers, support cases. Unlike Hashable /
+    # Tokenizable (which produce *random* identifiers), Sequenceable produces
+    # *ordered* ones backed by an integer column that is the source of truth.
+    #
+    #   class Invoice < ApplicationRecord
+    #     include ConcernsOnRails::Sequenceable
+    #
+    #     sequenceable_by :sequence,        # integer column — source of truth
+    #       into:    :number,               # optional string column for the formatted value
+    #       prefix:  "INV-",
+    #       padding: 5,
+    #       scope:   :account_id,           # one counter per account
+    #       reset:   :year                  # restart numbering each calendar year
+    #   end
+    #
+    #   invoice = Invoice.create!(account_id: 1)
+    #   invoice.sequence            # => 1, 2, 3 ... (per account, per year)
+    #   invoice.number              # => "INV-2026-00001"
+    #   invoice.formatted_sequence  # => "INV-2026-00001"
+    #   Invoice.next_sequence(account_id: 1)  # peek the next value without creating
+    #
+    # The integer is computed as MAX(field) within the scope (+ period) + 1, so
+    # numbering is dense and ordered. Generation is best-effort under concurrency
+    # — pair the column(s) with a scoped unique DB index for a real guarantee.
+    module Sequenceable
+      extend ActiveSupport::Concern
+
+      RESET_PERIODS = %i[never year month day].freeze
+      MAX_GENERATION_ATTEMPTS = 10
+      NAME = "ConcernsOnRails::Models::Sequenceable".freeze
+
+      included do
+        class_attribute :sequenceable_config, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+        include ConcernsOnRails::Support::SequenceCalculator
+
+        # Configure a sequenceable field.
+        #
+        # Options:
+        #   into:      string column to persist the formatted value into (default nil)
+        #   prefix:    string prepended to the formatted value (default "")
+        #   padding:   zero-pad width of the numeric portion (default 0 = no padding)
+        #   separator: joins prefix / period token / number in the default format (default "-")
+        #   start_at:  first value per scope/period when no rows exist yet (default 1)
+        #   scope:     column or array of columns the counter is scoped to (default nil)
+        #   reset:     :never (default) | :year | :month | :day — restart per period (needs created_at)
+        #   template:  ->(seq, record) { ... } full custom formatter; overrides prefix/padding/period
+        def sequenceable_by(field = :sequence, into: nil, prefix: "", padding: 0,
+                            separator: "-", start_at: 1, scope: nil, reset: :never, template: nil)
+          field      = field.to_sym
+          into       = into&.to_sym
+          reset      = reset.to_sym
+          scope_cols = Array(scope).map(&:to_sym)
+
+          ensure_columns!(NAME, field)
+          ensure_columns!(NAME, into) if into
+          ensure_columns!(NAME, *scope_cols) unless scope_cols.empty?
+          ensure_columns!(NAME, :created_at) unless reset == :never
+          validate_sequenceable_options!(reset, template)
+
+          self.sequenceable_config = sequenceable_config.merge(
+            field => { into: into, prefix: prefix.to_s, padding: padding.to_i,
+                       separator: separator.to_s, start_at: start_at.to_i,
+                       scope: scope_cols, reset: reset, template: template }
+          )
+
+          before_create -> { assign_sequenceable_value(field) }
+          define_sequenceable_methods(field)
+        end
+      end
+
+      class_methods do
+        private
+
+        def define_sequenceable_methods(field)
+          define_method("formatted_#{field}") do
+            cfg = self.class.sequenceable_config.fetch(field)
+            return self[cfg[:into]] if cfg[:into] && self[cfg[:into]].present?
+            return nil if self[field].blank?
+
+            self.class.send(:format_sequence, field, self[field], self)
+          end
+
+          define_singleton_method("next_#{field}") do |scope_attrs = {}|
+            sequence_base_value(field, nil, scope_attrs)
+          end
+        end
+
+        def validate_sequenceable_options!(reset, template)
+          unless RESET_PERIODS.include?(reset)
+            raise ArgumentError, "#{NAME}: unknown reset '#{reset}'. Valid values: #{RESET_PERIODS.join(', ')}"
+          end
+
+          return if template.nil? || template.respond_to?(:call)
+
+          raise ArgumentError, "#{NAME}: template must be callable (respond to #call)"
+        end
+      end
+
+      # Assigns the sequence (and, when configured, the formatted string) only when
+      # the integer column is blank, so callers can pass an explicit value. The
+      # increment-until-free loop is a best-effort guard against pre-taken values;
+      # a scoped unique index is the real concurrency guarantee.
+      def assign_sequenceable_value(field)
+        cfg = self.class.sequenceable_config.fetch(field)
+
+        if self[field].blank?
+          candidate = self.class.send(:sequence_base_value, field, self, {})
+          attempts = 0
+          while self.class.send(:sequence_value_taken?, field, candidate, self, {})
+            attempts += 1
+            if attempts >= MAX_GENERATION_ATTEMPTS
+              raise "#{NAME}: could not find a free value for '#{field}' after " \
+                    "#{MAX_GENERATION_ATTEMPTS} attempts — add a scoped unique index"
+            end
+            candidate += 1
+          end
+          self[field] = candidate
+        end
+
+        return unless cfg[:into] && self[cfg[:into]].blank?
+
+        self[cfg[:into]] = self.class.send(:format_sequence, field, self[field], self)
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/address_data.rb

@@ -0,0 +1,102 @@
+module ConcernsOnRails
+  module Support
+    # Reference data + lookups for Models::Addressable. Kept here (mirroring
+    # ColumnGuard / RandomValue) so the concern itself stays lean and so the
+    # large constant tables live as plain literals rather than RuboCop-flagged
+    # blocks. All lookups are case-insensitive and string-safe.
+    #
+    # Scope is *format/structure* only — this validates shape (a well-formed
+    # postal code, a real ISO country code), never real-world deliverability.
+    module AddressData
+      module_function
+
+      # ISO 3166-1 alpha-2 country codes.
+      ISO_COUNTRY_CODES = Set.new(%w[
+                                    AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ
+                                    BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ
+                                    CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ
+                                    DE DJ DK DM DO DZ
+                                    EC EE EG EH ER ES ET
+                                    FI FJ FK FM FO FR
+                                    GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY
+                                    HK HM HN HR HT HU
+                                    ID IE IL IM IN IO IQ IR IS IT
+                                    JE JM JO JP
+                                    KE KG KH KI KM KN KP KR KW KY KZ
+                                    LA LB LC LI LK LR LS LT LU LV LY
+                                    MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ
+                                    NA NC NE NF NG NI NL NO NP NR NU NZ
+                                    OM
+                                    PA PE PF PG PH PK PL PM PN PR PS PT PW PY
+                                    QA
+                                    RE RO RS RU RW
+                                    SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ
+                                    TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ
+                                    UA UG UM US UY UZ
+                                    VA VC VE VG VI VN VU
+                                    WF WS
+                                    YE YT
+                                    ZA ZM ZW
+                                  ]).freeze
+
+      # Per-country postal-code patterns (matched against the *normalized*,
+      # upcased value). `:default` is a permissive fallback for everything else.
+      POSTAL_FORMATS = {
+        "US" => /\A\d{5}(-\d{4})?\z/,
+        "CA" => /\A[A-Z]\d[A-Z] ?\d[A-Z]\d\z/,
+        "GB" => /\A[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}\z/,
+        "AU" => /\A\d{4}\z/,
+        "DE" => /\A\d{5}\z/,
+        "FR" => /\A\d{5}\z/,
+        default: /\A[A-Z0-9][A-Z0-9 -]{1,8}[A-Z0-9]\z/
+      }.freeze
+
+      # USPS state / territory abbreviations.
+      US_STATES = Set.new(%w[
+                            AL AK AZ AR CA CO CT DE FL GA HI ID IL IN IA KS KY LA ME MD MA MI MN MS
+                            MO MT NE NV NH NJ NM NY NC ND OH OK OR PA RI SC SD TN TX UT VT VA WA WV
+                            WI WY DC AS GU MP PR VI
+                          ]).freeze
+
+      # Canadian province / territory codes.
+      CA_PROVINCES = Set.new(%w[AB BC MB NB NL NS NT NU ON PE QC SK YT]).freeze
+
+      # True when `code` is a known ISO 3166-1 alpha-2 country code.
+      def valid_country?(code)
+        return false unless code.is_a?(String)
+
+        ISO_COUNTRY_CODES.include?(code.upcase)
+      end
+
+      # Regexp to validate a postal code for the given country (falls back to
+      # the permissive `:default` pattern for unmapped countries).
+      def postal_format_for(country)
+        POSTAL_FORMATS[country.to_s.upcase] || POSTAL_FORMATS[:default]
+      end
+
+      # Validate a state/region against US / CA sets. Returns true for any other
+      # country (we only know those two), so callers needn't special-case.
+      def valid_state?(country, code)
+        return true unless code.is_a?(String)
+
+        case country.to_s.upcase
+        when "US" then US_STATES.include?(code.upcase)
+        when "CA" then CA_PROVINCES.include?(code.upcase)
+        else true
+        end
+      end
+
+      # Squish + upcase a postal code, adding canonical spacing for CA
+      # (`A1A1A1` -> `A1A 1A1`). Non-strings pass through unchanged.
+      def normalize_postal(country, value)
+        return value unless value.is_a?(String)
+
+        normalized = value.strip.squish.upcase
+        return normalized unless country.to_s.upcase == "CA"
+
+        compact = normalized.delete(" ")
+        compact.match?(/\A[A-Z]\d[A-Z]\d[A-Z]\d\z/) ? "#{compact[0, 3]} #{compact[3, 3]}" : normalized
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/sequence_calculator.rb

@@ -0,0 +1,74 @@
+module ConcernsOnRails
+  module Support
+    # Internal helpers for Models::Sequenceable: computing the next value within a
+    # scope (+ period) and formatting it. Mixed into the model's class methods, so
+    # `self` is the model class and `unscoped` / `sequenceable_config` resolve
+    # against it. Kept here to keep the concern itself focused on configuration.
+    module SequenceCalculator
+      private
+
+      # Next integer that would be assigned for the given scope: MAX within the
+      # scope (+ period) + 1, or start_at when the scope/period is still empty.
+      def sequence_base_value(field, record, scope_attrs)
+        cfg = sequenceable_config.fetch(field)
+        max = sequence_relation(field, record, scope_attrs).maximum(field)
+        max ? max + 1 : cfg[:start_at]
+      end
+
+      def sequence_value_taken?(field, candidate, record, scope_attrs)
+        sequence_relation(field, record, scope_attrs).exists?(field => candidate)
+      end
+
+      # Relation of existing rows that share this record's scope (and period, when
+      # reset is enabled). Reads from `unscoped` so a model's default_scope never
+      # hides rows the counter must account for.
+      def sequence_relation(field, record, scope_attrs)
+        cfg = sequenceable_config.fetch(field)
+        rel = unscoped
+
+        cfg[:scope].each do |col|
+          value = record ? record[col] : (scope_attrs[col] || scope_attrs[col.to_s])
+          rel = rel.where(col => value)
+        end
+
+        return rel if cfg[:reset] == :never
+
+        rel.where(created_at: period_range(cfg[:reset], base_time(record)))
+      end
+
+      def format_sequence(field, seq, record)
+        cfg = sequenceable_config.fetch(field)
+        return cfg[:template].call(seq, record) if cfg[:template]
+
+        padded = cfg[:padding].positive? ? seq.to_s.rjust(cfg[:padding], "0") : seq.to_s
+        return "#{cfg[:prefix]}#{padded}" if cfg[:reset] == :never
+
+        token = period_token(cfg[:reset], base_time(record))
+        "#{cfg[:prefix]}#{token}#{cfg[:separator]}#{padded}"
+      end
+
+      def period_range(reset, time)
+        case reset
+        when :year  then time.beginning_of_year..time.end_of_year
+        when :month then time.beginning_of_month..time.end_of_month
+        when :day   then time.beginning_of_day..time.end_of_day
+        end
+      end
+
+      def period_token(reset, time)
+        case reset
+        when :year  then time.year.to_s
+        when :month then time.strftime("%Y%m")
+        when :day   then time.strftime("%Y%m%d")
+        end
+      end
+
+      # created_at is the natural anchor for the period, but it may not be set yet
+      # during before_create — fall back to the current time, which is what the
+      # timestamp will resolve to anyway.
+      def base_time(record)
+        record&.created_at || Time.current
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.9.0".freeze
+  VERSION = "1.11.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -10,6 +10,8 @@ end
 # Shared internal helpers (must load before the concerns that use them)
 require "concerns_on_rails/support/column_guard"
 require "concerns_on_rails/support/random_value"
+require "concerns_on_rails/support/address_data"
+require "concerns_on_rails/support/sequence_calculator"
 
 # Model concerns
 require "concerns_on_rails/models/sluggable"
@@ -24,6 +26,8 @@ require "concerns_on_rails/models/searchable"
 require "concerns_on_rails/models/activatable"
 require "concerns_on_rails/models/tokenizable"
 require "concerns_on_rails/models/stateable"
+require "concerns_on_rails/models/addressable"
+require "concerns_on_rails/models/sequenceable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -78,19 +78,23 @@ files:
 - lib/concerns_on_rails/controllers/sortable.rb
 - lib/concerns_on_rails/legacy_aliases.rb
 - lib/concerns_on_rails/models/activatable.rb
+- lib/concerns_on_rails/models/addressable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
 - lib/concerns_on_rails/models/normalizable.rb
 - lib/concerns_on_rails/models/publishable.rb
 - lib/concerns_on_rails/models/schedulable.rb
 - lib/concerns_on_rails/models/searchable.rb
+- lib/concerns_on_rails/models/sequenceable.rb
 - lib/concerns_on_rails/models/sluggable.rb
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb
 - lib/concerns_on_rails/models/stateable.rb
 - lib/concerns_on_rails/models/tokenizable.rb
+- lib/concerns_on_rails/support/address_data.rb
 - lib/concerns_on_rails/support/column_guard.rb
 - lib/concerns_on_rails/support/random_value.rb
+- lib/concerns_on_rails/support/sequence_calculator.rb
 - lib/concerns_on_rails/version.rb
 homepage: https://github.com/VSN2015/concerns_on_rails
 licenses: