### Installation

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Install the necessary packages for @pallad/query-graphql.

```sh
yarn add @pallad/query-graphql @pallad/query-descriptor graphql
```

--------------------------------

### Offset Pagination Query Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Example GraphQL query demonstrating offset pagination with limit and offset parameters.

```graphql
query {
  users(query: {limit: 20, offset: 40}) {
    list {
      id
      name
    }
    pageInfo {
      limit
      offset
      hasNextPage
      hasPreviousPage
    }
  }
}
```

--------------------------------

### Cursor Pagination Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Demonstrates cursor-based pagination, including the generated GraphQL types and a sample query.

```APIDOC
## Cursor Pagination Example

### Descriptor Configuration
```typescript
const descriptor = new QueryDescriptor()
	.paginationByCursor()
	.sortingBySingleField({
		fields: ["name", "createdAt"],
		default: { field: "createdAt", direction: "DESC" },
	});
```

### Generated Result Types
```graphql
type Users_Result {
  edges: [Users_Edge!]!
  nodes: [User!]!
  pageInfo: PageInfo_ByCursor!
  sortBy: Users_Result_Sort!
}

type Users_Edge {
  node: User!
  cursor: Cursor!
}
```

### Sample Query
```graphql
query {
  users(query: {limit: 20, sortBy: {field: createdAt, direction: DESC}}) {
    edges {
      node {
        id
        name
      }
      cursor
    }
    nodes {
      id
    }
    pageInfo {
      limit
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
    sortBy {
      field
      direction
    }
  }
}
```

### Note
Cursor pagination returns both `edges` and `nodes`. Cursors are automatically generated from entity IDs by `@pallad/query-descriptor` by default.
```

--------------------------------

### Cursor Pagination Descriptor Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Descriptor configuration for cursor-based pagination with single field sorting.

```ts
const descriptor = new QueryDescriptor()
	.paginationByCursor()
	.sortingBySingleField({
		fields: ["name", "createdAt"],
		default: { field: "createdAt", direction: "DESC" },
	});
```

--------------------------------

### Offset Pagination Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Illustrates the generated GraphQL result type and a sample query for offset-based pagination.

```APIDOC
## Offset Pagination Example

### Descriptor Configuration
```typescript
const descriptor = new QueryDescriptor().paginationByOffset();
```

### Generated Result Type
```graphql
type Users_Result {
  list: [User!]!
  pageInfo: PageInfo_ByOffset!
}
```

### Sample Query
```graphql
query {
  users(query: {limit: 20, offset: 40}) {
    list {
      id
      name
    }
    pageInfo {
      limit
      offset
      hasNextPage
      hasPreviousPage
    }
  }
}
```
```

--------------------------------

### Cursor Pagination Query Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Example GraphQL query for cursor pagination, including edges, nodes, pageInfo, and sortBy.

```graphql
query {
  users(query: {limit: 20, sortBy: {field: createdAt, direction: DESC}}) {
    edges {
      node {
        id
        name
      }
      cursor
    }
    nodes {
      id
    }
    pageInfo {
      limit
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
    sortBy {
      field
      direction
    }
  }
}
```

--------------------------------

### QueryDescriptor Example

Source: https://github.com/pallad-ts/query/blob/master/package/descriptor/README.md

Demonstrates creating a QueryDescriptor with filter, offset pagination, and multi-field sorting, then using it to parse query input and create result metadata.

```typescript
import { QueryDescriptor } from "@pallad/query-descriptor";
import { z } from "zod";

const descriptor = new QueryDescriptor()
	.filterSchema(
		z.object({
			status: z.enum(["active", "archived"]).optional(),
		})
	)
	.paginationByOffset({ defaultLimit: 20 })
	.sortingByMultipleFields({
		sortableFields: ["name", "createdAt"],
		defaultSorting: [{ field: "createdAt", direction: "DESC" }],
	});

const query = descriptor.createQuery({
	filter: { status: "active" },
	offset: 0,
	sortBy: [{ field: "name", direction: "ASC" }],
});

const result = descriptor.createResult(query, [{ id: "user-1", name: "Ada" }], {
	hasNextPage: false,
	hasPreviousPage: false,
});
```

--------------------------------

### GraphQLQueryBuilder Setup

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Initialize GraphQLQueryBuilder with a descriptor, filter type, and entity type to create GraphQL input and result types.

```ts
import { QueryDescriptor } from "@pallad/query-descriptor";
import { GraphQLQueryBuilder } from "@pallad/query-graphql";
import { GraphQLInputObjectType, GraphQLNonNull, GraphQLObjectType, GraphQLString } from "graphql";
import { z } from "zod";

const descriptor = new QueryDescriptor()
	.filterSchema(
		z.object({
			status: z.enum(["active", "archived"]).optional(),
		})
	)
	.paginationByOffset({ defaultLimit: 20 })
	.sortingByMultipleFields({
		sortableFields: ["name", "createdAt"],
		defaultSorting: [{ field: "createdAt", direction: "DESC" }],
	});

const userFilterType = new GraphQLInputObjectType({
	name: "User_Filter",
	fields: {
		status: { type: GraphQLString },
	},
});

const userType = new GraphQLObjectType({
	name: "User",
	fields: {
		id: { type: new GraphQLNonNull(GraphQLString) },
		name: { type: new GraphQLNonNull(GraphQLString) },
		createdAt: { type: new GraphQLNonNull(GraphQLString) },
	},
});

const usersQuery = new GraphQLQueryBuilder({
	baseName: "Users",
	descriptor,
	filterType: userFilterType,
	entityType: userType,
});
```

--------------------------------

### Single and Multi Sorting Examples

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Illustrates how to construct single and multi-field sorting objects using the defined types.

```typescript
const single: SingleSort = {
	sortBy: { field: "name", direction: "ASC" },
};

const multi: MultiSort = {
	sortBy: [
		{ field: "createdAt", direction: "DESC" },
		{ field: "name", direction: "ASC" },
	],
};
```

--------------------------------

### Single Sorting Query Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

GraphQL query demonstrating single field sorting with sortBy input.

```graphql
query {
  users(query: {sortBy: {field: name, direction: ASC}}) {
    list { id }
  }
}
```

--------------------------------

### Sorting Descriptor Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Descriptor configuration for multiple sorting fields, specifying sortable fields and default sorting.

```ts
const descriptor = new QueryDescriptor().sortingByMultipleFields({
	sortableFields: ["created_at", "name"],
	defaultSorting: [{ field: "created_at", direction: "DESC" }],
});
```

--------------------------------

### Multiple Sorting Query Example

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

GraphQL query demonstrating multiple field sorting using an array for sortBy input.

```graphql
query {
  users(query: {sortBy: [{field: createdAt, direction: DESC}, {field: name, direction: ASC}]}) {
    list { id }
  }
}
```

--------------------------------

### Sorting Configuration

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Explains how sorting is handled, including the generation of GraphQL enum types and examples for single and multiple field sorting.

```APIDOC
## Sorting

### Description
Sorting capabilities from the query descriptor are translated into GraphQL enums and input types. A GraphQL enum named `${baseName}_Sort_Field` is generated for sortable fields. Field names are camel-cased for GraphQL, while enum values retain their original descriptor field names.

### Descriptor Example
```typescript
const descriptor = new QueryDescriptor().sortingByMultipleFields({
	sortableFields: ["created_at", "name"],
	defaultSorting: [{ field: "created_at", direction: "DESC" }],
});
```

### Generated Sort Field Enum
```graphql
enum Users_Sort_Field {
  createdAt
  name
}
```

### Single Field Sorting Query Example
```graphql
query {
  users(query: {sortBy: {field: name, direction: ASC}}) {
    list { id }
  }
}
```

### Multiple Field Sorting Query Example
```graphql
query {
  users(query: {sortBy: [{field: createdAt, direction: DESC}, {field: name, direction: ASC}]}) {
    list { id }
  }
}
```
```

--------------------------------

### GraphQLQueryBuilder Usage

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Demonstrates the initialization of GraphQLQueryBuilder with a descriptor, filter type, and entity type to generate GraphQL schema components.

```APIDOC
## GraphQLQueryBuilder Initialization

### Description
Initializes `GraphQLQueryBuilder` with a `QueryDescriptor`, a GraphQL input type for filters, and a GraphQL object type for entities. This builder generates the necessary GraphQL types and resolver logic.

### Usage
```typescript
import { QueryDescriptor } from "@pallad/query-descriptor";
import { GraphQLQueryBuilder } from "@pallad/query-graphql";
import { GraphQLInputObjectType, GraphQLNonNull, GraphQLObjectType, GraphQLString } from "graphql";
import { z } from "zod";

const descriptor = new QueryDescriptor()
	.filterSchema(
		z.object({
			status: z.enum(["active", "archived"])).optional(),
		})
	)
	.paginationByOffset({ defaultLimit: 20 })
	.sortingByMultipleFields({
		sortableFields: ["name", "createdAt"],
		defaultSorting: [{ field: "createdAt", direction: "DESC" }],
	});

const userFilterType = new GraphQLInputObjectType({
	name: "User_Filter",
	fields: {
		status: { type: GraphQLString },
	},
});

const userType = new GraphQLObjectType({
	name: "User",
	fields: {
		id: { type: new GraphQLNonNull(GraphQLString) },
		name: { type: new GraphQLNonNull(GraphQLString) },
		createdAt: { type: new GraphQLNonNull(GraphQLString) },
	},
});

const usersQuery = new GraphQLQueryBuilder({
	baseName: "Users",
	descriptor,
	filterType: userFilterType,
	entityType: userType,
});
```
```

--------------------------------

### Adding Query Field to Schema

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Shows how to use `GraphQLQueryBuilder.getField()` to add a query field to a GraphQL schema, including a custom executor function.

```APIDOC
## Adding Field To Schema

### Description
Use `getField()` from `GraphQLQueryBuilder` to obtain a `GraphQLFieldConfig` that can be added to your GraphQL schema. The `execute` callback within `getField` handles parsing GraphQL arguments using the descriptor and then invokes your data loading logic.

### Usage
```typescript
import { GraphQLObjectType, GraphQLSchema } from "graphql";

// Assume loadUsers is a function that fetches user data based on the query
// async function loadUsers(query: any): Promise<Array<any>> { /* ... */ }

const schema = new GraphQLSchema({
	query: new GraphQLObjectType({
		name: "Query",
		fields: {
			users: usersQuery.getField({
				execute: async query => {
					const list = await loadUsers(query);

					return {
						list,
						pagination: {
							hasNextPage: false,
							hasPreviousPage: false,
						},
					};
				},
			}),
		},
	}),
});
```

### Note
The `execute` function returns raw entities and pagination context. `GraphQLQueryBuilder` then uses the descriptor to format this into a GraphQL-ready result.
```

--------------------------------

### Offset Pagination Result

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Represents the result structure for offset-based pagination, including the list of items and page information like offset, limit, and navigation flags.

```typescript
import { PaginationByOffset } from "@pallad/query";

type OffsetQuery = PaginationByOffset;

const result: PaginationByOffset.Result<User> = {
	list: users,
	pageInfo: {
		offset: 0,
		limit: 20,
		hasNextPage: true,
		hasPreviousPage: false,
	};
}
```

--------------------------------

### No Pagination Result

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Represents a result set when no pagination is applied, simply returning a list of items.

```typescript
import { NoPagination } from "@pallad/query";

const result: NoPagination.Result<User> = {
	list: users,
};
```

--------------------------------

### Cursor Pagination Result

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Represents the result structure for cursor-based pagination, including edges (node and cursor) and page information. Suitable for infinite scrolling or deep linking.

```typescript
import { PaginationByCursor } from "@pallad/query";

const result: PaginationByCursor.Result<User> = {
	edges: users.map(user => ({
		node: user,
		cursor: { i: user.id },
	})),
	nodes: users,
	pageInfo: {
		limit: 20,
		hasNextPage: false,
		hasPreviousPage: false,
	},
};
```

--------------------------------

### Adding Users Field to Schema

Source: https://github.com/pallad-ts/query/blob/master/package/graphql/README.md

Use usersQuery.getField to add a GraphQL field that executes a query against your data source.

```ts
import { GraphQLObjectType, GraphQLSchema } from "graphql";

const schema = new GraphQLSchema({
	query: new GraphQLObjectType({
		name: "Query",
		fields: {
			users: usersQuery.getField({
				execute: async query => {
					const list = await loadUsers(query);

					return {
						list,
						pagination: {
							hasNextPage: false,
							hasPreviousPage: false,
						},
					};
				},
			}),
		},
	}),
});
```

--------------------------------

### Sorting Definitions

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Defines types for single and multi-field sorting criteria, specifying the field name and sort direction (ASC/DESC).

```typescript
import { SortingSingle, SortingMulti } from "@pallad/query";

type UserSortField = "name" | "createdAt";

type SingleSort = SortingSingle<UserSortField>;
type MultiSort = SortingMulti<UserSortField>;
```

--------------------------------

### Base Query Type

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Defines the fundamental structure of a query object, which includes a filter. Additional pagination and sorting types can be intersected.

```typescript
import { Query } from "@pallad/query";

type UserQuery = Query<{
	status?: "active" | "archived";
}>;
```

--------------------------------

### Query Runner Type Definition

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

Defines the contract for a query runner function, which takes a query object and returns a paginated result, potentially asynchronously.

```typescript
import { PaginationByOffset, Query, QueryRunner } from "@pallad/query";

type UserQuery = Query<{ status?: string }> & PaginationByOffset;

const runUsersQuery: QueryRunner<UserQuery, PaginationByOffset.Result<User>> = async query => {
	return {
		list: [],
		pageInfo: {
			offset: query.offset ?? 0,
			limit: query.limit,
			hasNextPage: false,
			hasPreviousPage: false,
		},
	};
};
```

--------------------------------

### SetResultType Utility

Source: https://github.com/pallad-ts/query/blob/master/package/main/README.md

A utility type to replace the entity type within a known result shape, useful for generic result handling.

```typescript
import { PaginationByCursor, SetResultType } from "@pallad/query";

type UserCursorResult = SetResultType<User, PaginationByCursor.Result<unknown>>;
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.