Schema API Reference

Functions

buildSchema

function buildSchema(
  db: PgDatabase<any, any, any>,
  config?: BuildSchemaConfig,
): {
  schema: GraphQLSchema
  entities: GeneratedEntities
  withPermissions: (permissions: PermissionConfig) => GraphQLSchema
  clearPermissionCache: (id?: string) => void
}

Main entry point. Takes a Drizzle PgDatabase instance and optional configuration, returns the generated GraphQL schema, entity definitions, and permission helpers.

buildSchemaFromDrizzle

function buildSchemaFromDrizzle(
  drizzleSchema: Record<string, unknown>,
  config?: BuildSchemaConfig,
): {
  schema: GraphQLSchema
  entities: GeneratedEntities
  withPermissions: (permissions: PermissionConfig) => GraphQLSchema
  clearPermissionCache: (id?: string) => void
}

Builds a schema directly from Drizzle schema exports without a database connection. Creates stub resolvers — intended for introspection, codegen, and testing.

buildEntities

function buildEntities(
  db: PgDatabase<any, any, any>,
  config?: BuildSchemaConfig,
): GeneratedEntities

Returns the GeneratedEntities object (queries, mutations, inputs, types) without building a full GraphQLSchema. Useful for composing into an existing schema.

generateSDL

function generateSDL(
  schema: GraphQLSchema,
): string

Generates the GraphQL SDL string from a GraphQLSchema (as produced by buildSchema or buildSchemaFromDrizzle). Codegen utility.

generateTypes

function generateTypes(
  schema: GraphQLSchema,
  options?: CodegenOptions,
): string

Generates TypeScript type definitions from a GraphQLSchema. Codegen utility.

generateEntityDefs

function generateEntityDefs(
  schema: GraphQLSchema,
  options?: CodegenOptions,
): string

Generates entity definition types for use with @graphql-suite/client from a GraphQLSchema. Codegen utility.

permissive

function permissive(
  id: string,
  tables?: Record<string, boolean | TableAccess>,
): PermissionConfig

Creates a permissive permission config. In permissive mode, all tables are accessible unless explicitly denied.

restricted

function restricted(
  id: string,
  tables?: Record<string, boolean | TableAccess>,
): PermissionConfig

Creates a restricted permission config. In restricted mode, all tables are denied unless explicitly allowed.

readOnly

function readOnly(): TableAccess

Returns a TableAccess object with query: true and all mutations set to false.

withRowSecurity

function withRowSecurity(
  rules: Record<string, (context: any) => Record<string, unknown>>,
): HooksConfig

Generates a HooksConfig that injects WHERE clauses from row-level security rules. Rules are applied as before hooks on query, querySingle, count, update, and delete operations.

parseResolveInfo

function parseResolveInfo(info: GraphQLResolveInfo): ResolveTree | null

Builds a selection tree for the field currently being resolved. The schema builder uses it to prune columns and to derive nested relation arguments; it is exported because it is generally useful in any resolver that wants to know what the client asked for.

Fragments and inline fragments are inlined against their type condition, @skip / @include are applied, arguments are coerced (variables and defaults included), and introspection meta-fields are left out. Returns null when info carries no usable field node.

import { parseResolveInfo } from '@graphql-suite/schema'

const resolve = (_source, _args, _context, info) => {
  const tree = parseResolveInfo(info)
  const selected = Object.keys(tree?.fieldsByTypeName.UserSelectItem ?? {})
  // ['id', 'email'] for `{ users { id email } }`
}

Uses only root exports of graphql, so a single copy of the library serves both graphql 16 and 17. It replaces graphql-parse-resolve-info, whose peer range stops at graphql 16, and produces the same ResolveTree shape.

mergeHooks

function mergeHooks(...configs: HooksConfig[]): HooksConfig

Merges multiple hook configurations. When multiple hooks target the same table and operation, they are composed in order.

Classes

SchemaBuilder

class SchemaBuilder {
  constructor(db: PgDatabase<any, any, any>, config?: BuildSchemaConfig)
  build(): {
    schema: GraphQLSchema
    entities: GeneratedEntities
    withPermissions: (permissions: PermissionConfig) => GraphQLSchema
    clearPermissionCache: (id?: string) => void
  }
  buildEntities(): GeneratedEntities
}

The underlying builder class. Exposed for advanced use cases where you need more control over the build process.

Constants

GraphQLJSON

Custom GraphQL scalar type for JSONB columns. Serializes and parses arbitrary JSON values.

Types

ResolveTree

type ResolveTree = {
  /** Field name as defined in the schema. */
  name: string
  /** Response key — the alias when one is given, otherwise the field name. */
  alias: string
  /** Coerced argument values, with variables and defaults already applied. */
  args: Record<string, unknown>
  /** Sub-selection, keyed by the type name it was selected on. */
  fieldsByTypeName: FieldsByTypeName
}

Returned by parseResolveInfo.

FieldsByTypeName

type FieldsByTypeName = Record<string, Record<string, ResolveTree>>

Selected sub-fields of a field, grouped by the type they were selected on. The inner key is the response key (alias when present), matching the shape of a GraphQL response.

BuildSchemaConfig

type BuildSchemaConfig = {
  mutations?: boolean
  limitRelationDepth?: number
  limitSelfRelationDepth?: number
  suffixes?: { list?: string; single?: string }
  hooks?: HooksConfig
  tables?: {
    exclude?: readonly string[]
    config?: Record<string, TableOperations>
  }
  pruneRelations?: Record<string, RelationPruneRule>
  debug?: boolean | { schemaSize?: boolean; relationTree?: boolean }
}

GeneratedEntities

type GeneratedEntities = {
  queries: Record<string, GraphQLFieldConfig<any, any>>
  mutations: Record<string, GraphQLFieldConfig<any, any>>
  inputs: Record<string, GraphQLInputObjectType>
  types: Record<string, GraphQLObjectType>
}

PermissionConfig

type PermissionConfig = {
  id: string
  mode: 'permissive' | 'restricted'
  tables?: Record<string, boolean | TableAccess>
}

TableAccess

type TableAccess = {
  query?: boolean
  insert?: boolean
  update?: boolean
  delete?: boolean
}

TableOperations

type TableOperations = {
  queries?: boolean
  mutations?: boolean
}

RelationPruneRule

type RelationPruneRule = false | 'leaf' | { only: string[] }

HooksConfig

type HooksConfig = {
  [tableName: string]: TableHookConfig
}

TableHookConfig

type TableHookConfig = {
  [K in OperationType]?: OperationHooks
}

OperationHooks

type OperationHooks =
  | { before?: BeforeHookFn; after?: AfterHookFn }
  | { resolve: ResolveHookFn }

BeforeHookFn

type BeforeHookFn = (
  ctx: HookContext,
) => Promise<BeforeHookResult | undefined> | BeforeHookResult | undefined

AfterHookFn

type AfterHookFn = (ctx: AfterHookContext) => Promise<any> | any

ResolveHookFn

type ResolveHookFn = (ctx: ResolveHookContext) => Promise<any> | any

HookContext

type HookContext = {
  args: any
  context: any
  info: GraphQLResolveInfo
}

AfterHookContext

type AfterHookContext = {
  result: any
  beforeData: any
  context: any
  info: GraphQLResolveInfo
}

ResolveHookContext

type ResolveHookContext = HookContext & {
  defaultResolve: (overrideArgs?: any) => Promise<any>
}

OperationType

type OperationType =
  | 'query'
  | 'querySingle'
  | 'count'
  | 'insert'
  | 'insertSingle'
  | 'update'
  | 'delete'

BeforeHookResult

type BeforeHookResult = {
  args?: any
  data?: any
}

CodegenOptions

type CodegenOptions = {
  drizzle?: {
    importPath: string
    typeNames?: Record<string, string>
  }
}