active_record-virtual_joins 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59d1d1b0ae151d9115e013a4915f52555327779289019f736dbb551a187ad6f1
+  data.tar.gz: c1b133959d7ff43e37fe86e3728625bfaafdd939cfc0053d6aff7e935f57f751
+SHA512:
+  metadata.gz: cb99c980f83b67ec6ad6332946407dd59dc2c0795b3f2856fedbb0e3ef7ccec9fd687ad0e438240d3073877fe963429a001ede9111998dd91e5ac9387af70275
+  data.tar.gz: de20998770a734153f1ffa2149990b9fe7540ebcc55a87c30670210d446bc367f3e2e9ed0255dd24880b6e978e3c0e157dd4754788efde72cec24446bc8c9c4a

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,101 @@
+# ActiveRecord::VirtualJoins
+
+Joins a list of Ruby hashes to the records of an ActiveRecord relation, as a virtual table.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_record-virtual_joins', github: 'mintyfresh/active_record-virtual_joins'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Then extend your models with `ActiveRecord::VirtualJoins` (typically in `ApplicationRecord`, so all models get it):
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  extend ActiveRecord::VirtualJoins
+end
+```
+
+## Usage
+
+`virtual_joins` takes the column to join by, the list of hashes, and the types of the other columns.
+The values are left-joined to the records by the join column, and selected onto them:
+
+```ruby
+scores = [{ id: 1, score: 10 }, { id: 2, score: 20 }]
+
+users = User.virtual_joins(:id, scores, score: :integer)
+# SELECT "users".*, "users_id_json"."score" FROM "users"
+# LEFT OUTER JOIN json_to_recordset('[{"id":1,"score":10},{"id":2,"score":20}]'::json)
+#   AS "users_id_json"("score" integer, "id" bigint)
+#   ON "users"."id" = "users_id_json"."id"
+
+users.find(1).score # => 10
+users.find(3).score # => nil
+```
+
+Records without matching values are kept, with null values.
+Keys of the hashes that aren't columns of the virtual table are ignored, and missing keys are null.
+
+The values can be used in the rest of the query, by the name of the virtual table
+(which defaults to the table and join column, eg. `users_id_json`):
+
+```ruby
+User.virtual_joins(:id, scores, score: :integer).where('users_id_json.score > 15').order('users_id_json.score')
+
+User.virtual_joins(:id, scores, join_table_name: :scores, score: :integer).order('scores.score')
+```
+
+It can be called on any relation (including associations), and keeps the relation's conditions and projection:
+
+```ruby
+user.posts.where(published: true).virtual_joins(:slug, views, views: :integer)
+User.select(:id).virtual_joins(:id, scores, score: :integer) # selects only users.id and the score
+```
+
+### Types
+
+Types can be given as ActiveRecord types (eg. `:integer`, `:string`), which are converted to the database's types,
+or as SQL types (eg. `'decimal(10, 2)'`), which are used as they are.
+The type of the join column defaults to the type of the model's column, but can be given like any other column.
+
+Note that `:decimal` uses the database's default precision, which is a scale of 0 on MySQL
+(so use an SQL type like `'decimal(10, 2)'` for fractional values).
+
+### Databases
+
+PostgreSQL (`json_to_recordset`), MySQL (`JSON_TABLE`), and SQLite (`json_each`) are supported.
+
+SQLite has no column types to convert the values to, so values are read as their JSON types
+(eg. strings rather than times, and `1`/`0` rather than booleans).
+
+### Sorbet
+
+A Tapioca DSL compiler is included, which adds `virtual_joins` to the relations generated for models
+extended by `ActiveRecord::VirtualJoins`. 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/virtual_joins/version.rb

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

data/lib/active_record/virtual_joins/virtual_table.rb

@@ -0,0 +1,128 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveRecord
+  module VirtualJoins
+    # A table of values decoded from JSON by the database, with the SQL to join it to a model's table:
+    # * PostgreSQL - `json_to_recordset`
+    # * MySQL - `JSON_TABLE`
+    # * SQLite - `json_each` (which doesn't convert the values to the types of the columns)
+    class VirtualTable
+      #: String
+      attr_reader :name
+
+      #: (
+      #|   singleton(ActiveRecord::Base) model,
+      #|   Symbol | String name,
+      #|   Symbol | String join_column_name,
+      #|   Hash[Symbol | String, Symbol | String] column_types
+      #| ) -> void
+      def initialize(model, name, join_column_name, column_types)
+        @model = model
+        @name = name.to_s
+        @join_column_name = join_column_name.to_s
+        @column_types = column_types.transform_keys(&:to_s)
+        @column_types[@join_column_name] ||= join_column_type
+      end
+
+      # Joins the virtual table to the model's table, by the join column.
+      #
+      #: (Enumerable[Hash[Symbol | String, untyped]] values) -> String
+      def join_sql(values)
+        @model.with_connection do |connection|
+          source = source_sql(connection)
+          condition = "#{@model.quoted_table_name}.#{connection.quote_column_name(@join_column_name)} = " \
+                      "#{qualified_column_name(connection, @join_column_name)}"
+
+          @model.sanitize_sql_array(
+            ["LEFT OUTER JOIN #{source} ON #{condition}", ActiveSupport::JSON.encode(values.to_a)]
+          )
+        end
+      end
+
+      # The columns of the virtual table, other than the join column (which is the same as the model's).
+      #
+      #: -> Array[Arel::Nodes::SqlLiteral]
+      def select_values
+        @model.with_connection do |connection|
+          @column_types.keys.excluding(@join_column_name).map do |column_name|
+            Arel.sql(qualified_column_name(connection, column_name))
+          end
+        end
+      end
+
+    private
+
+      #: -> String
+      def join_column_type
+        column = @model.columns_hash[@join_column_name]
+        return column.sql_type if column
+
+        raise ArgumentError, "The type of the join column `#{@join_column_name}` must be given, " \
+                             "since it isn't a column of `#{@model.name}`."
+      end
+
+      # The table, which decodes the values from a JSON array of objects (given as a bind parameter).
+      #
+      #: (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, "virtual_joins isn't supported by the #{connection.adapter_name} adapter."
+        end
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def postgresql_source_sql(connection)
+        columns = @column_types.map do |column_name, type|
+          "#{connection.quote_column_name(column_name)} #{sql_type(connection, type)}"
+        end
+
+        "json_to_recordset(?::json) AS #{connection.quote_table_name(name)}(#{columns.join(', ')})"
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> String
+      def mysql_source_sql(connection)
+        columns = @column_types.map do |column_name, type|
+          "#{connection.quote_column_name(column_name)} #{sql_type(connection, type)} " \
+            "PATH #{connection.quote(json_path(column_name))}"
+        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_types.keys.map do |column_name|
+          "json_extract(value, #{connection.quote(json_path(column_name))}) " \
+            "AS #{connection.quote_column_name(column_name)}"
+        end
+
+        "(SELECT #{columns.join(', ')} FROM json_each(?)) AS #{connection.quote_table_name(name)}"
+      end
+
+      # ActiveRecord types are converted to the database's types (eg. `:string` to `character varying`),
+      # while SQL types are used as they are.
+      #
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection, Symbol | String type) -> String
+      def sql_type(connection, type)
+        type.is_a?(Symbol) ? connection.type_to_sql(type) : type
+      end
+
+      # A path to a key of a JSON object (which is quoted, so that keys aren't parsed as paths).
+      #
+      #: (String column_name) -> String
+      def json_path(column_name)
+        "$.#{column_name.to_json}"
+      end
+
+      #: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection, String column_name) -> String
+      def qualified_column_name(connection, column_name)
+        "#{connection.quote_table_name(name)}.#{connection.quote_column_name(column_name)}"
+      end
+    end
+  end
+end

data/lib/active_record/virtual_joins.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_record/virtual_joins/version'
+
+module ActiveRecord
+  # Joins lists of hashes to the records of a model and its subclasses, as virtual tables:
+  #
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     extend ActiveRecord::VirtualJoins
+  #   end
+  #
+  #   users = User.virtual_joins(:id, [{ id: 1, score: 10 }, { id: 2, score: 20 }], score: :integer)
+  #   users.find(1).score # => 10
+  module VirtualJoins
+    autoload :VirtualTable, 'active_record/virtual_joins/virtual_table'
+
+    # Left-joins a list of hashes as a virtual table, matched to records by the join column,
+    # and selects the other columns of the virtual table onto the records.
+    #
+    # The columns of the virtual table are given with their types, as ActiveRecord types (eg. `:integer`)
+    # or SQL types (eg. `'numeric(10, 2)'`). The type of the join column defaults to that of the model's column.
+    # Keys of the hashes that aren't columns of the virtual table are ignored, and missing keys are null.
+    #
+    # The records' own columns are selected, unless the relation already selects other columns.
+    #
+    #: (
+    #|   Symbol | String join_column_name,
+    #|   Enumerable[Hash[Symbol | String, untyped]] join_values,
+    #|   ?join_table_name: Symbol | String,
+    #|   **Symbol | String join_value_types
+    #| ) -> ActiveRecord::Relation
+    def virtual_joins(
+      join_column_name,
+      join_values,
+      join_table_name: "#{table_name}_#{join_column_name}_json",
+      **join_value_types
+    )
+      virtual_table = VirtualTable.new(self, join_table_name, join_column_name, join_value_types)
+
+      relation = all.joins(virtual_table.join_sql(join_values))
+      relation = relation.select(arel_table[Arel.star]) if relation.select_values.empty?
+
+      select_values = virtual_table.select_values
+      select_values.empty? ? relation : relation.select(*select_values)
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# 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 `virtual_joins` to the relations generated by the ActiveRecordRelations compiler,
+      # for models extended by ActiveRecord::VirtualJoins.
+      # (Relations delegate it to their model, so it isn't otherwise known to be a relation method.)
+      # Compilers decorate a constant in order of their names, so this runs after ActiveRecordRelations.
+      #
+      #: [ConstantType = singleton(::ActiveRecord::Base)]
+      class ActiveRecordVirtualJoins < 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_virtual_joins_method(mod, RelationClassName)
+            end
+
+            model.create_module(AssociationRelationMethodsModuleName) do |mod|
+              create_virtual_joins_method(mod, AssociationRelationClassName)
+            end
+          end
+        end
+
+        class << self
+          # @override
+          #: -> Enumerable[Module[top]]
+          def gather_constants
+            ActiveRecordRelations.gather_constants.grep(::ActiveRecord::VirtualJoins)
+          end
+        end
+
+      private
+
+        #: (RBI::Scope scope, String return_type) -> void
+        def create_virtual_joins_method(scope, return_type)
+          scope.create_method(
+            'virtual_joins',
+            parameters: [
+              create_param('join_column_name', type: 'T.any(Symbol, String)'),
+              create_param('join_values', type: 'T::Enumerable[T::Hash[T.any(Symbol, String), T.untyped]]'),
+              create_kw_opt_param('join_table_name', type: 'T.any(Symbol, String)', default: default_join_table_name),
+              create_kw_rest_param('join_value_types', type: 'T.any(Symbol, String)'),
+            ],
+            return_type:
+          )
+        end
+
+        # The default depends on the join column, so it's given as the expression which computes it.
+        #
+        #: -> String
+        def default_join_table_name
+          '"#{table_name}_#{join_column_name}_json"' # rubocop:disable Lint/InterpolationCheck
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: active_record-virtual_joins
+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 a list of hashes to the records of an ActiveRecord relation as
+  a virtual table, selecting its values onto the records.
+email:
+- 7896757+mintyfresh@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/active_record/virtual_joins.rb
+- lib/active_record/virtual_joins/version.rb
+- lib/active_record/virtual_joins/virtual_table.rb
+- lib/tapioca/dsl/compilers/active_record_virtual_joins.rb
+homepage: https://github.com/mintyfresh/active_record-virtual_joins
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mintyfresh/active_record-virtual_joins
+  source_code_uri: https://github.com/mintyfresh/active_record-virtual_joins
+  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: Join lists of Ruby hashes to ActiveRecord relations
+test_files: []