Skip to content

graphql.mdx

Latest commit

 

History

History
397 lines (264 loc) · 10.5 KB

graphql.mdx

File metadata and controls

397 lines (264 loc) · 10.5 KB
Raw
title Graphql
description Graphql protocol schemas

GraphQL Protocol Support

GraphQL is a query language for APIs and a runtime for executing those queries.

It provides a complete and understandable description of the data in your API,

gives clients the power to ask for exactly what they need, and enables powerful

developer tools.

Overview

GraphQL provides:

  • Type-safe schema definition

  • Precise data fetching (no over/under-fetching)

  • Introspection and documentation

  • Real-time subscriptions

  • Batched queries with DataLoader

Use Cases

  1. Modern API Development

  • Mobile and web applications

  • Microservices federation

  • Real-time dashboards

  1. Data Aggregation

  • Multi-source data integration

  • Complex nested queries

  • Efficient data loading

  1. Developer Experience

  • Self-documenting API

  • Type safety and validation

  • GraphQL playground

@see https://graphql.org/

@see https://spec.graphql.org/

@example GraphQL Query

query GetCustomer($id: ID!) \{

customer(id: $id) \{

id

name

email

orders(limit: 10, status: "active") \{

id

total

items \{

product \{

name

price

\}

\}

\}

\}

\}

@example GraphQL Mutation

mutation CreateOrder($input: CreateOrderInput!) \{

createOrder(input: $input) \{

id

orderNumber

status

\}

\}
**Source:** `packages/spec/src/api/graphql.zod.ts`

TypeScript Usage

import { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api';
import type { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api';

// Validate data
const result = GraphQLConfig.parse(data);

GraphQLConfig

Properties

Property Type Required Description
enabled boolean ✅ Enable GraphQL API
path string ✅ GraphQL endpoint path
playground Object optional GraphQL Playground configuration
schema Object optional Schema generation configuration
dataLoaders Object[] optional DataLoader configurations
security Object optional Security configuration

GraphQLDataLoaderConfig

Properties

Property Type Required Description
name string ✅ DataLoader name
source string ✅ Source object or datasource
batchFunction Object ✅ Batch function configuration
cache Object optional DataLoader caching
options Object optional DataLoader options

GraphQLDirectiveConfig

Properties

Property Type Required Description
name string ✅ Directive name (camelCase)
description string optional Directive description
locations Enum<'QUERY' | 'MUTATION' | 'SUBSCRIPTION' | 'FIELD' | 'FRAGMENT_DEFINITION' | 'FRAGMENT_SPREAD' | 'INLINE_FRAGMENT' | 'VARIABLE_DEFINITION' | 'SCHEMA' | 'SCALAR' | 'OBJECT' | 'FIELD_DEFINITION' | 'ARGUMENT_DEFINITION' | 'INTERFACE' | 'UNION' | 'ENUM' | 'ENUM_VALUE' | 'INPUT_OBJECT' | 'INPUT_FIELD_DEFINITION'>[] ✅ Directive locations
args Record<string, Object> optional Directive arguments
repeatable boolean ✅ Can be applied multiple times
implementation Object optional Directive implementation

GraphQLDirectiveLocation

Allowed Values

  • QUERY
  • MUTATION
  • SUBSCRIPTION
  • FIELD
  • FRAGMENT_DEFINITION
  • FRAGMENT_SPREAD
  • INLINE_FRAGMENT
  • VARIABLE_DEFINITION
  • SCHEMA
  • SCALAR
  • OBJECT
  • FIELD_DEFINITION
  • ARGUMENT_DEFINITION
  • INTERFACE
  • UNION
  • ENUM
  • ENUM_VALUE
  • INPUT_OBJECT
  • INPUT_FIELD_DEFINITION

GraphQLMutationConfig

Properties

Property Type Required Description
name string ✅ Mutation field name (camelCase recommended)
object string ✅ Source ObjectQL object name
type Enum<'create' | 'update' | 'delete' | 'upsert' | 'custom'> ✅ Mutation type
description string optional Mutation description
input Object optional Input configuration
output Object optional Output configuration
transaction Object optional Transaction configuration
authRequired boolean ✅ Require authentication
permissions string[] optional Required permissions
hooks Object optional Lifecycle hooks

GraphQLPersistedQuery

Properties

Property Type Required Description
enabled boolean ✅ Enable persisted queries
mode Enum<'optional' | 'required'> ✅ Persisted query mode (optional: allow both, required: only persisted)
store Object optional Query store configuration
apq Object optional Automatic Persisted Queries configuration
allowlist Object optional Query allow list configuration
security Object optional Security configuration

GraphQLQueryComplexity

Properties

Property Type Required Description
enabled boolean ✅ Enable query complexity limiting
maxComplexity integer ✅ Maximum query complexity
defaultFieldComplexity integer ✅ Default complexity per field
fieldComplexity Record<string, integer | Object> optional Per-field complexity configuration
listMultiplier number ✅ Multiplier for list fields
onComplexityExceeded Enum<'reject' | 'log' | 'warn'> ✅ Action when complexity exceeded
errorMessage string optional Custom error message for complexity violations

GraphQLQueryConfig

Properties

Property Type Required Description
name string ✅ Query field name (camelCase recommended)
object string ✅ Source ObjectQL object name
type Enum<'get' | 'list' | 'search'> ✅ Query type
description string optional Query description
args Record<string, Object> optional Query arguments
filtering Object optional Filtering capabilities
sorting Object optional Sorting capabilities
pagination Object optional Pagination configuration
fields Object optional Field selection configuration
authRequired boolean ✅ Require authentication
permissions string[] optional Required permissions
cache Object optional Query caching

GraphQLQueryDepthLimit

Properties

Property Type Required Description
enabled boolean ✅ Enable query depth limiting
maxDepth integer ✅ Maximum query depth
ignoreFields string[] optional Fields excluded from depth calculation
onDepthExceeded Enum<'reject' | 'log' | 'warn'> ✅ Action when depth exceeded
errorMessage string optional Custom error message for depth violations

GraphQLRateLimit

Properties

Property Type Required Description
enabled boolean ✅ Enable rate limiting
strategy Enum<'token_bucket' | 'fixed_window' | 'sliding_window' | 'cost_based'> ✅ Rate limiting strategy
global Object optional Global rate limits
perUser Object optional Per-user rate limits
costBased Object optional Cost-based rate limiting
operations Record<string, Object> optional Per-operation rate limits
onLimitExceeded Enum<'reject' | 'queue' | 'log'> ✅ Action when rate limit exceeded
errorMessage string optional Custom error message for rate limit violations
includeHeaders boolean ✅ Include rate limit headers in response

GraphQLResolverConfig

Properties

Property Type Required Description
path string ✅ Resolver path (Type.field)
type Enum<'datasource' | 'computed' | 'script' | 'proxy'> ✅ Resolver implementation type
implementation Object optional Implementation configuration
cache Object optional Resolver caching

GraphQLScalarType

Allowed Values

  • ID
  • String
  • Int
  • Float
  • Boolean
  • DateTime
  • Date
  • Time
  • JSON
  • JSONObject
  • Upload
  • URL
  • Email
  • PhoneNumber
  • Currency
  • Decimal
  • BigInt
  • Long
  • UUID
  • Base64
  • Void

GraphQLSubscriptionConfig

Properties

Property Type Required Description
name string ✅ Subscription field name (camelCase recommended)
object string ✅ Source ObjectQL object name
events Enum<'created' | 'updated' | 'deleted' | 'custom'>[] ✅ Events to subscribe to
description string optional Subscription description
filter Object optional Subscription filtering
payload Object optional Payload configuration
authRequired boolean ✅ Require authentication
permissions string[] optional Required permissions
rateLimit Object optional Subscription rate limiting

GraphQLTypeConfig

Properties

Property Type Required Description
name string ✅ GraphQL type name (PascalCase recommended)
object string ✅ Source ObjectQL object name
description string optional Type description
fields Object optional Field configuration
interfaces string[] optional GraphQL interface names
isInterface boolean ✅ Define as GraphQL interface
directives Object[] optional GraphQL directives