active_record-with_ordinality 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f21ab71daeca46389e1fc3cc0ace3dad48ef691a4bb91d4735573305d2bbe0de
+  data.tar.gz: 27841e8dfde95dd646a72d942a5be56668be1bf40c3d6202be4cbfb94bb1621c
+SHA512:
+  metadata.gz: 6d8a9745c4127e6d2e1d700bb091dca36da0765ea5d4002f9c513337633c3d02341447759e9788042c0c2143d62968204b7e3bfa7db8faf28a54739549e236c6
+  data.tar.gz: 7dd838bff8c2e5b5c0ca966780197af58a68da6d8ec4a9b346959c6037f9519adac2bee85d076f060b936ae975b45c3e0113f35e609dd60757ed483a05a3c794

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Minty Fresh
+
+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,116 @@
+# ActiveRecord::WithOrdinality
+
+Joins lists of values to ActiveRecord relations with their ordinal positions,
+and orders relations by them with `in_order_of`.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_record-with_ordinality', github: 'mintyfresh/active_record-with_ordinality'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Then extend your models with `ActiveRecord::WithOrdinality` (typically in `ApplicationRecord`, so all models get it):
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  extend ActiveRecord::WithOrdinality
+end
+```
+
+## Usage
+
+### with_ordinality
+
+`with_ordinality` joins a list of values to the records with matching columns,
+along with the position of each value (starting from 1):
+
+```ruby
+User.with_ordinality(:id, [3, 1, 2])
+# SELECT "users".* FROM "users"
+# INNER JOIN (
+#   SELECT (element.value->>0)::bigint AS "id", element.ordinality AS "ordinal"
+#   FROM json_array_elements('[[3],[1],[2]]'::json) WITH ORDINALITY AS element(value, ordinality)
+# ) AS "users_id_ordinals" ON "users"."id" = "users_id_ordinals"."id"
+# WHERE "users"."id" IN (3, 1, 2)
+```
+
+The ordinal is selected onto the records when it's given a name with `as`:
+
+```ruby
+User.with_ordinality(:id, [3, 1, 2], as: :position).map { |user| [user.id, user.position] }
+# => [[1, 2], [2, 3], [3, 1]]
+```
+
+Otherwise, it can be used in the rest of the query by the name of the joined table
+(which defaults to the table and columns, eg. `users_id_ordinals`, or can be given with `join_table_name`):
+
+```ruby
+User.with_ordinality(:id, [3, 1, 2]).order('users_id_ordinals.ordinal')
+User.with_ordinality(:id, [3, 1, 2], join_table_name: :positions).order('positions.ordinal')
+```
+
+Only records matching the values are kept, unless `filter` is false (in which case other records have no ordinal):
+
+```ruby
+User.with_ordinality(:id, [3, 1], as: :position, filter: false)
+```
+
+Repeated values are joined once, at their first position, so that records aren't repeated.
+Values are converted by the types of the attributes, so eg. enums can be given by name.
+
+### Composite columns
+
+Several columns can be given, with a list of values for each record:
+
+```ruby
+User.with_ordinality(%i[tenant_id id], [[1, 3], [1, 1], [1, 2], [2, 4]], as: :position)
+```
+
+### in_order_of
+
+`in_order_of` is overridden to order records by their ordinals, rather than by a `CASE` of every value,
+and supports composite columns:
+
+```ruby
+User.in_order_of(:id, [3, 1, 2])
+User.in_order_of(%i[tenant_id id], [[1, 3], [1, 1], [1, 2], [2, 4]])
+User.in_order_of(:id, [3, 1, 2], filter: false) # other records are ordered last
+```
+
+Columns that aren't attributes of the model (eg. `Arel.sql('LOWER(name)')`) are ordered by Rails' `in_order_of`.
+
+### Databases
+
+PostgreSQL (`json_array_elements` with `WITH ORDINALITY`), MySQL (`JSON_TABLE` with `FOR ORDINALITY`),
+and SQLite (`json_each`) are supported.
+
+### Sorbet
+
+A Tapioca DSL compiler is included, which adds `with_ordinality` to the relations generated for models
+extended by `ActiveRecord::WithOrdinality`. It's loaded automatically by `bin/tapioca dsl`.
+
+## Development
+
+The specs run against a dummy Rails application in `spec/dummy`, using SQLite by default:
+
+```bash
+$ bin/rspec
+$ bin/rubocop
+```
+
+PostgreSQL and MySQL are selected with the `DATABASE_ADAPTER` and `DATABASE_URL` environment variables
+(see `.github/workflows/ci.yml`).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/active_record/with_ordinality/ordinality_table.rb

@@ -0,0 +1,160 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WithOrdinality
+    # A table of values (decoded from JSON by the database) numbered by their position, with the SQL to join it:
+    # * PostgreSQL - `json_array_elements` with `WITH ORDINALITY`
+    # * MySQL - `JSON_TABLE` with a `FOR ORDINALITY` column
+    # * SQLite - `json_each`, numbered by array index
+    #
+    # The table has a column for each of the model's columns (of the same name and type), and an `ordinal` column.
+    class OrdinalityTable
+      ORDINAL_COLUMN_NAME = 'ordinal'
+
+      class << self
+        # Checks if columns are given as names of the model's attributes (rather than eg. SQL expressions).
+        #
+        #: (singleton(ActiveRecord::Base) model, untyped column_names) -> bool
+        def attributes?(model, column_names)
+          names = Array(column_names)
+
+          names.any? && names.all? do |name|
+            (name.is_a?(Symbol) || name.is_a?(String)) && model.columns_hash.key?(column_name(model, name))
+          end
+        end
+
+        # Resolves aliased attributes to their columns.
+        #
+        #: (singleton(ActiveRecord::Base) model, Symbol | String name) -> String
+        def column_name(model, name)
+          model.attribute_aliases.fetch(name.to_s, name.to_s)
+        end
+      end
+
+      #: String
+      attr_reader :name
+
+      # The rows of values, without repeats (which would join each record more than once).
+      #
+      #: Array[Array[untyped]]
+      attr_reader :values
+
+      #: (
+      #|   singleton(ActiveRecord::Base) model,
+      #|   Symbol | String | Array[Symbol | String] column_names,
+      #|   Enumerable[untyped] values,
+      #|   ?(Symbol | String)? name
+      #| ) -> void
+      def initialize(model, column_names, values, name = nil)
+        @model = model
+        @column_names = Array(column_names).map { |column_name| resolve_column_name(column_name) }
+        @values = values.map { |value| column_names.is_a?(Array) ? row(value) : [value] }.uniq
+        @name = (name || "#{model.table_name}_#{@column_names.join('_')}_ordinals").to_s
+      end
+
+      # Matches the records to the values, as a condition of the model's table (so that its indexes may be used).
+      #
+      #: -> Hash[String | Array[String], untyped]
+      def condition
+        @column_names.one? ? { @column_names.first => @values.map(&:first) } : { @column_names => @values }
+      end
+
+      #: -> Arel::Attributes::Attribute
+      def ordinal
+        Arel::Table.new(name)[ORDINAL_COLUMN_NAME]
+      end
+
+      # Joins the table to the model's table by the columns.
+      #
+      #: (String join_type) -> String
+      def join_sql(join_type)
+        @model.with_connection do |connection|
+          conditions = @column_names.map do |column_name|
+            "#{@model.quoted_table_name}.#{connection.quote_column_name(column_name)} = " \
+              "#{connection.quote_table_name(name)}.#{connection.quote_column_name(column_name)}"
+          end
+
+          @model.sanitize_sql_array(
+            ["#{join_type} #{source_sql(connection)} ON #{conditions.join(' AND ')}", ActiveSupport::JSON.encode(rows)]
+          )
+        end
+      end
+
+    private
+
+      #: (Symbol | String column_name) -> String
+      def resolve_column_name(column_name)
+        resolved = self.class.column_name(@model, column_name)
+        return resolved if @model.columns_hash.key?(resolved)
+
+        raise ArgumentError, "`#{column_name}` is not a column of `#{@model.name}`."
+      end
+
+      #: (untyped value) -> Array[untyped]
+      def row(value)
+        row = Array(value)
+        return row if row.size == @column_names.size
+
+        raise ArgumentError, "Expected #{@column_names.size} values for the columns #{@column_names.inspect}, " \
+                             "got #{value.inspect}."
+      end
+
+      # The values as the database stores them (eg. the integers of enums).
+      #
+      #: -> Array[Array[untyped]]
+      def rows
+        types = @column_names.map { |column_name| @model.type_for_attribute(column_name) }
+
+        @values.map { |row| row.zip(types).map { |value, type| type.serialize(value) } }
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def source_sql(connection)
+        case connection.adapter_name
+        when /postgres/i then postgresql_source_sql(connection)
+        when /mysql|trilogy/i then mysql_source_sql(connection)
+        when /sqlite/i then sqlite_source_sql(connection)
+        else
+          raise NotImplementedError, "with_ordinality isn't supported by the #{connection.adapter_name} adapter."
+        end
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def postgresql_source_sql(connection)
+        columns = @column_names.each_with_index.map do |column_name, index|
+          "(element.value->>#{index})::#{@model.columns_hash[column_name].sql_type} " \
+            "AS #{connection.quote_column_name(column_name)}"
+        end
+        columns << "element.ordinality AS #{connection.quote_column_name(ORDINAL_COLUMN_NAME)}"
+
+        elements = 'json_array_elements(?::json) WITH ORDINALITY AS element(value, ordinality)'
+
+        "(SELECT #{columns.join(', ')} FROM #{elements}) AS #{connection.quote_table_name(name)}"
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def mysql_source_sql(connection)
+        columns = ["#{connection.quote_column_name(ORDINAL_COLUMN_NAME)} FOR ORDINALITY"]
+        columns.concat(
+          @column_names.each_with_index.map do |column_name, index|
+            "#{connection.quote_column_name(column_name)} #{@model.columns_hash[column_name].sql_type} " \
+              "PATH '$[#{index}]'"
+          end
+        )
+
+        "JSON_TABLE(?, '$[*]' COLUMNS(#{columns.join(', ')})) AS #{connection.quote_table_name(name)}"
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def sqlite_source_sql(connection)
+        columns = @column_names.each_with_index.map do |column_name, index|
+          "json_extract(value, '$[#{index}]') AS #{connection.quote_column_name(column_name)}"
+        end
+        columns << "key + 1 AS #{connection.quote_column_name(ORDINAL_COLUMN_NAME)}"
+
+        "(SELECT #{columns.join(', ')} FROM json_each(?)) AS #{connection.quote_table_name(name)}"
+      end
+    end
+  end
+end

data/lib/active_record/with_ordinality/relation_extension.rb

@@ -0,0 +1,59 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WithOrdinality
+    module RelationExtension
+      # Joins a list of values to the records with matching columns, along with the ordinal position of each value
+      # (starting from 1). Composite columns are matched by lists of values:
+      #
+      #   User.with_ordinality(:id, [3, 1, 2])
+      #   User.with_ordinality(%i[tenant_id id], [[1, 3], [1, 1], [2, 4]])
+      #
+      # Only records matching the values are kept, unless `filter` is false (in which case others have no ordinal).
+      # The ordinal is selected onto the records as the attribute named by `as`, if given.
+      # Otherwise it can be referred to by the joined table (eg. `users_id_ordinals.ordinal`).
+      #
+      # Repeated values are joined once, at their first position.
+      #
+      #: (
+      #|   Symbol | String | Array[Symbol | String] column_names,
+      #|   Enumerable[untyped] values,
+      #|   ?as: (Symbol | String)?,
+      #|   ?filter: bool,
+      #|   ?join_table_name: (Symbol | String)?
+      #| ) -> ActiveRecord::Relation
+      def with_ordinality(column_names, values, as: nil, filter: true, join_table_name: nil)
+        ordinality = OrdinalityTable.new(model, column_names, values, join_table_name)
+        return none if filter && ordinality.values.empty?
+
+        relation = filter ? where(ordinality.condition) : spawn
+        relation = relation.joins(ordinality.join_sql(filter ? 'INNER JOIN' : 'LEFT OUTER JOIN'))
+        return relation unless as
+
+        relation = relation.select(table[Arel.star]) if relation.select_values.empty?
+        relation.select(ordinality.ordinal.as(model.adapter_class.quote_column_name(as.to_s)))
+      end
+
+      # Orders the records in the order of a list of values, by joining them `with_ordinality`.
+      # Composite columns are ordered by lists of values (see `with_ordinality`).
+      #
+      # Only records matching the values are kept, unless `filter` is false (in which case others are ordered last).
+      # Columns that aren't attributes of the model (eg. SQL expressions) are ordered by Rails' `in_order_of` instead.
+      #
+      #: (untyped column_names, Enumerable[untyped] values, ?filter: bool) -> ActiveRecord::Relation
+      def in_order_of(column_names, values, filter: true)
+        return super unless OrdinalityTable.attributes?(model, column_names)
+
+        # Rails' `in_order_of` matches no records for no values, regardless of `filter`
+        values = values.to_a
+        return none if values.empty?
+
+        ordinal = OrdinalityTable.new(model, column_names, values).ordinal
+        relation = with_ordinality(column_names, values, filter:)
+
+        filter ? relation.order(ordinal.asc) : relation.order(ordinal.eq(nil), ordinal.asc)
+      end
+    end
+  end
+end

data/lib/active_record/with_ordinality/version.rb

@@ -0,0 +1,8 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WithOrdinality
+    VERSION = '0.1.0'
+  end
+end

data/lib/active_record/with_ordinality.rb

@@ -0,0 +1,61 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_record/with_ordinality/version'
+
+module ActiveRecord
+  # Adds `with_ordinality` to the relations of a model and its subclasses, which joins a list of values to the records
+  # with their ordinal positions, and overrides `in_order_of` to order records by them (rather than by a CASE):
+  #
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     extend ActiveRecord::WithOrdinality
+  #   end
+  #
+  #   User.with_ordinality(:id, [3, 1, 2], as: :ordinal).map(&:ordinal)
+  #   User.in_order_of(%i[tenant_id id], [[1, 3], [1, 1], [2, 4]])
+  module WithOrdinality
+    autoload :OrdinalityTable, 'active_record/with_ordinality/ordinality_table'
+    autoload :RelationExtension, 'active_record/with_ordinality/relation_extension'
+
+    class << self
+      # Extends the relations of a model, and of any of its subclasses that were already defined.
+      #
+      #: (singleton(ActiveRecord::Base) base) -> void
+      def extended(base)
+        super
+        [base, *base.descendants].each(&:install_with_ordinality)
+      end
+    end
+
+    # See `RelationExtension#with_ordinality`.
+    #
+    #: (*untyped args, **untyped options) -> ActiveRecord::Relation
+    def with_ordinality(*args, **options)
+      all.with_ordinality(*args, **options)
+    end
+
+    # See `RelationExtension#in_order_of`.
+    #
+    #: (*untyped args, **untyped options) -> ActiveRecord::Relation
+    def in_order_of(*args, **options)
+      all.in_order_of(*args, **options)
+    end
+
+    # Rails builds the relation classes of each model as it's defined (see `ActiveRecord::Delegation::DelegateCache`),
+    # so subclasses defined after the model was extended are installed here.
+    #
+    #: -> void
+    def initialize_relation_delegate_cache
+      super
+      install_with_ordinality
+    end
+
+    #: -> void
+    def install_with_ordinality
+      ActiveRecord::Delegation.delegated_classes.each do |relation_class|
+        relation_delegate_class(relation_class).include(RelationExtension)
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/active_record_with_ordinality.rb

@@ -0,0 +1,63 @@
+# typed: strict
+# frozen_string_literal: true
+
+return unless defined?(ActiveRecord::Base)
+
+require 'tapioca/dsl/compilers/active_record_relations'
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Adds `with_ordinality` to the relations generated by the ActiveRecordRelations compiler,
+      # for models extended by ActiveRecord::WithOrdinality.
+      # (The `in_order_of` override needs no signature, since the generated one is untyped.)
+      # Compilers decorate a constant in order of their names, so this runs after ActiveRecordRelations.
+      #
+      #: [ConstantType = singleton(::ActiveRecord::Base)]
+      class ActiveRecordWithOrdinality < Compiler
+        include Helpers::ActiveRecordConstantsHelper
+
+        # @override
+        #: -> void
+        def decorate
+          return unless compiler_enabled?('ActiveRecordRelations')
+
+          root.create_path(constant) do |model|
+            model.create_module(RelationMethodsModuleName) do |mod|
+              create_with_ordinality_method(mod, RelationClassName)
+            end
+
+            model.create_module(AssociationRelationMethodsModuleName) do |mod|
+              create_with_ordinality_method(mod, AssociationRelationClassName)
+            end
+          end
+        end
+
+        class << self
+          # @override
+          #: -> Enumerable[Module[top]]
+          def gather_constants
+            ActiveRecordRelations.gather_constants.grep(::ActiveRecord::WithOrdinality)
+          end
+        end
+
+      private
+
+        #: (RBI::Scope scope, String return_type) -> void
+        def create_with_ordinality_method(scope, return_type)
+          scope.create_method(
+            'with_ordinality',
+            parameters: [
+              create_param('column_names', type: 'T.any(Symbol, String, T::Array[T.any(Symbol, String)])'),
+              create_param('values', type: 'T::Enumerable[T.untyped]'),
+              create_kw_opt_param('as', type: 'T.nilable(T.any(Symbol, String))', default: 'nil'),
+              create_kw_opt_param('filter', type: 'T::Boolean', default: 'true'),
+              create_kw_opt_param('join_table_name', type: 'T.nilable(T.any(Symbol, String))', default: 'nil'),
+            ],
+            return_type:
+          )
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: active_record-with_ordinality
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Minty Fresh
+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: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: Joins lists of values to ActiveRecord relations with their ordinal positions,
+  and orders relations by them with in_order_of.
+email:
+- 7896757+mintyfresh@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/active_record/with_ordinality.rb
+- lib/active_record/with_ordinality/ordinality_table.rb
+- lib/active_record/with_ordinality/relation_extension.rb
+- lib/active_record/with_ordinality/version.rb
+- lib/tapioca/dsl/compilers/active_record_with_ordinality.rb
+homepage: https://github.com/mintyfresh/active_record-with_ordinality
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mintyfresh/active_record-with_ordinality
+  source_code_uri: https://github.com/mintyfresh/active_record-with_ordinality
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ordinal joins for ActiveRecord relations
+test_files: []