lighthouse-graphql 0.2.0 → 0.3.0

data/sig/lighthouse/graphql.rbs

@@ -0,0 +1,111 @@
+# The entrypoints: building the schema from SDL and running operations.
+module Lighthouse
+  module GraphQL
+    VERSION: String
+
+    Config: singleton(Lighthouse::Config)
+
+    # A GraphQL::Schema subclass.
+    type schema = untyped
+
+    module RbLightHouse
+      # The schema built from the SDL in `sdl_folder` (default: Config.sdl_folder).
+      # `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.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],
+                                    ?schema_options: Hash[Symbol, untyped], **untyped extra_options) -> schema
+      def self?.load_sdl: (path? sdl_folder) -> String
+    end
+
+    # Apollo's Automatic Persisted Queries, and a manifest of trusted operations.
+    module PersistedQueries
+      HASH: Regexp
+      NOT_FOUND: Array[String]
+      NOT_SUPPORTED: Array[String]
+      HASH_MISMATCH: Array[String]
+      NOT_IN_LIST: Array[String]
+
+      # A request the protocol rejects, rendered with Apollo's error codes.
+      class Error < StandardError
+        attr_reader code: String
+
+        def initialize: (String message, String code) -> void
+        def to_h: () -> Hash[String, untyped]
+      end
+
+      # `extensions` as the request carries it: a Hash, a JSON String (GET) or
+      # ActionController::Parameters.
+      #
+      # `schema.execute` with the query the request names: its result, or a
+      # protocol error as a ready-to-render { "errors" => [...] } Hash.
+      def self?.execute: (schema schema, query: String?, ?extensions: untyped, **untyped options) -> untyped
+      # A batch: `schema.multiplex` with the query each operation (a Hash of
+      # query, extensions, variables, operation_name, context) names. One result
+      # per operation, in order; a protocol error is a ready-to-render Hash.
+      def self?.multiplex: (schema schema, Array[Hash[Symbol | String, untyped]] operations, **untyped options) -> Array[untyped]
+      # The query text to run for a request's `query` and `extensions`.
+      def self?.resolve: (String? query, untyped extensions) -> String?
+      def self?.enabled?: () -> bool
+      def self?.digest: (String query) -> String
+      # Store a query ahead of time (e.g. from a deploy task); returns its hash.
+      def self?.register: (String query) -> String
+    end
+
+    # A concern for a GraphQL::Schema::Subscription (graphql-ruby ships no RBS, so
+    # the class it is included in is not declared): PHP Lighthouse's hooks and
+    # topic. All optional. `object` is the broadcast root and `context` the
+    # subscriber's. Including it elsewhere raises Lighthouse::DefinitionError.
+    module Subscription
+      # May this client subscribe? Called with the subscription request only.
+      def authorize?: (**untyped args) -> boolish
+      # Should this subscriber receive the broadcast of `root`? `args` are the
+      # arguments it subscribed with.
+      def filter?: (untyped root, **untyped args) -> boolish
+      # The value an update resolves the field with.
+      def resolve_payload: (untyped root, **untyped args) -> untyped
+
+      # The class methods the concern adds to its includer.
+      module ClassMethods
+        # :field (default): every subscriber shares the field's topic and filter?
+        # decides; :arguments: graphql-ruby's, subscribers match the trigger's arguments.
+        def topic_by: (?(:field | :arguments)? mode) -> (:field | :arguments)
+        def topic_for: (arguments: untyped, field: untyped, scope: untyped) -> String
+        # What @broadcast triggers the subscription with, for the root a mutation returned.
+        def trigger_arguments: (untyped root, context context) -> Hash[Symbol | String, untyped]
+        def trigger_scope: (untyped root, context context) -> untyped
+      end
+
+      # What a Subscription field with no class of its own resolves to.
+      class Default
+      end
+    end
+
+    # The Cache-Control header the selected fields' @cacheControl hints allow.
+    module CacheControl
+      DEFINITION: String
+      TYPE_DEFINITIONS: Hash[String, String]
+      CONTEXT_KEY: Symbol
+
+      # For an executed query (a GraphQL::Query::Result or GraphQL::Query);
+      # nil when the schema does not use @cacheControl.
+      def self?.header: (untyped result) -> String?
+      # Set the header on a Rails (or Rack) response, and return it.
+      def self?.apply: (untyped response, untyped result) -> String?
+    end
+
+    # The opt-in cache of the manipulated schema document, in tmp/cache.
+    module SchemaCache
+      PREFIX: String
+
+      def self?.enabled?: () -> bool
+      def self?.directory: () -> path
+      # Build the schema document now and return the cache file's path.
+      def self?.warm!: (?String? sdl) -> String
+      def self?.clear!: () -> void
+    end
+  end
+end

data/sig/lighthouse.rbs

@@ -0,0 +1,193 @@
+# Signatures for the parts of Lighthouse an application implements or calls:
+# the classes a schema names (builders, validators), the configuration, the
+# directive extension points and the entrypoints. Internals are left out.
+#
+# graphql-ruby and Active Record ship no RBS every app has, so the values that
+# come from them are aliases of untyped, named for what they hold.
+module Lighthouse
+  # An ActiveRecord::Relation, or anything with its query interface.
+  type relation = untyped
+
+  # A field's arguments, with snake_case Symbol keys as graphql-ruby passes them.
+  type arguments = Hash[Symbol, untyped]
+
+  # The request's GraphQL::Query::Context.
+  type context = untyped
+
+  # A path on disk: a String or a Pathname.
+  type path = String | _ToPath
+
+  # A class `@builder(class: "Name")` names, looked up in Config.namespaces[:builders].
+  # It refines the relation of a field resolved by @all, @paginate, @first,
+  # @count or @aggregate and returns the relation to use; nil keeps the one it
+  # was given. `@builder(method:)` names a method other than `call`, with the
+  # same signature. The class answers it, or else an instance built with no
+  # arguments does. A GraphQL::ExecutionError it raises reaches the client.
+  interface _Builder
+    def call: (relation relation, arguments args, context context) -> relation?
+  end
+
+  # A @validator contract other than a Dry::Validation::Contract: it gets the
+  # arguments (snake_case Symbol keys) and answers the errors by key,
+  # { title: ["is missing"] }, nested for input objects; empty when valid.
+  interface _Validator
+    def call: (Hash[Symbol, untyped] values) -> Hash[Symbol | String, untyped]
+  end
+
+  # Config.on_error: called with an error a directive or resolver swallowed.
+  interface _ErrorHandler
+    def call: (StandardError error, context? context) -> void
+  end
+
+  # Config.authenticated_user and Config.policy_user: the user of a request.
+  interface _UserReader
+    def call: (context? context) -> untyped
+  end
+
+  # Config.authorizer: may `user` perform `ability` on `record` (a model
+  # instance, or a model class for @canModel)? `args` are the @can* `args:`,
+  # after the field's arguments with `injectArgs: true`.
+  interface _Authorizer
+    def call: (untyped user, untyped record, String | Symbol ability, ?Array[untyped] args) -> boolish
+  end
+
+  # Config.feature_checker: is the feature `name` (as written in @feature) on
+  # for `actor`? The default asks Flipper.
+  interface _FeatureChecker
+    def call: (String name, untyped actor, context? context) -> boolish
+  end
+
+  # Config.soft_deletes: what "trashed" means for @softDeletes, @trashed,
+  # @restore, @forceDelete and @withoutGlobalScopes. The filters take a model's
+  # relation and answer the constrained one; `restore` and `force_delete` act
+  # on a record and answer whether they succeeded.
+  interface _SoftDeletes
+    def soft_deletes?: (Class model) -> boolish
+    def only_trashed: (relation relation) -> relation
+    def with_trashed: (relation relation) -> relation
+    def without_trashed: (relation relation) -> relation
+    def restore: (untyped record) -> boolish
+    def force_delete: (untyped record) -> boolish
+  end
+
+  # What DirectiveRegistry#register_manipulator takes: it transforms the SDL
+  # before the schema is built.
+  interface _SdlManipulator
+    def manipulate: (String sdl) -> String
+  end
+
+  def self.configure: () ?{ (singleton(Config) config) -> void } -> void
+
+  module Config
+    DEFAULT_NAMESPACES: Hash[Symbol, Array[String]]
+    SETTINGS: Array[Symbol]
+
+    def self.configure: () ?{ (singleton(Config) config) -> void } -> void
+    def self.[]: (Symbol | String key) -> untyped
+    def self.reset!: () -> void
+
+    def self.sdl_folder: () -> path?
+    def self.sdl_folder=: (path? folder) -> path?
+
+    # { queries:, mutations:, subscriptions:, builders:, validators:, events: } => [namespace, ...].
+    # Assigning a partial hash overrides only the kinds it names.
+    def self.namespaces: () -> Hash[Symbol, Array[String]]
+    def self.namespaces=: (Hash[Symbol | String, String | Array[String]] overrides) -> Hash[Symbol | String, String | Array[String]]
+
+    def self.resolver_namespaces: () -> Array[String]
+    def self.resolver_namespaces=: (Array[String] namespaces) -> Array[String]
+
+    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?
+
+    def self.pagination_default_count: () -> Integer?
+    def self.pagination_default_count=: (Integer? count) -> Integer?
+    def self.pagination_max_count: () -> Integer?
+    def self.pagination_max_count=: (Integer? count) -> Integer?
+
+    def self.schema_cache: () -> bool
+    def self.schema_cache=: (bool? enabled) -> bool?
+    def self.schema_cache_path: () -> path?
+    def self.schema_cache_path=: (path? path) -> path?
+    def self.watch_sdl: () -> bool
+    def self.watch_sdl=: (bool? enabled) -> bool?
+
+    def self.persisted_queries: () -> bool
+    def self.persisted_queries=: (bool? enabled) -> bool?
+    def self.persisted_queries_store: () -> untyped
+    def self.persisted_queries_store=: (untyped store) -> untyped
+    def self.persisted_queries_ttl: () -> Numeric?
+    def self.persisted_queries_ttl=: (Numeric? seconds) -> Numeric?
+    def self.persisted_queries_manifest: () -> path?
+    def self.persisted_queries_manifest=: (path? path) -> path?
+    def self.persisted_queries_only: () -> bool
+    def self.persisted_queries_only=: (bool? enabled) -> bool?
+
+    def self.convert_empty_strings_to_null: () -> bool
+    def self.convert_empty_strings_to_null=: (bool? enabled) -> bool?
+
+    # Whether @broadcast triggers in an ActiveJob (Lighthouse::GraphQL::BroadcastJob)
+    # unless the directive says shouldQueue; and the job's queue (nil: ActiveJob's default).
+    def self.queue_broadcasts: () -> bool
+    def self.queue_broadcasts=: (bool? enabled) -> bool?
+    def self.broadcast_queue: () -> (String | Symbol)?
+    def self.broadcast_queue=: ((String | Symbol)? queue) -> (String | Symbol)?
+
+    def self.on_error: () -> _ErrorHandler
+    def self.on_error=: (_ErrorHandler? handler) -> _ErrorHandler?
+    def self.handle_error: (StandardError error, ?context? context) -> void
+
+    def self.authenticated_user: () -> _UserReader
+    def self.authenticated_user=: (_UserReader? reader) -> _UserReader?
+    def self.policy_user: () -> _UserReader
+    def self.policy_user=: (_UserReader? reader) -> _UserReader?
+    def self.authorizer: () -> _Authorizer
+    def self.authorizer=: (_Authorizer? authorizer) -> _Authorizer?
+
+    def self.soft_deletes: () -> _SoftDeletes?
+    def self.soft_deletes=: (_SoftDeletes? adapter) -> _SoftDeletes?
+
+    def self.feature_checker: () -> _FeatureChecker
+    def self.feature_checker=: (_FeatureChecker? checker) -> _FeatureChecker?
+    def self.feature_actor: () -> _UserReader
+    def self.feature_actor=: (_UserReader? reader) -> _UserReader?
+  end
+
+  module Support
+    module SoftDeletes
+      # A nullable timestamp column marking trashed records, with no gem:
+      # `Config.soft_deletes = Support::SoftDeletes::Column.new(:archived_at)`.
+      class Column
+        include _SoftDeletes
+
+        DEFAULT_COLUMN: String
+
+        def initialize: (?String | Symbol column) -> void
+      end
+    end
+  end
+
+  # The schema refers to something that does not exist or breaks a contract.
+  class DefinitionError < StandardError
+  end
+
+  # A GraphQL::ExecutionError (declared from StandardError, which it descends
+  # from, as graphql-ruby ships no RBS): the @can* family denied the ability.
+  class AuthorizationError < StandardError
+    def initialize: (?String message, **untyped options) -> void
+  end
+
+  # A GraphQL::ExecutionError: invalid arguments, keyed by argument path
+  # ({ "input.title" => ["Title can't be blank"] }) under extensions.validation.
+  class ValidationError < StandardError
+    attr_reader messages: Hash[String, Array[String]]
+
+    def initialize: (String | Symbol field_name, Hash[String, Array[String]] messages) -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Vaz Innovation
@@ -59,13 +59,16 @@ files:
 - docs/configuration.md
 - docs/custom-directives.md
 - docs/directives.md
+- docs/events.md
 - docs/federation.md
 - docs/filtering-and-ordering.md
 - docs/getting-started.md
+- docs/motivation.md
 - docs/mutations.md
 - docs/performance.md
 - docs/relationships.md
 - docs/resolvers.md
+- docs/subscriptions.md
 - docs/validation.md
 - lib/generators/lighthouse/builder_generator.rb
 - lib/generators/lighthouse/class_generator.rb
@@ -77,8 +80,11 @@ files:
 - 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/broadcast_job.rb
+- lib/lighthouse/broadcasting.rb
 - lib/lighthouse/cache_control.rb
 - lib/lighthouse/caching.rb
 - lib/lighthouse/config.rb
@@ -88,6 +94,7 @@ files:
 - lib/lighthouse/contracts/field_manipulator.rb
 - lib/lighthouse/contracts/field_middleware.rb
 - lib/lighthouse/contracts/field_resolver.rb
+- lib/lighthouse/controller.rb
 - lib/lighthouse/dataloader_sources/association_loader.rb
 - lib/lighthouse/dataloader_sources/model_loader.rb
 - lib/lighthouse/dataloader_sources/relation_count_loader.rb
@@ -97,11 +104,14 @@ files:
 - lib/lighthouse/directive_resolvers/association_resolvers.rb
 - lib/lighthouse/directive_resolvers/auth_resolver.rb
 - lib/lighthouse/directive_resolvers/base.rb
+- lib/lighthouse/directive_resolvers/broadcast_resolver.rb
 - lib/lighthouse/directive_resolvers/builder_applier.rb
 - lib/lighthouse/directive_resolvers/cache_resolvers.rb
 - lib/lighthouse/directive_resolvers/can_resolvers.rb
 - lib/lighthouse/directive_resolvers/convention_resolver.rb
+- lib/lighthouse/directive_resolvers/convert_empty_strings_resolver.rb
 - lib/lighthouse/directive_resolvers/count_resolver.rb
+- lib/lighthouse/directive_resolvers/event_resolver.rb
 - lib/lighthouse/directive_resolvers/field_resolver.rb
 - lib/lighthouse/directive_resolvers/find_resolver.rb
 - lib/lighthouse/directive_resolvers/first_resolver.rb
@@ -111,16 +121,25 @@ files:
 - lib/lighthouse/directive_resolvers/paginate_resolver.rb
 - lib/lighthouse/directive_resolvers/rename_resolver.rb
 - lib/lighthouse/directive_resolvers/resolution.rb
+- lib/lighthouse/directive_resolvers/soft_delete_resolvers.rb
+- lib/lighthouse/directive_resolvers/subscription_resolver.rb
 - lib/lighthouse/directive_resolvers/validator_resolver.rb
 - lib/lighthouse/directive_resolvers/where_conditions_applier.rb
 - lib/lighthouse/directives/arguments/base.rb
 - lib/lighthouse/directives/arguments/filters.rb
 - lib/lighthouse/directives/arguments/order_by.rb
+- lib/lighthouse/directives/arguments/soft_deletes.rb
 - lib/lighthouse/directives/pagination_info_types.rb
 - lib/lighthouse/directives/pagination_manipulator.rb
 - lib/lighthouse/directives/registry.rb
+- lib/lighthouse/directives/soft_deletes_directive.rb
 - lib/lighthouse/directives/where_conditions_directive.rb
 - lib/lighthouse/errors.rb
+- lib/lighthouse/events.rb
+- lib/lighthouse/events/execution_trace.rb
+- lib/lighthouse/events/lifecycle.rb
+- lib/lighthouse/events/schema_build.rb
+- lib/lighthouse/feature_directive.rb
 - lib/lighthouse/federation_directives.rb
 - lib/lighthouse/field_resolver_stack.rb
 - lib/lighthouse/generated_resolvers.rb
@@ -137,6 +156,7 @@ files:
 - lib/lighthouse/nested_mutations/partitioner.rb
 - lib/lighthouse/pagination.rb
 - lib/lighthouse/persisted_queries.rb
+- lib/lighthouse/persisted_queries/batch.rb
 - lib/lighthouse/railtie.rb
 - lib/lighthouse/rb_lighthouse.rb
 - lib/lighthouse/reference_resolver.rb
@@ -147,21 +167,28 @@ files:
 - lib/lighthouse/schema_generator.rb
 - lib/lighthouse/schema_implementation.rb
 - lib/lighthouse/sdl_loader.rb
+- lib/lighthouse/subscription.rb
 - lib/lighthouse/support/arguments.rb
 - lib/lighthouse/support/authorization.rb
 - lib/lighthouse/support/batching.rb
 - lib/lighthouse/support/directive_args.rb
 - lib/lighthouse/support/model_resolver.rb
 - lib/lighthouse/support/naming.rb
+- lib/lighthouse/support/soft_deletes.rb
 - lib/lighthouse/tasks/lighthouse.rake
 - lib/lighthouse/where_conditions/operator_map.rb
+- sig/lighthouse.rbs
+- sig/lighthouse/controller.rbs
+- sig/lighthouse/directives.rbs
+- sig/lighthouse/events.rbs
+- sig/lighthouse/graphql.rbs
 homepage: https://github.com/Vaz-Innovation/lighthouse-graphql
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/Vaz-Innovation/lighthouse-graphql
   changelog_uri: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/Vaz-Innovation/lighthouse-graphql/tree/main/docs
+  documentation_uri: https://vaz-innovation.github.io/lighthouse-graphql/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: