graphsql 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cf0933b75d22d60adbda095d91985202111a72476a1d418b9b6b6c19a9e26c3
+  data.tar.gz: dc5823be1f0741913aa1166be8c4826bd7744623d5fd578457a1cc252ec0b58d
+SHA512:
+  metadata.gz: d55b842c33c1bebdfdaec2cf0fe8939f2ac7daebac8d61e4c1c85cd57b10120fec5acb7e937ffbfb50c73cc23055e94a2df3ecd009ab40dcd8a88d5f9b4c0356
+  data.tar.gz: 76c2e45232b2ee3788cb313394f8263be8a51f94e9bc257a9f0275ac1e2e1e3aaaee3386173217632d0923adbcb407ff33827e0f4a09e5efe2e5f92ec3b39f80

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dot Matrix Consulting
+
+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,125 @@
+# GraphSQL
+
+GraphSQL maps GraphQL type fields to ActiveRecord columns and associations,
+then applies a GraphQL lookahead to an ActiveRecord relation. It keeps query
+types declarative while avoiding unnecessary SQL columns and common N+1 reads.
+
+## Usage
+
+```ruby
+class Types::PersonaType < Types::BaseObject
+  include GraphSQL::Mapping
+
+  graphsql_model Persona
+  graphsql_column :handle
+
+  field :handle, String, null: false
+end
+
+class Types::GameType < Types::BaseObject
+  include GraphSQL::Mapping
+
+  graphsql_model Game
+  graphsql_column :slug
+  graphsql_column :name
+  graphsql_association :owner, to: Types::PersonaType
+
+  field :slug, String, null: false
+  field :name, String, null: false
+  field :owner, Types::PersonaType, null: false
+end
+
+class Types::QueryType < Types::BaseObject
+  field :games, [Types::GameType], null: false, extras: [:lookahead]
+
+  def games(lookahead:)
+    GraphSQL.resolve(Game.all, lookahead: lookahead, type: Types::GameType)
+  end
+end
+```
+
+`GraphSQL.resolve` always selects the model primary key, adds requested mapped
+columns, retains foreign keys required by requested `belongs_to` associations,
+and preloads requested mapped associations. For STI models it also retains the
+inheritance-discriminator column (`type` by default), so rows still
+instantiate as the correct subclass. Unmapped GraphQL fields remain the
+responsibility of their normal resolvers.
+
+Mappings may expose a database attribute or association under another GraphQL
+field name:
+
+```ruby
+graphsql_column :display_name, as: :name
+graphsql_association :organization_memberships, as: :memberships
+```
+
+`graphsql_column`/`required_columns:` must name a real column on the mapped
+model — not a Ruby method, not a virtual `attribute` with no DB backing.
+`GraphSQL.resolve` raises `GraphSQL::UnknownColumnError` naming the type,
+field, and column the moment it's requested, rather than letting a bad name
+reach Arel and fail later as an opaque `ActiveRecord::StatementInvalid`.
+
+## Nested column-limiting (`to:`)
+
+When an association's `to:` target type is itself GraphSQL-mapped, column
+selection recurses: only the fields actually requested on the *nested* object
+get selected on its preload query too, at any depth (`owner { organization {
+name } }` limits columns on both `owner` and its own `organization`).
+
+`to:` accepts a `-> { ... }` proc instead of a bare class for mutually
+associated types that would otherwise have a load-order problem (a `Game`
+type pointing at an `Organization` type that itself points back at `Game`):
+
+```ruby
+graphsql_association :games, to: -> { Types::GameType }
+```
+
+Without a resolvable `to:` (omitted, a class that turns out not to match the
+association's actual target, a polymorphic `belongs_to`, or a `:through`
+association), that one association just falls back to a plain full-row
+preload — the optimization is best-effort per-association; a query mixing a
+nestable and a non-nestable association preloads both correctly, just with
+only the nestable one getting the narrower `SELECT`.
+
+Mapping the *same* underlying association under two different, both-nestable
+GraphQL fields on one type (e.g. `owner`/`employer` both -> `belongs_to
+:organization`) and requesting both in one query raises
+`GraphSQL::AliasedAssociationError` rather than silently applying only one
+alias's column-limited scope to both — the two aliases share a single
+association proxy on the record, so there's no way to preload them
+independently. Only one of the aliased fields, not both, can be requested in
+the same query.
+
+## Pagination / `.count`
+
+`GraphSQL.resolve` always applies a `.select()` covering every mapped column.
+Rails' default `.count` column inference joins every `select_value` into
+`COUNT(col1, col2, ...)`, invalid SQL outside Postgres — so a **bare**
+`.count` on a relation with more than one selected column would normally
+raise `ActiveRecord::StatementInvalid`. A relation returned by
+`GraphSQL.resolve` avoids this: a bare `.count` (no column, no block) counts
+by the primary key instead, since it's always among the selected columns and
+always safe to count. `.count(:some_column)` and `.count { |r| ... }` still
+pass straight through unchanged.
+
+```ruby
+relation.count                         # counts by primary key, safe by default
+relation.count(:id)                    # explicit column still works as normal
+```
+
+This only applies to the `ActiveRecord::Relation` GraphSQL returns directly.
+`GraphSQL.resolve` returns a plain `Array` instead whenever the query also
+selects a nested GraphSQL-mapped association (see "Nested column-limiting"
+above) — `Array#count` has no SQL to generate and is unaffected either way.
+
+Pagination (`.limit`/`.offset`, `geared_pagination`, Kaminari, etc.) still
+belongs on the *pre-resolve* relation, not chained onto `GraphSQL.resolve`'s
+return value — `GraphSQL.resolve` is meant to be the terminal step right
+before returning the field's value.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```

data/lib/graphsql/aliased_association_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GraphSQL
+  # Raised by Resolver#nested_associations when a query requests the same
+  # underlying AR association under two different GraphQL field names (e.g.
+  # `owner`/`employer` both mapped to `belongs_to :organization`), both
+  # resolving to a nestable (`to:`-mapped) target. Both aliases share one
+  # association proxy on the record, and ActiveRecord::Associations::Preloader
+  # skips an association it's already marked loaded — so only the first
+  # alias's column-limited scope actually takes effect, and the second
+  # alias's requested fields silently go missing (up to and including a
+  # MissingAttributeError). Raising here turns that into a loud, immediate
+  # failure instead of a silent one.
+  class AliasedAssociationError < StandardError
+    def self.for_duplicate(type:, association:, fields:)
+      new("#{type} maps association `#{association}` under multiple requested GraphQL fields " \
+          "(#{fields.map(&:inspect).join(', ')}) — GraphQL.resolve can only apply one column-limited " \
+          "preload scope per underlying association per query. Request only one of these fields, or " \
+          "don't map `#{association}` under more than one GraphQL field name.")
+    end
+  end
+end

data/lib/graphsql/mapping.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GraphSQL
+  module Mapping
+    Association = Data.define(:name, :field_name, :type) do
+      # `type:` may be a class or a `-> { ... }` proc (for forward references
+      # between mutually-associated types, e.g. Game <-> Organization).
+      def resolved_type
+        type.respond_to?(:call) ? type.call : type
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def graphsql_model(model = nil)
+        return @graphsql_model = model if model
+
+        @graphsql_model || graphsql_mapping_ancestor&.graphsql_model
+      end
+
+      def graphsql_column(name, as: name)
+        (@graphsql_columns ||= {})[as.to_sym] = name.to_sym
+      end
+
+      def graphsql_association(name, as: name, to: nil)
+        (@graphsql_associations ||= {})[as.to_sym] = Association.new(
+          name: name.to_sym,
+          field_name: as.to_sym,
+          type: to
+        )
+      end
+
+      def graphsql_columns
+        inherited = graphsql_mapping_ancestor&.graphsql_columns || {}
+        inherited.merge(@graphsql_columns || {})
+      end
+
+      def graphsql_associations
+        inherited = graphsql_mapping_ancestor&.graphsql_associations || {}
+        inherited.merge(@graphsql_associations || {})
+      end
+
+      private
+
+      def graphsql_mapping_ancestor
+        superclass if superclass.respond_to?(:graphsql_model)
+      end
+    end
+  end
+end

data/lib/graphsql/resolver.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module GraphSQL
+  class Resolver
+    # A requested association whose target type also declares GraphSQL
+    # mappings, paired with the reflection needed to preload it safely and
+    # the nested lookahead needed to know which of ITS fields were selected.
+    NestedAssociation = Data.define(:mapping, :reflection, :target_type, :lookahead)
+
+    # select_columns always applies a multi-column .select() (primary key +
+    # every mapped column), which makes a *bare* `.count` ambiguous: Rails'
+    # default column inference joins every select_value into `COUNT(col1,
+    # col2, ...)`, invalid SQL outside Postgres. The primary key is always
+    # among those columns and is always a safe, correct thing to count, so a
+    # bare `.count`/`.count(&block)` defaults to it instead of failing —
+    # while `.count(:some_column)` still passes straight through untouched.
+    module CountsByPrimaryKey
+      def count(column_name = nil, &block)
+        return super if column_name || block
+
+        super(klass.primary_key)
+      end
+    end
+
+    def initialize(relation:, lookahead:, type:, required_associations: [], required_columns: [])
+      @relation = relation
+      @lookahead = lookahead
+      @type = type
+      @required_associations = required_associations
+      @required_columns = required_columns
+    end
+
+    def resolve
+      return relation unless supported?(relation, type, lookahead)
+
+      resolve_relation(relation, type, lookahead)
+    end
+
+    private
+
+    attr_reader :relation, :lookahead, :type, :required_associations, :required_columns
+
+    def resolve_relation(source, source_type, source_lookahead)
+      selected = select_columns(source, source_type, source_lookahead, required: required_columns)
+      nested = nested_associations(source, source_type, source_lookahead)
+      nested_names = nested.map { |assoc| assoc.mapping.name }
+      plain_names = association_mappings(source_type, source_lookahead).map(&:name).uniq - nested_names
+      eager_names = (plain_names + required_associations).uniq
+
+      return selected if nested.empty? && eager_names.empty?
+      return selected.includes(*eager_names) if nested.empty?
+
+      # Preloading a *scoped* (column-limited) association requires real
+      # record instances (ActiveRecord::Associations::Preloader operates on
+      # an array, not a relation) — this forces the load a step earlier than
+      # a plain `.includes` would, only when nested optimization applies.
+      records = selected.to_a
+      ActiveRecord::Associations::Preloader.new(records: records, associations: eager_names).call if eager_names.any?
+      preload_nested!(records, nested)
+      records
+    end
+
+    def supported?(source, source_type, source_lookahead)
+      source.is_a?(ActiveRecord::Relation) &&
+        source_type.respond_to?(:graphsql_model) &&
+        source_type.graphsql_model == source.klass &&
+        source_lookahead.respond_to?(:selections)
+    end
+
+    def field_names(source_lookahead)
+      source_lookahead.selections.filter_map do |selection|
+        selection.name.to_sym if selection.respond_to?(:name)
+      end.uniq
+    end
+
+    def association_mappings(source_type, source_lookahead)
+      source_type.graphsql_associations.slice(*field_names(source_lookahead)).values
+    end
+
+    # Requested associations whose target type is itself GraphSQL-mapped and
+    # matches the reflection's actual class, with a real nested lookahead to
+    # drive column selection. Anything else (no `to:`, mismatched `to:`,
+    # polymorphic, `:through`) safely falls back to a plain full-row preload —
+    # optimization is best-effort, correctness never depends on it applying.
+    def nested_associations(source, source_type, source_lookahead)
+      nested = association_mappings(source_type, source_lookahead).filter_map do |mapping|
+        reflection = source.klass.reflect_on_association(mapping.name)
+        next unless reflection
+        next if reflection.polymorphic? || reflection.through_reflection
+
+        target_type = mapping.resolved_type
+        next unless target_type.respond_to?(:graphsql_model)
+        next unless target_type.graphsql_model == reflection.klass
+
+        nested_lookahead = source_lookahead.selection(mapping.field_name)
+        next unless nested_lookahead.respond_to?(:selections)
+
+        NestedAssociation.new(mapping:, reflection:, target_type:, lookahead: nested_lookahead)
+      end
+
+      validate_no_aliased_duplicates!(nested, source_type)
+      nested
+    end
+
+    # Two GraphQL fields mapped to the same underlying association (e.g.
+    # `owner`/`employer` both -> `belongs_to :organization`), both nestable,
+    # both requested in the same query, would otherwise silently share one
+    # preloaded (and column-limited) association proxy — see
+    # AliasedAssociationError for why that loses data instead of erroring.
+    def validate_no_aliased_duplicates!(nested, source_type)
+      nested.group_by { |assoc| assoc.reflection.name }.each_value do |group|
+        next if group.size == 1
+
+        raise AliasedAssociationError.for_duplicate(
+          type: source_type,
+          association: group.first.reflection.name,
+          fields: group.map { |assoc| assoc.mapping.field_name }
+        )
+      end
+    end
+
+    def select_columns(source, source_type, source_lookahead, required: [])
+      names = field_names(source_lookahead)
+      mapped_fields = source_type.graphsql_columns.slice(*names)
+      validate_columns!(mapped_fields, required, source.klass, source_type)
+      mapped = mapped_fields.values
+      fks = association_mappings(source_type, source_lookahead).filter_map do |mapping|
+        reflection = source.klass.reflect_on_association(mapping.name)
+        reflection.foreign_key if reflection&.belongs_to? && !reflection.polymorphic?
+      end
+      required_fks = required_associations.filter_map do |assoc_name|
+        reflection = source.klass.reflect_on_association(assoc_name)
+        reflection.foreign_key if reflection&.belongs_to? && !reflection.polymorphic?
+      end
+      # STI models need their type-discriminator column present in the
+      # SELECT to instantiate the correct subclass — without it, every row
+      # silently comes back as the base class (no error, wrong class).
+      sti_column = source.klass.inheritance_column if source.klass.columns_hash.key?(source.klass.inheritance_column)
+      columns = [source.klass.primary_key, sti_column, *mapped, *fks, *required_fks, *required].compact.map(&:to_s).uniq
+      table = source.klass.arel_table
+
+      source.select(*columns.map { |column| table[column] }).extend(CountsByPrimaryKey)
+    end
+
+    # Fails fast and legibly instead of letting a nonexistent column reach
+    # Arel, where it would only surface once the query executes as a raw
+    # ActiveRecord::StatementInvalid with no mention of GraphSQL, the
+    # GraphQL type, or which field caused it.
+    def validate_columns!(mapped_fields, required, model, source_type)
+      known = model.column_names
+
+      mapped_fields.each do |field, column|
+        next if known.include?(column.to_s)
+
+        raise UnknownColumnError.for_mapped_column(type: source_type, field: field, column: column, model: model)
+      end
+
+      required.each do |column|
+        next if known.include?(column.to_s)
+
+        raise UnknownColumnError.for_required_column(column: column, model: model)
+      end
+    end
+
+    def preload_nested!(records, nested)
+      return if records.empty?
+
+      nested.each do |assoc|
+        scope = nested_scope(assoc)
+
+        ActiveRecord::Associations::Preloader.new(
+          records: records,
+          associations: assoc.mapping.name,
+          scope: scope
+        ).call
+
+        child_records = records.flat_map { |record| Array(record.public_send(assoc.mapping.name)) }
+        preload_nested!(child_records, nested_associations(scope, assoc.target_type, assoc.lookahead))
+      end
+    end
+
+    # belongs_to's join key lives on the *requesting* side (already selected
+    # by select_columns' `fks`, above) so the child scope needs nothing extra.
+    # has_many/has_one's join key lives on the *child* table — the preloader
+    # groups loaded children by that column, so it must be selected even
+    # though it's never GraphQL-mapped, or every association silently
+    # resolves empty (confirmed: this is not a hypothetical — see the
+    # has_many test coverage for the exact failure mode without it).
+    def nested_scope(assoc)
+      required = assoc.reflection.belongs_to? ? [] : [assoc.reflection.foreign_key]
+      select_columns(assoc.target_type.graphsql_model.all, assoc.target_type, assoc.lookahead, required: required)
+    end
+  end
+end

data/lib/graphsql/unknown_column_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GraphSQL
+  # Raised by Resolver#select_columns when a graphsql_column/required_columns:
+  # entry names something that isn't an actual column on the model — a plain
+  # Ruby method, a virtual `attribute` with no DB backing, or a typo. Without
+  # this check the same mistake surfaced as a raw
+  # ActiveRecord::StatementInvalid ("no such column: ...") from deep inside
+  # Arel/the SQL driver, with nothing pointing back at the offending
+  # graphsql_column call.
+  class UnknownColumnError < StandardError
+    def self.for_mapped_column(type:, field:, column:, model:)
+      new("#{type}'s graphsql_column #{field.inspect} maps to `#{column}`, " \
+          "but #{model} has no such column")
+    end
+
+    def self.for_required_column(column:, model:)
+      new("required_columns: referenced `#{column}`, but #{model} has no such column")
+    end
+  end
+end

data/lib/graphsql/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GraphSQL
+  VERSION = "0.4.0"
+end

data/lib/graphsql.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/core_ext/hash/slice"
+
+require_relative "graphsql/version"
+require_relative "graphsql/mapping"
+require_relative "graphsql/unknown_column_error"
+require_relative "graphsql/aliased_association_error"
+require_relative "graphsql/resolver"
+
+module GraphSQL
+  # `required_associations:`/`required_columns:` name associations/columns
+  # the caller needs loaded regardless of what the client requested (e.g. a
+  # model's #discussion reading title/body and persona.handle to
+  # find_or_open a thread, even when the query didn't ask for those
+  # fields). Passing these through here, rather than chaining
+  # `.select`/`.includes` onto the return value, is required for
+  # correctness: #resolve returns a plain Array (not a Relation — see
+  # Resolver#resolve_relation) whenever the query also requests a nested
+  # GraphQL-mapped association, and a caller-side `.select`/`.includes`
+  # chained after the call silently breaks the moment that happens.
+  def self.resolve(relation, lookahead:, type:, required_associations: [], required_columns: [])
+    Resolver.new(
+      relation: relation, lookahead: lookahead, type: type,
+      required_associations: required_associations, required_columns: required_columns
+    ).resolve
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: graphsql
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Dot Matrix
+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: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !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: 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: Selects mapped ActiveRecord columns and preloads mapped associations
+  from GraphQL lookaheads.
+email:
+- matrix9180@proton.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/graphsql.rb
+- lib/graphsql/aliased_association_error.rb
+- lib/graphsql/mapping.rb
+- lib/graphsql/resolver.rb
+- lib/graphsql/unknown_column_error.rb
+- lib/graphsql/version.rb
+homepage: https://gitlab.com/maqstaq/graphsql
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://gitlab.com/maqstaq/graphsql
+  bug_tracker_uri: https://gitlab.com/maqstaq/graphsql/-/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: GraphQL lookahead mapping for ActiveRecord relations.
+test_files: []