lighthouse-graphql 0.1.0

data/docs/directives.md

@@ -0,0 +1,298 @@
+# Directives Reference
+
+Directives are how you add behavior to your schema. They begin with `@` and are
+attached to fields or arguments. Lighthouse **contributes the SDL definitions for
+its own directives automatically**, so you don't have to declare
+`directive @all(...) on ...` yourself — just use them.
+
+Below is every built-in directive, grouped by purpose. Federation directives are
+documented separately in [federation.md](federation.md).
+
+---
+
+## Query / fetch directives
+
+These resolve a root (or any) field from a model.
+
+### `@all`
+
+Return all records of a model.
+
+```graphql
+type Query {
+  users: [User!]! @all
+}
+```
+
+The model defaults to the field's return type (`User`). Override with
+`@all(model: "Account")`. Combine with [argument filters](filtering-and-ordering.md)
+and [`@orderBy`](#orderby) to constrain the result.
+
+### `@find`
+
+Return a single record, typically by id. Pair it with an argument filter such as
+[`@eq`](#eq) so Lighthouse knows what to match on.
+
+```graphql
+type Query {
+  user(id: ID! @eq): User @find
+}
+```
+
+### `@first`
+
+Like `@all`, but returns the **first** matching record instead of a list. Useful
+with filters to fetch one record by criteria.
+
+```graphql
+type Query {
+  latestPost(authorId: ID! @eq): Post @first
+}
+```
+
+### `@paginate`
+
+Return a paginated list. Lighthouse rewrites the field to a Paginator type and
+adds pagination arguments.
+
+```graphql
+type Query {
+  posts: [Post!]! @paginate
+}
+```
+
+becomes, in effect:
+
+```graphql
+type Query {
+  posts(first: Int, after: String): PostConnection
+}
+```
+
+Use `@paginate(type: "CONNECTION")` for Relay-style cursor connections, or the
+default offset-based paginator otherwise.
+
+### `@count`
+
+Return the number of records — of a model, or of a relation on the parent object.
+
+```graphql
+type Query {
+  userCount: Int! @count(model: "User")
+}
+
+type Account {
+  usersCount: Int! @count(relation: "users")
+}
+```
+
+### `@aggregate`
+
+Compute an aggregate (`SUM`, `AVG`, `MIN`, `MAX`, `COUNT`) over a column.
+
+```graphql
+type Account {
+  totalRevenue: Float @aggregate(relation: "orders", column: "amount", function: SUM)
+}
+```
+
+---
+
+## Relationship directives
+
+Resolve ActiveRecord associations, batched through a Dataloader to avoid N+1.
+See [relationships.md](relationships.md) for the full guide.
+
+| Directive | Association |
+| --- | --- |
+| `@hasMany` | one-to-many (returns a connection) |
+| `@hasOne` | one-to-one |
+| `@belongsTo` | inverse of has-one/has-many |
+| `@belongsToMany` | many-to-many |
+
+```graphql
+type User {
+  posts: [Post!]! @hasMany
+  profile: Profile @hasOne
+  account: Account! @belongsTo
+  roles: [Role!]! @belongsToMany
+}
+```
+
+The relation name defaults to the field name (snake_cased). Override with
+`@hasMany(relation: "authored_posts")`.
+
+---
+
+## Field directives
+
+### `@field`
+
+Delegate a field to a custom resolver class — your escape hatch for anything the
+built-in directives don't cover.
+
+```graphql
+type Contact {
+  person: Person @field(resolver: "Resolvers::ContactPerson")
+}
+```
+
+The resolver is resolved against your configured
+[`resolver_namespaces`](configuration.md). It may be a class with a class-level
+`call`, an instance `#call`, or an instance `#resolve`, each receiving
+`(object, args, context)`:
+
+```ruby
+module Resolvers
+  class ContactPerson
+    def call(contact, _args, _ctx)
+      contact.linked_person
+    end
+  end
+end
+```
+
+### `@rename`
+
+Read a differently-named attribute off the parent object. This is the explicit
+override of the default camelCase→snake_case reader.
+
+```graphql
+type User {
+  displayName: String @rename(attribute: "full_name")
+}
+```
+
+### `@method`
+
+Resolve a field by calling a method on the parent object (PHP-parity). Great for
+exposing a computed method or predicate without a custom resolver.
+
+```graphql
+type Conversation {
+  labels: [String!]! @method(name: "label_list")
+  canReply: Boolean @method(name: "can_reply?")
+}
+```
+
+---
+
+## Authentication & Authorization
+
+Enforce auth declaratively instead of in resolvers. Full guide:
+[authorization.md](authorization.md).
+
+### `@guard`
+
+Require an authenticated user before the field resolves; otherwise raise
+`Unauthenticated.`. Runs outermost.
+
+```graphql
+type Query {
+  me: User @field(resolver: "Resolvers::CurrentUser") @guard
+}
+```
+
+### `@can`
+
+Authorize a field with a policy ability (Pundit by default; configurable). By
+default it authorizes the resolved record. `repeatable`.
+
+```graphql
+type Query {
+  contact(id: ID!): Contact
+    @field(resolver: "Resolvers::ContactResolver")
+    @can(ability: "show")
+}
+```
+
+`@can(ability:, find:, model:, root:)` — see [authorization.md](authorization.md)
+for the `find`/`model`/`root` modes.
+
+### `@auth`
+
+The original guard directive — require an authenticated user
+(`context[:current_user]`) before the field resolves; otherwise raise
+`Unauthenticated.`. `@guard` is the preferred, configurable equivalent.
+
+```graphql
+type Query {
+  me: User @auth
+}
+```
+
+---
+
+## Query builder customization
+
+### `@builder`
+
+Apply a custom method to the query builder before the field resolves. Repeatable.
+
+```graphql
+type Query {
+  contacts: [Contact!]! @paginate @builder(class: "Resolvers::ContactsBuilder")
+}
+```
+
+```ruby
+module Resolvers
+  class ContactsBuilder
+    def self.call(relation, args, _ctx)
+      args[:unassigned] ? relation.left_joins(:assignments).where(assignments: { id: nil }) : relation
+    end
+  end
+end
+```
+
+---
+
+## Argument filters
+
+Attach these to a **field argument** to compose a `WHERE`/`ORDER BY` clause onto
+the query when the client supplies that argument. They compose in argument order.
+Full guide: [filtering-and-ordering.md](filtering-and-ordering.md).
+
+| Directive | Effect |
+| --- | --- |
+| `@eq` | `column = value` |
+| `@neq` | `column != value` |
+| `@in` | `column IN (values)` |
+| `@notIn` | `column NOT IN (values)` |
+| `@like` | `column LIKE %value%` |
+| `@where(operator:)` | generic operator (`GT`, `GTE`, `IN`, `IS_NULL`, `CONTAINS`, …) |
+| `@orderBy` | sort by one or more columns |
+
+```graphql
+type Query {
+  users(
+    status: String @eq
+    nameSearch: String @like
+    minAge: Int @where(operator: "GTE", key: "age")
+    orderBy: [OrderByClause!] @orderBy
+  ): [User!]! @all
+}
+```
+
+The column defaults to the snake_cased argument name; override with `key:`.
+
+### `@whereConditions` / `@whereHasConditions`
+
+Give clients a structured, dynamic `WHERE` builder (AND/OR/operators, and HAS for
+related records). Lighthouse generates the input and enum types for you. See
+[filtering-and-ordering.md](filtering-and-ordering.md#complex-where-conditions).
+
+```graphql
+type Query {
+  people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+}
+```
+
+---
+
+## Adding your own
+
+Every directive above is a small class registered with
+`Lighthouse::DirectiveRegistry`. To add one, implement the relevant
+[contract](custom-directives.md) and register it — no edits to Lighthouse
+internals. See [custom-directives.md](custom-directives.md).

data/docs/federation.md

@@ -0,0 +1,108 @@
+# Apollo Federation
+
+Lighthouse lets a Rails service act as an [Apollo Federation](https://www.apollographql.com/docs/federation/)
+**subgraph**: it understands the federation directives in your SDL and wires up
+entity resolution so a gateway can compose your types with other subgraphs.
+
+This relies on the [`apollo-federation`](https://github.com/Gusto/apollo-federation-ruby)
+gem, which you include in your app's base types and schema.
+
+## Setup
+
+Include the federation mixins in the base types you pass to Lighthouse, and make
+your schema a federation schema:
+
+```ruby
+class BaseObject < GraphQL::Schema::Object
+  include ApolloFederation::Object
+
+  # Default entity resolution: look the record up by id on the model that shares
+  # the type's GraphQL name. Lighthouse falls back to this when no custom
+  # resolver is registered (see below).
+  def self.resolve_reference(reference, _context)
+    model = graphql_name.safe_constantize
+    return nil unless model&.respond_to?(:find_by)
+
+    model.find_by(id: reference[:id] || reference['id'])
+  end
+end
+
+BaseAppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  sdl_folder: Rails.root.join('graphql').to_s,
+  options: { federation: true, base_types: { object: BaseObject } }
+)
+
+class AppSchema < BaseAppSchema
+  include ApolloFederation::Schema
+  federation(version: '2.3')
+  query(superclass.query)
+end
+```
+
+## Declaring entities
+
+Mark a type as a federation entity with `@key`. Lighthouse recognizes the
+federation directives during the resolution phase and applies them:
+
+```graphql
+type User @key(fields: "id") {
+  id: ID!
+  name: String
+}
+
+type Order @key(fields: "id") @shareable {
+  id: ID!
+}
+```
+
+Supported object-level directives: `@key`, `@extends`, `@shareable`,
+`@inaccessible`. Field-level `@external` is recognized for federation composition.
+
+## Entity resolution (`resolve_reference`)
+
+When the gateway asks your subgraph to resolve an entity (via `_entities`),
+Lighthouse routes to a `resolve_reference` it installs on each `@key` type. The
+order of precedence is:
+
+1. **A custom resolver** registered with `Lighthouse::ReferenceResolver` for that
+   type, if any.
+2. **The base type's `resolve_reference`** otherwise (e.g. the default
+   model-lookup-by-id shown above).
+
+This means direct-model entities resolve with **zero extra code** — the default
+lookup handles them — while you register custom resolvers only for the entities
+that need bespoke loading.
+
+### Custom reference resolvers
+
+For entities that aren't a straightforward `find_by(id:)` — for example, ones
+backed by a join or an external identifier — register a resolver. The single best
+place is an initializer:
+
+```ruby
+# config/initializers/federation.rb
+Rails.application.config.to_prepare do
+  Lighthouse::ReferenceResolver.register('JudgmentCreditor') do |reference, _context|
+    id = reference['id'] || reference[:id]
+    OpenStruct.new(id: id, contacts: Contact.joins(:links).where(links: { external_id: id }))
+  end
+end
+```
+
+`register(typename) { |reference, context| ... }` returns the object that
+represents the entity; its fields then resolve normally.
+
+## The federation subgraph SDL
+
+A federation subgraph publishes its capabilities via the `_service { sdl }` field
+(and `federation_sdl`), which a gateway uses to compose the supergraph. With the
+setup above this is produced for you, including the `@link` to the federation spec
+and the `@key`/`@shareable`/… directives on your types.
+
+## Gateways
+
+Apollo Gateways that use `IntrospectAndCompose` poll subgraphs and recompose
+automatically when your subgraph SDL changes — no manual step needed when you
+deploy schema changes. Gateways that consume a static, pre-composed supergraph
+file need that file recomposed (e.g. via `rover supergraph compose`) after you
+change the subgraph.

data/docs/filtering-and-ordering.md

@@ -0,0 +1,128 @@
+# Filtering & Ordering
+
+Lighthouse offers two complementary ways to constrain a query: **simple argument
+filters** (one directive per argument) and **complex where conditions** (a single
+structured argument the client drives dynamically). Both work on any field backed
+by a query — `@all`, `@paginate`, `@first`, `@count`, and the relationship
+directives.
+
+## Simple argument filters
+
+Attach a filter directive to a field argument. When the client passes that
+argument, Lighthouse folds the corresponding clause onto the query builder.
+Filters compose in the order the arguments appear in the SDL.
+
+```graphql
+type Query {
+  users(
+    status: String @eq
+    role: [String!] @in
+    nameSearch: String @like
+    minAge: Int @where(operator: "GTE", key: "age")
+  ): [User!]! @all
+}
+```
+
+| Directive | SQL |
+| --- | --- |
+| `@eq` | `column = value` |
+| `@neq` | `column != value` |
+| `@in` | `column IN (...)` |
+| `@notIn` | `column NOT IN (...)` |
+| `@like` | `column LIKE '%value%'` |
+| `@where(operator:)` | operator-driven (see below) |
+
+By default the column is the **snake_cased argument name** (`minAge` → `min_age`).
+Override it with `key:` — above, `minAge` filters the `age` column.
+
+### `@where` operators
+
+`@where(operator: "...")` supports the same operator vocabulary as
+`@whereConditions`:
+
+`EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`, `IN`, `NIN`, `CONTAINS`, `STARTS_WITH`,
+`ENDS_WITH`, `IS_NULL`, `IS_NOT_NULL`.
+
+```graphql
+type Query {
+  events(
+    after: String @where(operator: "GTE", key: "starts_at")
+    titleContains: String @where(operator: "CONTAINS", key: "title")
+  ): [Event!]! @all
+}
+```
+
+## Ordering — `@orderBy`
+
+Sort the result by one or more columns. The client passes a list of clauses, each
+with a `column` and an `order` (`ASC`/`DESC`); clauses apply in order.
+
+```graphql
+type Query {
+  users(orderBy: [OrderByClause!] @orderBy): [User!]! @all
+
+  # query:
+  # users(orderBy: [{ column: NAME, order: ASC }, { column: CREATED_AT, order: DESC }])
+}
+```
+
+`@orderBy` also accepts `{ field:, direction: }` clause shapes, so it slots into
+existing client conventions.
+
+## Complex where conditions
+
+For a flexible, client-controlled `WHERE` builder, use `@whereConditions`.
+Lighthouse generates the input and column-enum types automatically — you only
+declare the allowed columns.
+
+```graphql
+type Query {
+  people(
+    where: _ @whereConditions(columns: ["age", "type", "height"])
+  ): [Person!]! @all
+}
+```
+
+Clients can then build dynamic conditions with `AND` / `OR` / operators:
+
+```graphql
+{
+  people(
+    where: {
+      AND: [
+        { column: AGE, operator: GT, value: 37 }
+        { OR: [
+            { column: TYPE, value: "Actor" }
+            { column: HEIGHT, operator: GTE, value: 150 }
+        ] }
+      ]
+    }
+  ) { name }
+}
+```
+
+The generated `SQLOperator` enum covers `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`,
+`IN`, `NIN`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IS_NULL`, `IS_NOT_NULL`.
+
+### `@whereHasConditions`
+
+Filter by the existence of a related record, with conditions applied to the
+relation:
+
+```graphql
+type Query {
+  users(
+    hasPosts: _ @whereHasConditions(columns: ["status"])
+  ): [User!]! @all
+}
+```
+
+The relation is inferred from the `has<Relation>` argument name (`hasPosts` →
+`posts`), or specified with `relation:`.
+
+## How columns are resolved
+
+Column names from enums (e.g. `CREATED_AT`) and arguments (`minAge`) are mapped to
+real columns through one central rule (`Lighthouse::Support::Naming`): ALLCAPS
+enum keys are downcased, and camelCase is converted to snake_case. This keeps
+client-facing GraphQL idiomatic while matching your Rails schema.

data/docs/getting-started.md

@@ -0,0 +1,152 @@
+# Getting Started
+
+This guide takes you from an empty Rails app to a working, directive-driven
+GraphQL endpoint.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'lighthouse-graphql'
+```
+
+```shell
+bundle install
+```
+
+Runtime dependencies (`graphql ~> 2.5`, `activesupport`) come with the gem. If you
+want federation, add `apollo-federation` to your app — it is intentionally **not**
+a hard dependency of Lighthouse so non-federated apps stay lean.
+
+## 1. Write your schema (SDL)
+
+By default Lighthouse loads every `*.graphql` file under `RAILS_ROOT/graphql`,
+sorted by path and concatenated. Split your schema however you like:
+
+```graphql
+# graphql/schema.graphql
+type Query {
+  users: [User!]! @all
+  user(id: ID! @eq): User @find
+}
+
+type User {
+  id: ID!
+  name: String
+  email: String
+}
+```
+
+`@all` resolves to `User.all`; `@find` resolves a single `User` by the `id`
+argument (the `@eq` makes `id` a filter). Lighthouse infers the model from the
+field's return type name (`User`), or you can be explicit with
+`@all(model: "User")`.
+
+## 2. Provide your base types
+
+Lighthouse builds on graphql-ruby, so you supply the base classes it should use
+for objects, interfaces, etc. — exactly the place to mix in Apollo Federation or
+any custom field/argument behavior.
+
+```ruby
+# app/graphql/base_object.rb
+class BaseObject < GraphQL::Schema::Object
+  # include ApolloFederation::Object   # if you use federation
+end
+```
+
+## 3. Build the schema
+
+```ruby
+# app/graphql/app_schema.rb
+require 'lighthouse-graphql'
+
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  sdl_folder: Rails.root.join('graphql').to_s,
+  options: {
+    base_types: {
+      object: BaseObject,
+      # interface:, union:, enum:, input_object:, scalar: ...
+    }
+  }
+)
+```
+
+`get_schema` returns a `GraphQL::Schema` subclass you can use directly, or
+subclass further (e.g. to add federation, tracing, a Dataloader):
+
+```ruby
+class AppSchema < AppSchema   # or build a Base*Schema and subclass it
+  use GraphQL::Dataloader
+end
+```
+
+> Lighthouse uses graphql-ruby's `Dataloader` to batch relationship loads. Add
+> `use GraphQL::Dataloader` to your schema to get N+1-free relationships.
+
+## 4. Serve it
+
+A standard graphql-ruby controller:
+
+```ruby
+class GraphqlController < ApplicationController
+  def execute
+    result = AppSchema.execute(
+      params[:query],
+      variables: params[:variables],
+      context: { current_user: current_user },
+      operation_name: params[:operationName]
+    )
+    render json: result
+  end
+end
+```
+
+## 5. Configure (optional)
+
+Create an initializer to wire app-specific settings. This is also the single
+place to register custom directives and federation reference resolvers, which
+keeps Lighthouse itself free of any app constants.
+
+```ruby
+# config/initializers/lighthouse.rb
+require 'lighthouse-graphql'
+
+Lighthouse.configure do |config|
+  # Namespaces tried when resolving a class referenced by a directive argument,
+  # e.g. @field(resolver: "Users::Profile") or @all(model: "User").
+  config.resolver_namespaces = ['App::Graphql', 'Resolvers']
+
+  # How swallowed directive errors are surfaced (raise in test, log otherwise).
+  # config.on_error = ->(error, _ctx) { Sentry.capture_exception(error) }
+end
+```
+
+See [configuration.md](configuration.md) for all options.
+
+## Casing: camelCase ↔ snake_case
+
+GraphQL conventionally uses `camelCase` field names; Rails uses `snake_case`
+attributes. Lighthouse bridges them with one rule: a field with no directive is
+read off the parent object by its **snake_cased** name.
+
+```graphql
+type User {
+  customAttributes: String   # reads user.custom_attributes
+}
+```
+
+When the mapping isn't a simple `underscore`, use [`@rename`](directives.md#rename):
+
+```graphql
+type User {
+  displayName: String @rename(attribute: "full_name")
+}
+```
+
+## Next steps
+
+- [Directives reference](directives.md) — the full vocabulary.
+- [Relationships](relationships.md) — wiring associations.
+- [Filtering & ordering](filtering-and-ordering.md) — query constraints.
+- [Apollo Federation](federation.md) — become a subgraph.