> ## Documentation Index
> Fetch the complete documentation index at: https://www.orionjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL Integration

> How schemas integrate with GraphQL in Orionjs

Orionjs schemas automatically integrate with GraphQL, providing a seamless type-safe experience from your database to your API.

## Basic Integration

When you define a schema with `schemaWithName()`, it can be used directly in GraphQL resolvers:

```typescript theme={null}
import {schemaWithName, InferSchemaType} from '@orion-js/schema'
import {createQuery, Resolvers} from '@orion-js/graphql'

export const UserSchema = schemaWithName('UserSchema', {
  _id: {type: String},
  name: {type: String},
  email: {type: String, optional: true},
  createdAt: {type: Date}
})

export type UserType = InferSchemaType<typeof UserSchema>

@Resolvers()
class UserResolvers {
  @Query()
  getUser = createQuery({
    params: {
      userId: {type: String}
    },
    returns: UserSchema,
    resolve: async ({userId}) => {
      // Query implementation
      return user // This will be validated against UserSchema
    }
  })
}
```

Orionjs will automatically:

1. Generate the GraphQL type for `UserSchema`
2. Validate the resolver's return value against the schema
3. Convert any special types (like dates) to the appropriate GraphQL format

## GraphQL Schema Customization

You can customize how a schema appears in GraphQL:

```typescript theme={null}
import {schemaWithName} from '@orion-js/schema'

export const ProductSchema = schemaWithName('ProductSchema', {
  _id: {type: String},
  
  name: {
    type: String,
    label: 'Product Name',
    description: 'The display name of the product', // Appears in GraphQL documentation
    graphQLName: 'displayName' // Override the field name in GraphQL
  },
  
  internalCode: {
    type: String,
    private: true // This field won't be exposed in GraphQL
  },
  
  price: {type: Number}
})
```

## Generated GraphQL Types

The following table shows how schema types map to GraphQL types:

| Schema Type | GraphQL Type | Notes                    |
| ----------- | ------------ | ------------------------ |
| `String`    | `String`     | Plain text               |
| `Number`    | `Float`      | Default numeric type     |
| `'integer'` | `Int`        | Whole numbers            |
| `Boolean`   | `Boolean`    | True/false values        |
| `Date`      | `Date`       | Custom scalar type       |
| Schema      | Object Type  | Nested object definition |
| `[Type]`    | `[Type]`     | List of items            |
| Enum        | Enum         | Custom enum type         |

## Using Schemas for GraphQL Inputs

Schemas can be used for input validation:

```typescript theme={null}
import {schemaWithName, InferSchemaType} from '@orion-js/schema'
import {createMutation, Resolvers} from '@orion-js/graphql'

export const CreateUserInput = schemaWithName('CreateUserInput', {
  name: {type: String, min: 2},
  email: {type: String},
  role: {type: String, allowedValues: ['admin', 'user']}
})

export type CreateUserInputType = InferSchemaType<typeof CreateUserInput>

@Resolvers()
class UserResolvers {
  @Mutation()
  createUser = createMutation({
    params: CreateUserInput,
    returns: UserSchema,
    resolve: async (params: CreateUserInputType) => {
      // The input has been validated against CreateUserInput schema
      return await createUser(params)
    }
  })
}
```

## Custom GraphQL Type Resolvers

For complex field types, you can add custom resolvers:

```typescript theme={null}
import {schemaWithName} from '@orion-js/schema'
import {createModelResolver, ModelResolvers} from '@orion-js/graphql'

export const UserSchema = schemaWithName('UserSchema', {
  _id: {type: String},
  name: {type: String},
  // More fields...
})

@ModelResolvers(UserSchema)
class UserGraphQLResolvers {
  @ModelResolver()
  fullName = createModelResolver({
    returns: String,
    resolve: async (user) => {
      return `${user.firstName} ${user.lastName}`
    }
  })
} 
```