graphsql 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cf0933b75d22d60adbda095d91985202111a72476a1d418b9b6b6c19a9e26c3
-  data.tar.gz: dc5823be1f0741913aa1166be8c4826bd7744623d5fd578457a1cc252ec0b58d
+  metadata.gz: 7a69af6d7f58b9a71a39a4e760de0505dddad7311298f71bb9447d4635718eb5
+  data.tar.gz: 4edaf48b75cdb861eb37203c889fd2bea8bc2c945e8283ccfc6b2a514ff334c0
 SHA512:
-  metadata.gz: d55b842c33c1bebdfdaec2cf0fe8939f2ac7daebac8d61e4c1c85cd57b10120fec5acb7e937ffbfb50c73cc23055e94a2df3ecd009ab40dcd8a88d5f9b4c0356
-  data.tar.gz: 76c2e45232b2ee3788cb313394f8263be8a51f94e9bc257a9f0275ac1e2e1e3aaaee3386173217632d0923adbcb407ff33827e0f4a09e5efe2e5f92ec3b39f80
+  metadata.gz: 15997387c5c563f5aab7ffee76305ebbb2730b129ccb0609e91b916983fc78f532ea16409b059f2673790c4f4e0467f2f46a1043da58a68297fa6062b0122c49
+  data.tar.gz: 1dfe67fcb6353a3a32ef3622e192c6cdff64c065f064298318b80ffa96fbf69fcdc9f175eb7ef58e9574a026d249aedf68e260609064d69d261accb8696caed3

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this gem are documented here. Loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions before
+0.4.0 were never published to rubygems.org — this repo graduated out of the
+MaqStaq monorepo (full commit history preserved) ahead of the first real
+release. See `ROADMAP.md` for the full writeup behind each fix below,
+including how it was confirmed and what was checked and ruled out.
+
+## [0.5.1] - 2026-07-31
+
+### Changed
+
+- Friendlier gemspec `summary`/`description` — the old description read like
+  an internal code comment ("Selects mapped ActiveRecord columns and
+  preloads mapped associations from GraphQL lookaheads.").
+
+### Infrastructure
+
+- Added `.gitlab-ci.yml` (test suite, `gem build` sanity check,
+  SAST/secret-detection) — nothing ran this gem's tests automatically since
+  it graduated out of the monorepo's own CI matrix.
+
+## [0.5.0] - 2026-07-31
+
+### Added
+
+- `rails generate graphsql:type ModelName` generator: introspects an
+  already-migrated model's real columns/associations and scaffolds a
+  matching type (`graphsql_column`/`graphsql_association`/`field` for each,
+  a `lookahead:`-driven resolver method for collection associations), and
+  wires a matching collection field/resolver into the app's query type.
+  See README "Generator".
+
+## [0.4.0] - 2026-07-30
+
+### Changed
+
+- Gem package name renamed from `GraphSQL` to `graphsql`, matching rubygems
+  convention (`graphql`/`GraphQL`, `activerecord`/`ActiveRecord` are all
+  lowercase packages with capitalized Ruby modules). The `GraphSQL` Ruby
+  module is unchanged. Breaking for any Gemfile still referencing the old
+  capitalized package name.
+
+## [0.3.3] - 2026-07-30
+
+### Fixed
+
+- Mapping the same underlying association under two nestable GraphQL field
+  aliases on one type (e.g. `owner`/`employer` both -> `belongs_to
+  :organization`) no longer silently applies only one alias's column-limited
+  scope to both, dropping the other alias's requested fields. Now raises
+  `GraphSQL::AliasedAssociationError` immediately instead.
+
+## [0.3.2] - 2026-07-30
+
+### Added
+
+- `graphsql_column`/`required_columns:` referencing something that isn't a
+  real column on the model (a typo, a Ruby method, a virtual `attribute`
+  with no DB backing) now raises `GraphSQL::UnknownColumnError` naming the
+  type, field, and column — instead of a raw `ActiveRecord::StatementInvalid`
+  surfacing later, deep in Arel, once a query actually requested that field.
+
+## [0.3.1] - 2026-07-30
+
+### Fixed
+
+- Single-table inheritance models now retain their `inheritance_column` in
+  the generated `SELECT`, so rows instantiate as the correct subclass.
+  Previously every row silently came back as the STI base class, with no
+  error at all.
+
+## [0.3.0] - 2026-07-30
+
+### Fixed
+
+- A bare `.count` on a relation returned by `GraphSQL.resolve` no longer
+  raises `ActiveRecord::StatementInvalid` (Rails' default `.count` column
+  inference builds an invalid multi-column `COUNT(...)` once more than one
+  column is selected, which every `GraphSQL.resolve`'d relation has). It now
+  counts by the primary key by default; `.count(:column)` and
+  `.count { |r| ... }` still pass through unchanged.
+
+## [0.2.0] - 2026-07-25
+
+### Fixed
+
+- `graphsql_association`'s `to:` is now actually consulted for nested
+  column-limiting, recursing at arbitrary depth (`owner { organization {
+  name } }`) instead of only ever optimizing the top-level type's columns.
+- `has_many` column-limiting no longer silently returns an empty association
+  array when the child-side foreign key isn't itself GraphQL-mapped.
+- A plain (non-nestable) association requested alongside a nestable one on
+  the same type is no longer dropped from preloading.
+
+## [0.1.0] - 2026-07-14
+
+Initial version, added to the MaqStaq monorepo.

data/README.md

@@ -1,9 +1,32 @@
 # GraphSQL
 
+[![Gem Version](https://badge.fury.io/rb/graphsql.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/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.
 
+## Installation
+
+Published on [rubygems.org](https://rubygems.org/gems/graphsql) as `graphsql`
+(the Ruby module is `GraphSQL`, capitalized — only the package name is
+lowercase, matching the `graphql`/`GraphQL` and `activerecord`/`ActiveRecord`
+convention). Add it to your Gemfile:
+
+```ruby
+gem "graphsql"
+```
+
+```bash
+bundle install
+```
+
+Or without Bundler:
+
+```bash
+gem install graphsql
+```
+
 ## Usage
 
 ```ruby
@@ -117,6 +140,52 @@ 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.
 
+## Generator
+
+In a Rails app, `rails generate graphsql:type ModelName` introspects an
+**already-migrated** model's real columns and associations and scaffolds a
+matching type — this reads the live schema via ActiveRecord, it doesn't
+guess from a migration file, so create the model (and run its migration)
+first:
+
+```bash
+rails generate graphsql:type Persona
+```
+
+This writes `app/graphql/types/persona_type.rb` with a `graphsql_column` +
+`field` pair for every real column (skipping the primary key, the STI
+discriminator column if any, and `belongs_to` foreign key columns — those
+are exposed through the association's own field instead), and a
+`graphsql_association` + `field` pair for every association, guessing
+`to: Types::<TargetClass>Type` for every non-polymorphic one. Collection
+(`has_many`) associations also get a `lookahead:`-driven resolver method;
+`belongs_to`/`has_one` don't need one — they're preloaded by whatever calls
+`GraphSQL.resolve` on the *containing* type, and graphql-ruby just reads
+`object.<association>` by convention.
+
+It also wires a matching collection field + resolver into your query type
+(`app/graphql/types/query_type.rb` by default), via Thor's
+`inject_into_class` — it lands right after the class's opening line, not
+necessarily grouped with existing `field` calls, since that's as precise as
+text injection gets. Review the diff.
+
+Options:
+
+```bash
+rails generate graphsql:type Persona --type-namespace=GraphQL::Types  # default: Types
+rails generate graphsql:type Persona --base-class=Types::BaseNode     # default: "<type_namespace>::BaseObject"
+rails generate graphsql:type Persona --query-type-path=app/graphql/types/root_query.rb
+rails generate graphsql:type Persona --query-type-class-name=RootQuery # default: QueryType
+rails generate graphsql:type Persona --skip-query                     # only generate the type, don't touch the query type
+```
+
+A polymorphic association gets a `graphsql_association` line with no `to:`
+(matching the gem's own documented fallback) but no `field`/resolver —
+there's no single GraphQL type to point at without a Union/Interface, add
+that by hand. Everything else the generator can't confidently guess is
+meant to be edited afterward, not configured away — it's a starting point,
+not a promise of a finished type.
+
 ## Development
 
 ```bash

data/lib/generators/graphsql/type/templates/type.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module <%= type_namespace %>
+  class <%= class_name %>Type < <%= base_class %>
+    include GraphSQL::Mapping
+
+    graphsql_model <%= model_class.name %>
+<% mapped_columns.each do |column| -%>
+    graphsql_column :<%= column.name %>
+<% end -%>
+<% mapped_associations.each do |assoc| -%>
+<% if assoc.to_type -%>
+    graphsql_association :<%= assoc.name %>, to: <%= assoc.to_type %>
+<% else -%>
+    graphsql_association :<%= assoc.name %> # polymorphic — no single GraphQL type to guess; map/field this by hand
+<% end -%>
+<% end -%>
+
+    field :id, ID, null: false
+<% mapped_columns.each do |column| -%>
+    field :<%= column.name %>, <%= column.graphql_type %>, null: <%= column.nullable %>
+<% end -%>
+<% mapped_associations.each do |assoc| -%>
+<% next unless assoc.to_type -%>
+    field :<%= assoc.name %>, <%= association_field_type(assoc) %>, null: <%= assoc.nullable %><%= assoc.collection ? ", extras: [:lookahead]" : "" %>
+<% end -%>
+<% if resolver_associations.any? -%>
+
+<% resolver_associations.each do |assoc| -%>
+    def <%= assoc.name %>(lookahead:)
+      GraphSQL.resolve(object.<%= assoc.name %>, lookahead: lookahead, type: <%= assoc.to_type %>)
+    end
+<% end -%>
+<% end -%>
+  end
+end

data/lib/generators/graphsql/type/type_generator.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+
+module GraphSQL
+  module Generators
+    # rails generate graphsql:type Persona
+    #
+    # Introspects an already-migrated ActiveRecord model's columns and
+    # associations and emits a matching GraphSQL::Mapping type — every
+    # column gets a graphsql_column + field pair, every association gets a
+    # graphsql_association + field pair (plus a lookahead-driven resolver
+    # method for collection associations), and `to:` is guessed for every
+    # non-polymorphic association as "<type_namespace>::<TargetClass>Type".
+    # Also wires a matching collection field + resolver into the app's query
+    # type via Thor's inject_into_class, unless --skip-query.
+    #
+    # This only works against a model whose table already exists — it reads
+    # real column/association metadata via ActiveRecord, it doesn't infer
+    # anything from a migration file. Generate the model (and run its
+    # migration) first, then generate its type.
+    class TypeGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      MappedColumn = Data.define(:name, :graphql_type, :nullable)
+      MappedAssociation = Data.define(:name, :to_type, :collection, :nullable)
+
+      SCALAR_TYPES = {
+        "string" => "String", "text" => "String", "citext" => "String",
+        "integer" => "Integer", "bigint" => "Integer",
+        "float" => "Float", "decimal" => "Float",
+        "boolean" => "Boolean",
+        "date" => "GraphQL::Types::ISO8601Date",
+        "datetime" => "GraphQL::Types::ISO8601DateTime", "timestamp" => "GraphQL::Types::ISO8601DateTime",
+        "json" => "GraphQL::Types::JSON", "jsonb" => "GraphQL::Types::JSON"
+      }.freeze
+
+      class_option :type_namespace, type: :string, default: "Types",
+        desc: "Module namespace the generated type (and guessed association `to:` types) live under"
+      class_option :base_class, type: :string, default: nil,
+        desc: 'Base class for the generated type (default: "<type_namespace>::BaseObject")'
+      class_option :query_type_path, type: :string, default: "app/graphql/types/query_type.rb",
+        desc: "Path to the query type file to wire a collection field/resolver into"
+      class_option :query_type_class_name, type: :string, default: "QueryType",
+        desc: "Unqualified class name inject_into_class matches inside --query-type-path"
+      class_option :skip_query, type: :boolean, default: false,
+        desc: "Only generate the type file — don't touch the query type"
+
+      def create_type_file
+        template "type.rb.tt", File.join("app/graphql/types", "#{file_name}_type.rb")
+      end
+
+      def add_query_field
+        return if options[:skip_query]
+
+        unless File.exist?(File.join(destination_root, query_type_path))
+          say_status :skip,
+            "#{query_type_path} not found (pass --query-type-path or add the field by hand)", :yellow
+          return
+        end
+
+        inject_into_class query_type_path, options[:query_type_class_name], query_field_snippet
+      end
+
+      private
+
+      def model_class
+        @model_class ||= class_name.constantize
+      rescue NameError
+        raise Thor::Error,
+          "graphsql:type couldn't load a `#{class_name}` model — make sure the model class and its " \
+          "migration exist before generating its type (this generator introspects the real schema, " \
+          "it doesn't guess from a migration file)"
+      end
+
+      def type_namespace
+        options[:type_namespace]
+      end
+
+      def base_class
+        options[:base_class] || "#{type_namespace}::BaseObject"
+      end
+
+      def query_type_path
+        options[:query_type_path]
+      end
+
+      def guessed_type_for(klass)
+        "#{type_namespace}::#{klass.name}Type"
+      end
+
+      # Every non-PK, non-STI-discriminator, non-belongs_to-foreign-key
+      # column on the model — those three are either handled automatically
+      # by GraphSQL.resolve (PK, STI column) or exposed through the
+      # association's own field instead of as a raw id/type scalar (FK).
+      def mapped_columns
+        @mapped_columns ||= begin
+          belongs_to_fks = model_class.reflect_on_all_associations(:belongs_to).flat_map do |reflection|
+            reflection.polymorphic? ? [reflection.foreign_key, reflection.foreign_type] : [reflection.foreign_key]
+          end
+          skip = Set.new(belongs_to_fks) << model_class.primary_key << sti_column_name
+
+          model_class.columns.reject { |column| skip.include?(column.name) }.map do |column|
+            MappedColumn.new(
+              name: column.name.to_sym,
+              graphql_type: SCALAR_TYPES.fetch(column.type.to_s, "String"),
+              nullable: column.null
+            )
+          end
+        end
+      end
+
+      def sti_column_name
+        model_class.inheritance_column if model_class.columns_hash.key?(model_class.inheritance_column)
+      end
+
+      # `to:` is guessable for every association except polymorphic ones
+      # (no single target class to point at — reflection.klass itself would
+      # raise). :through associations still get a normal `to:` guess: the
+      # gem's own resolver already falls back to a plain full-row preload
+      # for :through on its own (see lib/graphsql/resolver.rb), so mapping
+      # one here is harmless, not incorrect.
+      def mapped_associations
+        @mapped_associations ||= model_class.reflect_on_all_associations.map do |reflection|
+          MappedAssociation.new(
+            name: reflection.name,
+            to_type: reflection.polymorphic? ? nil : guessed_type_for(reflection.klass),
+            collection: reflection.collection?,
+            nullable: association_nullable?(reflection)
+          )
+        end
+      end
+
+      def association_nullable?(reflection)
+        case reflection.macro
+        when :belongs_to then reflection.options[:optional] == true
+        when :has_one then true
+        else false # has_many: empty array, never null itself
+        end
+      end
+
+      def association_field_type(assoc)
+        assoc.collection ? "[#{assoc.to_type}]" : assoc.to_type
+      end
+
+      # Collection associations need their own lookahead-driven resolver
+      # method to apply column-limiting to what THEY return — belongs_to/
+      # has_one are already preloaded (full or column-limited) by the
+      # parent's own GraphSQL.resolve call and need no method of their own,
+      # graphql-ruby just calls object.<name> by convention.
+      def resolver_associations
+        mapped_associations.select { |assoc| assoc.collection && assoc.to_type }
+      end
+
+      def query_field_name
+        file_name.pluralize
+      end
+
+      def query_field_snippet
+        namespaced_type = guessed_type_for(model_class)
+        <<~RUBY
+
+          field :#{query_field_name}, [#{namespaced_type}], null: false, extras: [:lookahead]
+
+          def #{query_field_name}(lookahead:)
+            GraphSQL.resolve(#{model_class.name}.all, lookahead: lookahead, type: #{namespaced_type})
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/graphsql/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphsql
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Dot Matrix
@@ -93,16 +93,35 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Selects mapped ActiveRecord columns and preloads mapped associations
-  from GraphQL lookaheads.
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Map your GraphQL type's fields to ActiveRecord columns and associations,
+  and GraphSQL turns each query's actual field selection into a right-sized SELECT
+  and preload automatically — no more guessing which columns and associations a resolver
+  needs to load.
 email:
 - matrix9180@proton.me
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/graphsql/type/templates/type.rb.tt
+- lib/generators/graphsql/type/type_generator.rb
 - lib/graphsql.rb
 - lib/graphsql/aliased_association_error.rb
 - lib/graphsql/mapping.rb
@@ -115,6 +134,7 @@ licenses:
 metadata:
   source_code_uri: https://gitlab.com/maqstaq/graphsql
   bug_tracker_uri: https://gitlab.com/maqstaq/graphsql/-/issues
+  changelog_uri: https://gitlab.com/maqstaq/graphsql/-/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -131,5 +151,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: GraphQL lookahead mapping for ActiveRecord relations.
+summary: Turn a GraphQL query's field selection into a right-sized ActiveRecord query.
 test_files: []