lighthouse-graphql 0.6.0 → 0.7.1

data/lib/lighthouse/where_conditions/types.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# The types @whereConditions and @whereHasConditions generate, as PHP
+# Lighthouse's WhereConditionsServiceProvider defines them. For an argument
+# whose input is named N:
+#
+#   N               column, operator, value, AND, OR, HAS: the conditions
+#   NRelation       HAS: a relation, how many of its records (operator, amount), and a condition on them
+#   NHasCondition   the condition on the related records: as N, but on any column
+#
+# Without `columns:` / `columnsEnum:` the argument shares the unrestricted
+# WhereConditions (and its WhereConditionsRelation / WhereConditionsHasCondition).
+module Lighthouse::WhereConditions::Types
+  DEFAULT = 'WhereConditions'
+  SQL_OPERATOR = 'SQLOperator'
+  MIXED = 'Mixed'
+
+  # The SQLOperator enum: what a condition compares the column with.
+  OPERATORS = {
+    'EQ' => 'Equal operator (`=`)',
+    'NEQ' => 'Not equal operator (`!=`)',
+    'GT' => 'Greater than operator (`>`)',
+    'GTE' => 'Greater than or equal operator (`>=`)',
+    'LT' => 'Less than operator (`<`)',
+    'LTE' => 'Less than or equal operator (`<=`)',
+    'LIKE' => 'Simple pattern matching (`LIKE`)',
+    'NOT_LIKE' => 'Negation of simple pattern matching (`NOT LIKE`)',
+    'IN' => 'Whether a value is within a set of values (`IN`)',
+    'NOT_IN' => 'Whether a value is not within a set of values (`NOT IN`)',
+    'BETWEEN' => 'Whether a value is within a range of values (`BETWEEN`)',
+    'NOT_BETWEEN' => 'Whether a value is not within a range of values (`NOT BETWEEN`)',
+    'IS_NULL' => 'Whether a value is null (`IS NULL`)',
+    'IS_NOT_NULL' => 'Whether a value is not null (`IS NOT NULL`)'
+  }.freeze
+
+  DEFAULT_OPERATOR = 'EQ'
+  DEFAULT_HAS_OPERATOR = 'GTE'
+  DEFAULT_HAS_AMOUNT = 1
+
+  module_function
+
+  # Defines N, NHasCondition and NRelation, and the SQLOperator and Mixed they use.
+  def define(document_ast, name, column_type, path)
+    document_ast.define_type(SQL_OPERATOR) { sql_operator }
+    document_ast.define_type(MIXED, 'scalar Mixed')
+    document_ast.define_type(name) { conditions(name, "Dynamic WHERE conditions for #{path}.", column_type) }
+    document_ast.define_type("#{name}HasCondition") do
+      conditions("#{name}HasCondition", "Dynamic WHERE HAS conditions for #{path}.", 'String')
+    end
+    document_ast.define_type("#{name}Relation") { relation(name, "Dynamic HAS conditions for WHERE conditions for #{path}.") }
+  end
+
+  def define_default(document_ast)
+    define(document_ast, DEFAULT, 'String', 'any column')
+  end
+
+  def conditions(name, description, column_type)
+    <<~GRAPHQL
+      "#{description}"
+      input #{name} {
+        "The column that is used for the condition."
+        column: #{column_type}
+
+        "The operator that is used for the condition."
+        operator: #{SQL_OPERATOR} = #{DEFAULT_OPERATOR}
+
+        "The value that is used for the condition."
+        value: #{MIXED}
+
+        "A set of conditions that requires all conditions to match."
+        AND: [#{name}!]
+
+        "A set of conditions that requires at least one condition to match."
+        OR: [#{name}!]
+
+        "Check whether a relation exists. Extra conditions or a minimum amount can be applied."
+        HAS: #{name.delete_suffix('HasCondition')}Relation
+      }
+    GRAPHQL
+  end
+
+  def relation(name, description)
+    <<~GRAPHQL
+      "#{description}"
+      input #{name}Relation {
+        "The relation that is checked."
+        relation: String!
+
+        "The comparison operator to test against the amount."
+        operator: #{SQL_OPERATOR} = #{DEFAULT_HAS_OPERATOR}
+
+        "The amount to test."
+        amount: Int = #{DEFAULT_HAS_AMOUNT}
+
+        "Additional condition logic."
+        condition: #{name}HasCondition
+      }
+    GRAPHQL
+  end
+
+  def sql_operator
+    values = OPERATORS.map { |value, description| %(  "#{description}"\n  #{value}) }
+    <<~GRAPHQL
+      "The available SQL operators that are used to filter query results."
+      enum #{SQL_OPERATOR} {
+      #{values.join("\n\n")}
+      }
+    GRAPHQL
+  end
+end

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

@@ -92,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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 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
@@ -87,6 +88,7 @@ files:
 - 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
@@ -98,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
@@ -143,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
@@ -151,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
@@ -159,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
@@ -184,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
@@ -201,7 +208,7 @@ files:
 - 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
@@ -217,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/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