lighthouse-graphql 0.5.0 → 0.7.0

data/sig/lighthouse/directives.rbs

@@ -36,9 +36,17 @@ module Lighthouse
       include Directive
     end
 
+    # Its instances, built with (arg_node, directive_node), answer
+    # `manipulate_arg_definition(document_ast, field_node, type_node)` with the argument node.
     module ArgManipulator
       include Directive
     end
+
+    # Its instances, built with (field_node, directive_node), answer
+    # `handle_field_builder(relation)` with the constrained relation.
+    module FieldBuilder
+      include Directive
+    end
   end
 
   class DirectiveRegistry
@@ -67,6 +75,9 @@ module Lighthouse
     def resolution_names: () -> Array[String]
     def arg_builder_class: (String | Symbol name) -> Class?
     def arg_builder_names: () -> Array[String]
+    def arg_manipulator_class: (String | Symbol name) -> Class?
+    def arg_manipulator_classes: () -> Array[Class]
+    def field_builder_class: (String | Symbol name) -> Class?
 
     # { "name" => "directive @name(...) on ..." }
     def directive_definitions: () -> Hash[String, String]
@@ -83,9 +94,11 @@ module Lighthouse
     PROGRAMMATIC_TYPES_FILE: String
 
     # Writes both files into `output_dir` and returns their paths.
-    def self?.write: (output_dir: path, ?sdl_folder: path?, ?registry: DirectiveRegistry) -> Array[String]
+    def self?.write: (output_dir: path, ?schema_path: path?, ?registry: DirectiveRegistry) -> Array[String]
+    # Config.ide_helper's rewrite, on boot and every reload.
+    def self?.refresh: (?output_dir: path) -> Array[String]
     def self?.directives_sdl: (?String sdl, ?registry: DirectiveRegistry) -> String
-    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry) -> String
+    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry, ?directives: String) -> String
   end
 
   module GraphQL
@@ -107,7 +120,7 @@ module Lighthouse
         # `ctx`: the query's context, which @builder on an argument receives.
         def apply_where_filters: (relation relation, untyped args, ?context? ctx) -> relation
         def apply_arg_builders: (relation relation, arguments args_h, ?context? ctx) -> relation
-        def extract_relation_name_from_directive: (untyped arg_node) -> String?
+        def apply_field_builders: (relation relation, ?arguments args_h, ?context? ctx) -> relation
         def constantize_model: (String? name) -> Class?
         def apply_scopes: (relation relation) -> relation
 

data/sig/lighthouse/graphql.rbs

@@ -9,16 +9,60 @@ module Lighthouse
     type schema = untyped
 
     module RbLightHouse
-      # The schema built from the SDL in `sdl_folder` (default: Config.sdl_folder).
+      # The schema built from the SDL `schema_path` (default: Config.schema_path) and its imports.
       # `options` takes :base_types, :base_schema and the schema's own options.
-      def self.get_schema: (?sdl_folder: path?, ?options: Hash[Symbol, untyped]) -> schema
+      def self.get_schema: (?schema_path: path?, ?options: Hash[Symbol, untyped]) -> schema
       def self.configure: () ?{ (singleton(Lighthouse::Config) config) -> void } -> void
     end
 
     module SchemaFactory
-      def self?.build_base_schema: (?sdl_folder: path?, ?sdl: String?, ?base_types: Hash[untyped, untyped],
+      def self?.build_base_schema: (?schema_path: path?, ?sdl: String?, ?base_types: Hash[untyped, untyped],
                                     ?schema_options: Hash[Symbol, untyped], **untyped extra_options) -> schema
-      def self?.load_sdl: (path? sdl_folder) -> String
+      def self?.load_sdl: (?path? schema_path) -> String
+    end
+
+    # Reads the schema from its entrypoint, pasting in what it #imports.
+    class SchemaStitcher
+      IMPORT: String
+
+      attr_reader root_schema_path: String
+
+      def initialize: (path root_schema_path) -> void
+      def schema_string: () -> String
+      # Every file the schema is read from, the entrypoint first.
+      def files: () -> Array[String]
+    end
+
+    # The schema document the manipulation phase works on: each type defined once.
+    class DocumentAST
+      KEYWORDS: Hash[Class, String]
+      EXTENSIONS: Array[Class]
+
+      attr_reader types: Hash[String, untyped]
+      attr_reader type_extensions: Hash[String, Array[untyped]]
+      attr_reader directives: Hash[String, untyped]
+      attr_reader schema_definitions: Array[untyped]
+
+      def self.from_source: (String sdl) -> DocumentAST
+      def self.from_document: (untyped document) -> DocumentAST
+
+      def initialize: () -> void
+      def add: (untyped definition) -> untyped
+      # Adds a type, or replaces the one of the same name.
+      def put_type: (untyped definition) -> self
+      # Adds the type parsed from the SDL (or the block's), unless one of the name exists.
+      def define_type: (String name, ?String? sdl) ?{ () -> String } -> untyped
+      def type?: (String name) -> bool
+      def type_names: () -> Array[String]
+      def to_document: () -> untyped
+      def to_sdl: () -> String
+    end
+
+    # The manipulation phase: extensions merged, then the type, field and argument manipulators.
+    module ASTBuilder
+      ROOT_TYPES: Array[String]
+
+      def self?.build: (String sdl, ?registry: DirectiveRegistry) -> String
     end
 
     # Apollo's Automatic Persisted Queries, and a manifest of trusted operations.

data/sig/lighthouse.rbs

@@ -45,12 +45,6 @@ module Lighthouse
     def decode: (String global_id) -> Array[String]
   end
 
-  # Config.upload_store: stores the file an @upload argument carries, and returns
-  # what the argument holds instead (an ActiveStorage blob's signed id by default).
-  interface _UploadStore
-    def call: (untyped file, ?disk: String?, ?path: String?, ?public: bool?) -> untyped
-  end
-
   # Config.authenticated_user and Config.policy_user: the user of a request.
   interface _UserReader
     def call: (context? context) -> untyped
@@ -98,8 +92,14 @@ module Lighthouse
     def self.[]: (Symbol | String key) -> untyped
     def self.reset!: () -> void
 
-    def self.sdl_folder: () -> path?
-    def self.sdl_folder=: (path? folder) -> path?
+    # The schema's entrypoint, which imports the other files (SchemaStitcher).
+    def self.schema_path: () -> path?
+    def self.schema_path=: (path? path) -> path?
+    def self.schema_directory: () -> String?
+
+    # Rewrite the IDE helper files on boot and every reload; nil: in development with a graphql.config.yml.
+    def self.ide_helper: () -> bool?
+    def self.ide_helper=: (bool? enabled) -> bool?
 
     # { queries:, mutations:, subscriptions:, builders:, validators:, events: } => [namespace, ...].
     # Assigning a partial hash overrides only the kinds it names.
@@ -112,8 +112,6 @@ module Lighthouse
     def self.directive_map: () -> Hash[untyped, untyped]
 
     # An ActiveSupport::Cache::Store; Rails.cache by default.
-    def self.cache_store: () -> untyped
-    def self.cache_store=: (untyped store) -> untyped
 
     def self.transactional_mutations: () -> bool
     def self.transactional_mutations=: (bool? enabled) -> bool?
@@ -147,8 +145,6 @@ module Lighthouse
     def self.global_id: () -> _GlobalId
     def self.global_id=: (_GlobalId? codec) -> _GlobalId?
 
-    def self.upload_store: () -> _UploadStore
-    def self.upload_store=: (_UploadStore? store) -> _UploadStore?
 
     # Whether @broadcast triggers in an ActiveJob (Lighthouse::GraphQL::BroadcastJob)
     # unless the directive says shouldQueue; and the job's queue (nil: ActiveJob's default).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Vaz Innovation
@@ -70,6 +70,7 @@ files:
 - docs/relationships.md
 - docs/relay.md
 - docs/resolvers.md
+- docs/schema-organisation.md
 - docs/security.md
 - docs/subscriptions.md
 - docs/types.md
@@ -78,17 +79,16 @@ files:
 - lib/generators/lighthouse/base_classes.rb
 - lib/generators/lighthouse/builder_generator.rb
 - lib/generators/lighthouse/class_generator.rb
+- lib/generators/lighthouse/install/graphql_ruby_install.rb
 - lib/generators/lighthouse/install/install_generator.rb
 - lib/generators/lighthouse/install/templates/graphql.config.yml.tt
 - lib/generators/lighthouse/install/templates/graphql_controller.rb.tt
 - lib/generators/lighthouse/install/templates/initializer.rb.tt
 - lib/generators/lighthouse/install/templates/schema.graphql.tt
-- lib/generators/lighthouse/install/templates/schema.rb.tt
-- lib/generators/lighthouse/mutation_generator.rb
-- lib/generators/lighthouse/query_generator.rb
 - lib/generators/lighthouse/subscription_generator.rb
 - lib/generators/lighthouse/validator_generator.rb
 - lib/lighthouse-graphql.rb
+- lib/lighthouse/ast_builder.rb
 - lib/lighthouse/async_mutation_job.rb
 - lib/lighthouse/broadcast_job.rb
 - lib/lighthouse/broadcasting.rb
@@ -100,6 +100,7 @@ files:
 - lib/lighthouse/contracts/arg_builder.rb
 - lib/lighthouse/contracts/arg_manipulator.rb
 - lib/lighthouse/contracts/directive.rb
+- lib/lighthouse/contracts/field_builder.rb
 - lib/lighthouse/contracts/field_manipulator.rb
 - lib/lighthouse/contracts/field_middleware.rb
 - lib/lighthouse/contracts/field_resolver.rb
@@ -145,7 +146,6 @@ files:
 - lib/lighthouse/directive_resolvers/throttle_resolver.rb
 - lib/lighthouse/directive_resolvers/type_method_resolver.rb
 - lib/lighthouse/directive_resolvers/validator_resolver.rb
-- lib/lighthouse/directive_resolvers/where_conditions_applier.rb
 - lib/lighthouse/directive_resolvers/with_count_resolver.rb
 - lib/lighthouse/directive_resolvers/with_resolver.rb
 - lib/lighthouse/directives/arguments/base.rb
@@ -153,7 +153,11 @@ files:
 - lib/lighthouse/directives/arguments/more_filters.rb
 - lib/lighthouse/directives/arguments/order_by.rb
 - lib/lighthouse/directives/arguments/soft_deletes.rb
+- lib/lighthouse/directives/arguments/where_conditions.rb
+- lib/lighthouse/directives/arguments/where_conditions_base.rb
+- lib/lighthouse/directives/arguments/where_has_conditions.rb
 - lib/lighthouse/directives/definitions.rb
+- lib/lighthouse/directives/generated_types.rb
 - lib/lighthouse/directives/model_directive.rb
 - lib/lighthouse/directives/node_directive.rb
 - lib/lighthouse/directives/pagination_info_types.rb
@@ -161,7 +165,7 @@ files:
 - lib/lighthouse/directives/registry.rb
 - lib/lighthouse/directives/soft_deletes_directive.rb
 - lib/lighthouse/directives/visibility_directive.rb
-- lib/lighthouse/directives/where_conditions_directive.rb
+- lib/lighthouse/document_ast.rb
 - lib/lighthouse/enum_directive.rb
 - lib/lighthouse/errors.rb
 - lib/lighthouse/events.rb
@@ -186,6 +190,7 @@ files:
 - lib/lighthouse/nested_mutations/many_to_many_operations.rb
 - lib/lighthouse/nested_mutations/partitioner.rb
 - lib/lighthouse/node_registry.rb
+- lib/lighthouse/order_by/types.rb
 - lib/lighthouse/pagination.rb
 - lib/lighthouse/persisted_queries.rb
 - lib/lighthouse/persisted_queries/batch.rb
@@ -197,12 +202,13 @@ files:
 - lib/lighthouse/resolve_info.rb
 - lib/lighthouse/resolver_bases.rb
 - lib/lighthouse/resolver_dispatch.rb
+- lib/lighthouse/root_types.rb
 - lib/lighthouse/scalar_coercion.rb
 - lib/lighthouse/schema_cache.rb
 - lib/lighthouse/schema_factory.rb
 - lib/lighthouse/schema_generator.rb
 - lib/lighthouse/schema_implementation.rb
-- lib/lighthouse/sdl_loader.rb
+- lib/lighthouse/schema_stitcher.rb
 - lib/lighthouse/subscription.rb
 - lib/lighthouse/support/arguments.rb
 - lib/lighthouse/support/authorization.rb
@@ -218,7 +224,11 @@ files:
 - lib/lighthouse/type_resolution.rb
 - lib/lighthouse/upload.rb
 - lib/lighthouse/upload_store.rb
+- lib/lighthouse/where_conditions/columns.rb
+- lib/lighthouse/where_conditions/handler.rb
+- lib/lighthouse/where_conditions/json_column.rb
 - lib/lighthouse/where_conditions/operator_map.rb
+- lib/lighthouse/where_conditions/types.rb
 - sig/lighthouse.rbs
 - sig/lighthouse/controller.rbs
 - sig/lighthouse/directives.rbs

data/lib/generators/lighthouse/install/templates/schema.rb.tt

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# Executable schema built by Lighthouse from the SDL in <%= sdl_folder %>/. The
-# Dataloader batches relationship loads (@hasMany, @belongsTo, ...) to avoid N+1.
-# base_types names the base classes: every class a Query, Mutation or Subscription
-# field resolves to must inherit from its kind's, and a Subscription field with no
-# class of its own resolves with the subscription one. graphql-ruby builds the
-# SDL's types from the others (written by `rails g graphql:install`), and type
-# classes (Types::PostType, Types::DateTimeType, ...) inherit from them.
-<%= schema_name %> = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  options: {
-    using: { GraphQL::Dataloader => {} },
-    base_types: {
-      resolver: <%= base_class_constant(:queries) %>,
-      mutation: <%= base_class_constant(:mutations) %>,
-      subscription: <%= base_class_constant(:subscriptions) %>,
-      object: Types::BaseObject,
-      interface: Types::BaseInterface,
-      union: Types::BaseUnion,
-      scalar: Types::BaseScalar,
-      enum: Types::BaseEnum,
-      input_object: Types::BaseInputObject
-    }
-  }
-)
-
-# Refuse expensive queries before they run (see the gem's docs/security.md):
-# <%= schema_name %>.max_complexity(300)
-# <%= schema_name %>.max_depth(12)

data/lib/generators/lighthouse/mutation_generator.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'class_generator'
-
-# `rails generate lighthouse:mutation PublishPost` — the class (a
-# Mutations::BaseMutation, so a GraphQL::Schema::Mutation) that `Mutation.publishPost`
-# resolves to by convention.
-class Lighthouse::Generators::MutationGenerator < Lighthouse::Generators::ClassGenerator
-  desc 'Generate the class of a Mutation field (a Mutations::BaseMutation) in app/graphql/mutations.'
-
-  private
-
-  def kind = :mutations
-
-  def body
-    <<~RUBY
-      # Resolves Mutation.#{class_basename.camelize(:lower)}. Keyword arguments are the field's
-      # arguments in snake_case; `object` and `context` are available. Raise
-      # GraphQL::ExecutionError for failures the client should see.
-      class #{class_basename} < #{superclass_name}
-        def resolve(**args)
-          raise NotImplementedError
-        end
-      end
-    RUBY
-  end
-
-  def usage
-    "Mutation.#{class_basename.camelize(:lower)} resolves to #{full_class_name} — add the field to your SDL without a resolving directive."
-  end
-end

data/lib/generators/lighthouse/query_generator.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'class_generator'
-
-# `rails generate lighthouse:query LatestPosts` — the resolver (a
-# Resolvers::BaseResolver, so a GraphQL::Schema::Resolver) that `Query.latestPosts`
-# resolves to by convention.
-class Lighthouse::Generators::QueryGenerator < Lighthouse::Generators::ClassGenerator
-  desc 'Generate the resolver of a Query field (a Resolvers::BaseResolver) in app/graphql/resolvers.'
-
-  private
-
-  def kind = :queries
-
-  def body
-    <<~RUBY
-      # Resolves Query.#{class_basename.camelize(:lower)}. Keyword arguments are the field's
-      # arguments in snake_case; `object` and `context` are available.
-      class #{class_basename} < #{superclass_name}
-        def resolve(**args)
-          raise NotImplementedError
-        end
-      end
-    RUBY
-  end
-
-  def usage
-    "Query.#{class_basename.camelize(:lower)} resolves to #{full_class_name} — add the field to your SDL without a resolving directive."
-  end
-end

data/lib/lighthouse/directive_resolvers/where_conditions_applier.rb

@@ -1,170 +0,0 @@
-# frozen_string_literal: true
-
-class Lighthouse::GraphQL::DirectiveResolvers::WhereConditionsApplier
-  # Operator semantics live in Lighthouse::WhereConditions::OperatorMap so
-  # they can be shared with the simple argument-filter directives.
-  SUPPORTED_OPERATORS = Lighthouse::WhereConditions::OperatorMap::OPERATORS
-  # graphql-ruby hands input objects over with Ruby-style keys, so the
-  # generated input's AND/OR/HAS fields arrive as :and/:or/:has.
-  LOGICAL_KEYS = { and: :AND, or: :OR, has: :HAS }.freeze
-
-  class << self
-    def apply(relation, value)
-      return relation unless relation.respond_to?(:where)
-
-      condition = normalize_condition(value)
-      return relation unless condition
-
-      # AND narrows the incoming scope step by step; each OR branch starts
-      # from the incoming scope, and their union replaces it.
-      result = apply_all(relation, condition[:AND])
-      result = apply_any(relation, condition[:OR]) || result
-      result = apply_has_condition(result, condition[:HAS])
-      result = apply_single_condition(result, condition) if condition.key?(:column)
-      result
-    end
-
-    def apply_has(relation, has_cond)
-      relation_name = has_cond[:relation].to_s
-      return relation if relation_name.blank?
-
-      resolved_relation_name = resolve_relation_name(relation, relation_name)
-      return relation if resolved_relation_name.blank?
-
-      reflection = reflection_for(relation, resolved_relation_name)
-      return relation unless reflection&.klass
-
-      joined = relation.joins(resolved_relation_name.to_sym)
-      return joined.distinct if has_cond[:condition].blank?
-
-      # Use an EXISTS-style filter to safely apply conditions from the related model.
-      child_scope = apply(reflection.klass.all, has_cond[:condition])
-      joined.where(reflection.klass.table_name => { id: child_scope.select(:id) }).distinct
-    rescue StandardError
-      relation
-    end
-
-    def resolve_relation_name(relation, relation_name)
-      candidate_names = [relation_name.to_s, relation_name.to_s.singularize, relation_name.to_s.pluralize].uniq
-
-      candidate_names.each do |candidate|
-        next if candidate.blank?
-        return candidate if association_exists?(relation, candidate)
-      end
-
-      nil
-    rescue StandardError
-      nil
-    end
-
-    def association_exists?(relation, name)
-      reflection_for(relation, name).present?
-    rescue StandardError
-      false
-    end
-
-    def apply_has_argument(relation, arg_name, arg_value, relation_name = nil)
-      relation_name ||= derive_relation_name(arg_name)
-      return relation unless relation_name.present? && arg_value.present?
-
-      condition = arg_value.is_a?(Hash) ? arg_value : symbolized(arg_value)
-      has_payload = { relation: relation_name, condition: condition }
-      apply_has(relation, has_payload)
-    end
-
-    private
-
-    # The condition as a symbol-keyed Hash, or nil when there is none.
-    def normalize_condition(value)
-      return nil if value.nil?
-
-      condition = value.is_a?(Hash) ? value.deep_symbolize_keys : symbolized(value)
-      condition.transform_keys { |key| LOGICAL_KEYS.fetch(key, key) } if condition.is_a?(Hash)
-    end
-
-    def apply_all(relation, conditions)
-      Array(conditions).reduce(relation) { |acc, sub| apply(acc, sub) }
-    end
-
-    # The union of the branches, or nil when there are none.
-    def apply_any(relation, conditions)
-      Array(conditions).map { |sub| apply(relation, sub) }.reduce { |acc, sub_scope| acc.or(sub_scope) }
-    end
-
-    def apply_has_condition(relation, has_cond)
-      return relation unless has_cond.is_a?(Hash) && has_cond[:relation]
-
-      apply_has(relation, has_cond)
-    end
-
-    def reflection_for(relation, name)
-      klass = relation.respond_to?(:klass) ? relation.klass : relation
-      klass.reflect_on_association(name.to_sym) if klass.respond_to?(:reflect_on_association)
-    end
-
-    def derive_relation_name(arg_name)
-      Lighthouse::Support::Naming.derive_relation_name(arg_name)
-    end
-
-    def apply_single_condition(relation, condition)
-      return relation if condition[:column].blank? || !relation.respond_to?(:where)
-
-      column_name = resolve_column_name(condition[:column])
-      return relation if column_name.blank?
-
-      apply_operator(relation, column_name, operator_of(condition), condition[:value])
-    rescue StandardError
-      relation
-    end
-
-    def operator_of(condition)
-      condition[:operator]&.to_s&.upcase || 'EQ'
-    end
-
-    # Null and set operators are plain hash conditions; the rest need Arel.
-    def apply_operator(relation, column_name, operator, value)
-      case operator
-      when 'IS_NULL' then relation.where(column_name => nil)
-      when 'IS_NOT_NULL' then relation.where.not(column_name => nil)
-      when 'IN' then relation.where(column_name => Array(value))
-      when 'NIN' then relation.where.not(column_name => Array(value))
-      else apply_arel_operator(relation, column_name, operator, value)
-      end
-    end
-
-    # An unknown operator falls back to equality rather than failing the query.
-    def apply_arel_operator(relation, column_name, operator, value)
-      pattern = like_pattern(operator, value)
-      return relation.where(arel_table(relation)[column_name].matches(pattern)) if pattern
-
-      predicate = SUPPORTED_OPERATORS[operator]
-      return relation.where(column_name => value) unless predicate
-
-      relation.where(arel_table(relation)[column_name].public_send(predicate, value))
-    end
-
-    def like_pattern(operator, value)
-      case operator
-      when 'CONTAINS' then "%#{value}%"
-      when 'STARTS_WITH' then "#{value}%"
-      when 'ENDS_WITH' then "%#{value}"
-      end
-    end
-
-    def resolve_column_name(column)
-      Lighthouse::Support::Naming.column(column)
-    end
-
-    def arel_table(relation)
-      relation.klass.arel_table
-    end
-
-    def symbolized(obj)
-      if obj.respond_to?(:to_h)
-        obj.to_h.deep_symbolize_keys
-      else
-        {}
-      end
-    end
-  end
-end