@gqlkit-ts/cli 0.5.1 → 0.7.0

package/dist/type-extractor/validator/type-validator.js

@@ -1,5 +1,10 @@
 import { BUILT_IN_SCALARS } from "../../shared/constants.js";
-const PLACEHOLDER_TYPES = new Set(["__INLINE_OBJECT__", "__INLINE_ENUM__"]);
+const PLACEHOLDER_TYPES = new Set([
+    "__INLINE_OBJECT__",
+    "__INLINE_ENUM__",
+    "__INLINE_UNION__",
+    "__NEVER__",
+]);
 export function validateTypes(options) {
     const { types, customScalarNames } = options;
     const diagnostics = [];

package/dist/type-extractor/validator/type-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"type-validator.js","sourceRoot":"","sources":["../../../src/type-extractor/validator/type-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAY7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE5E,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAE7C,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;QAC3B,GAAG,gBAAgB;QACnB,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC;KAC7B,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAErC,IACE,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;oBACxB,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAC3B,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAChC,CAAC;oBACD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,iCAAiC,QAAQ,GAAG;wBACzE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,IAAI,CAAC,IAAI,iCAAiC,MAAM,GAAG;wBACtE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC;QAC/B,WAAW;KACZ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"type-validator.js","sourceRoot":"","sources":["../../../src/type-extractor/validator/type-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAY7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,mBAAmB;IACnB,iBAAiB;IACjB,kBAAkB;IAClB,WAAW;CACZ,CAAC,CAAC;AAEH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAE7C,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;QAC3B,GAAG,gBAAgB;QACnB,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC;KAC7B,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAErC,IACE,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;oBACxB,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAC3B,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAChC,CAAC;oBACD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,iCAAiC,QAAQ,GAAG;wBACzE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,IAAI,CAAC,IAAI,iCAAiC,MAAM,GAAG;wBACtE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC;QAC/B,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/docs/configuration.md

@@ -155,6 +155,25 @@ export default defineConfig({
 |------|-------------|
 | `afterAllFileWrite` | Runs after all generated files are written. Receives the list of written file paths. |
 
+## Custom Discriminator Fields
+
+Specify custom TypeScript fields for union type resolution. This is useful when union members use a discriminator field other than `__typename` or `$typeName` (e.g., external library types).
+
+```ts
+export default defineConfig({
+  discriminatorFields: {
+    // Single field
+    ContentPart: "type",
+    // Multiple fields for tuple-based discrimination
+    Content: ["type", "mediaType"],
+  },
+});
+```
+
+Keys are GraphQL union type names, and values are either a single field name or an array of field names. gqlkit automatically generates `__resolveType` functions based on these fields.
+
+See [Union Types - Custom Discriminator Fields](./schema/unions.md#custom-discriminator-fields) for detailed usage and validation rules.
+
 ## Source Directory
 
 By default, gqlkit scans `src/gqlkit/schema` for types and resolvers.

package/docs/getting-started.md

@@ -57,7 +57,7 @@ Create `src/gqlkit/gqlkit.ts` to export resolver factories:
 import { createGqlkitApis } from "@gqlkit-ts/runtime";
 import type { Context } from "./context";
 
-export const { defineQuery, defineMutation, defineField } =
+export const { defineQuery, defineMutation, defineSubscription, defineField } =
   createGqlkitApis<Context>();
 ```
 
@@ -118,3 +118,4 @@ export const schema = makeExecutableSchema({ typeDefs, resolvers });
 - [HTTP Server Integration](./integration/yoga) - Connect your schema to graphql-yoga, Apollo Server, or other HTTP servers
 - [Object Types](./schema/objects) - Learn more about defining types
 - [Queries & Mutations](./schema/queries-mutations) - Advanced resolver patterns
+- [Subscriptions](./schema/subscriptions) - Real-time data with subscriptions

package/docs/index.md

@@ -25,6 +25,7 @@ gqlkit generates GraphQL schema and resolver maps from TypeScript types and func
 - [Defining Object Types](./schema/objects.md): Plain TypeScript type exports become GraphQL Object types.
 - [Defining Input Types](./schema/inputs.md): TypeScript types with Input suffix are treated as GraphQL input types.
 - [Defining Queries and Mutations](./schema/queries-mutations.md): Define Query and Mutation fields using the @gqlkit-ts/runtime API.
+- [Defining Subscriptions](./schema/subscriptions.md): Define Subscription fields using the @gqlkit-ts/runtime API.
 - [Defining Field Resolvers](./schema/fields.md): Add computed fields to object types using defineField.
 - [Defining Scalar Types](./schema/scalars.md): gqlkit provides built-in scalar types and supports custom scalar definitions.
 - [Defining Enum Types](./schema/enums.md): gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
@@ -40,6 +41,7 @@ gqlkit generates GraphQL schema and resolver maps from TypeScript types and func
 - [Integration with Apollo Server](./integration/apollo.md): Use gqlkit with Apollo Server, a popular GraphQL server.
 - [Integration with Drizzle ORM](./integration/drizzle.md): Derive GraphQL types from Drizzle table definitions.
 - [Integration with Prisma](./integration/prisma.md): Derive GraphQL types from Prisma model types.
+- [Integration with Vercel AI SDK](./integration/ai-sdk.md): Stream AI responses as GraphQL subscriptions using the Vercel AI SDK.
 
 ## Guides
 

package/docs/integration/ai-sdk.md

@@ -0,0 +1,189 @@
+---
+title: Integration with Vercel AI SDK
+description: Stream AI responses as GraphQL subscriptions using the Vercel AI SDK.
+---
+
+# Vercel AI SDK
+
+The [Vercel AI SDK](https://ai-sdk.dev/) provides a unified API for working with large language models. gqlkit integrates with the AI SDK by automatically converting its rich message types — including tool invocations, step boundaries, and custom data parts — into GraphQL unions and subscriptions.
+
+## Installation
+
+```sh filename="npm"
+npm install ai @ai-sdk/openai
+```
+
+```sh filename="pnpm"
+pnpm add ai @ai-sdk/openai
+```
+
+```sh filename="yarn"
+yarn add ai @ai-sdk/openai
+```
+
+## Defining Tools
+
+Define AI tools using the AI SDK's `tool()` helper. The `ToolSet` and `InferUITools` types let you derive strongly-typed UI tool representations:
+
+```typescript
+// src/agent.ts
+import type { InferUITools, ToolSet, UIMessage } from "ai";
+import { tool } from "ai";
+import { z } from "zod";
+
+export const tools = {
+  weather: tool({
+    description: "Get current weather for a location",
+    inputSchema: z.object({
+      location: z.string().describe("City name"),
+    }),
+    execute: async ({ location }) => ({
+      location,
+      temperature: 72,
+      condition: "sunny" as const,
+    }),
+  }),
+  calculate: tool({
+    description: "Calculate a math expression",
+    inputSchema: z.object({
+      expression: z.string().describe("Math expression"),
+    }),
+    execute: async ({ expression }) => ({
+      expression,
+      result: 42,
+    }),
+  }),
+} satisfies ToolSet;
+
+export type AppTools = InferUITools<typeof tools>;
+
+export type AppMetadata = {
+  model: string;
+  timestamp: number;
+};
+
+export type AppData = {
+  chart: { labels: string[]; values: number[] };
+  suggestion: { text: string; confidence: number };
+};
+
+export type AppMessage = UIMessage<AppMetadata, AppData, AppTools>;
+```
+
+## Defining the Message Type
+
+Re-export your `AppMessage` as a named type in the gqlkit schema directory. gqlkit discovers the `UIMessage` fields — including the `parts` union — transitively, so you don't need to manually define each part type:
+
+```typescript
+// src/gqlkit/schema/message.ts
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { AppMessage } from "../../agent.js";
+import { defineQuery } from "../gqlkit.js";
+
+// Re-export AppMessage as Message — gqlkit discovers UIMessage fields transitively.
+export type Message = AppMessage;
+
+export const messages = defineQuery<NoArgs, Message[]>(() => mockMessages);
+export const message = defineQuery<{ id: string }, Message | null>(
+  (_root, args) => mockMessages.find((m) => m.id === args.id) ?? null,
+);
+```
+
+The `parts` field on `UIMessage` is a discriminated union of text parts, tool invocations, tool results, step boundaries, source parts, file parts, reasoning parts, and your custom data parts. gqlkit automatically generates a corresponding GraphQL union type for this.
+
+## Defining Subscriptions
+
+The AI SDK provides two streaming patterns that map naturally to GraphQL subscriptions:
+
+### Raw Stream (chunk-by-chunk)
+
+Use `toUIMessageStream()` to yield each `UIMessageChunk` as it arrives:
+
+```typescript
+// src/gqlkit/schema/subscription.ts
+import type { InferUIMessageChunk } from "ai";
+import { streamText } from "ai";
+import type { AppMessage } from "../../agent.js";
+import { tools } from "../../agent.js";
+import { defineSubscription } from "../gqlkit.js";
+
+export type ChatStreamChunk = InferUIMessageChunk<AppMessage>;
+
+export const chatStream = defineSubscription<
+  { prompt: string },
+  ChatStreamChunk
+>(async (_root, args, ctx) => {
+  const result = streamText({ model: ctx.model, prompt: args.prompt, tools });
+  return result.toUIMessageStream<AppMessage>();
+});
+```
+
+### Assembled Message (progressive updates)
+
+Use `readUIMessageStream()` to yield the progressively-built `Message` on each update:
+
+```typescript
+import { readUIMessageStream, streamText } from "ai";
+import type { AppMessage } from "../../agent.js";
+import { tools } from "../../agent.js";
+import { defineSubscription } from "../gqlkit.js";
+import type { Message } from "./message.js";
+
+export const chat = defineSubscription<{ prompt: string }, Message>(
+  async (_root, args, ctx) => {
+    const result = streamText({ model: ctx.model, prompt: args.prompt, tools });
+    return readUIMessageStream<AppMessage>({
+      stream: result.toUIMessageStream(),
+    });
+  },
+);
+```
+
+## Discriminator Fields Configuration
+
+The AI SDK's union types use discriminator fields that gqlkit needs to know about. Configure them in `gqlkit.config.ts`:
+
+```typescript
+// gqlkit.config.ts
+import type { GqlkitConfig } from "@gqlkit-ts/cli";
+
+const config: GqlkitConfig = {
+  discriminatorFields: {
+    // Message.parts union — discriminated by "type" with "state" as a secondary field
+    MessageParts: ["type", "state"],
+    // UIMessageChunk variants — discriminated by "type"
+    ChatStreamChunk: ["type"],
+  },
+};
+
+export default config;
+```
+
+The `discriminatorFields` option tells gqlkit which fields to use when generating the GraphQL union's `__resolveType` implementation.
+
+## Context with Language Model
+
+Inject the `LanguageModel` via context so resolvers stay testable and model-agnostic. For basic setup, see [Set Up Context and Resolver Factories](../getting-started.md#set-up-context-and-resolver-factories).
+
+```typescript
+// src/gqlkit/context.ts
+import type { LanguageModel } from "ai";
+
+export type Context = {
+  model: LanguageModel;
+};
+```
+
+## Complete Example
+
+See the [examples/with-ai-sdk](https://github.com/gqlkit/gqlkit/tree/main/examples/with-ai-sdk) directory for a complete working example with:
+
+- Tool definitions with Zod schemas
+- `UIMessage` with custom metadata, data parts, and tool types
+- Both streaming patterns (`chatStream` and `chat` subscriptions)
+- Discriminator fields configuration
+
+## Further Reading
+
+- [AI SDK Documentation](https://ai-sdk.dev/docs)
+- [AI SDK GitHub](https://github.com/vercel/ai)

package/docs/schema/conventions.md

@@ -34,6 +34,13 @@ gqlkit maps TypeScript types to GraphQL types as follows:
 
 gqlkit generates type names using predictable conventions:
 
+For `defineQuery`, `defineMutation`, and `defineField`, GraphQL field names are also derived from exported variable names:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- Common usage is a single prefix (for example, `Query$users` -> `users`).
+- If the export name ends with `$`, gqlkit reports an error.
+
 | Context | Pattern | Example |
 |---------|---------|---------|
 | Object field (inline) | `{ParentType}{Field}` | `User.profile` → `UserProfile` |

package/docs/schema/fields.md

@@ -7,6 +7,12 @@ description: Add computed fields to object types using defineField.
 
 Add computed fields to object types using `defineField`. Define them alongside the type.
 
+GraphQL field names are derived from the exported variable name:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- If the export name ends with `$`, gqlkit reports an error.
+
 ## Basic Usage
 
 ```typescript
@@ -44,6 +50,15 @@ type User {
 }
 ```
 
+Example with `$` delimiter:
+
+```typescript
+// GraphQL field name: posts
+export const User$posts = defineField<User, NoArgs, Post[]>(
+  (parent) => findPostsByAuthor(parent.id)
+);
+```
+
 ## Resolver Function Signature
 
 Field resolvers receive four arguments:

package/docs/schema/queries-mutations.md

@@ -11,7 +11,11 @@ Define Query and Mutation fields using the `@gqlkit-ts/runtime` API.
 
 ## Query Resolvers
 
-Use `defineQuery` to define Query fields. The export name becomes the GraphQL field name:
+Use `defineQuery` to define Query fields. GraphQL field names are derived from the exported variable name:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- If the export name ends with `$`, gqlkit reports an error.
 
 ```typescript
 import { defineQuery } from "../gqlkit";
@@ -50,9 +54,16 @@ type Query {
 }
 ```
 
+Example with `$` delimiter:
+
+```typescript
+// GraphQL field name: users
+export const Query$users = defineQuery<NoArgs, User[]>(() => []);
+```
+
 ## Mutation Resolvers
 
-Use `defineMutation` to define Mutation fields:
+Use `defineMutation` to define Mutation fields. The same export-name rule applies:
 
 ```typescript
 import { defineMutation } from "../gqlkit";
@@ -71,6 +82,14 @@ export const deleteUser = defineMutation<{ id: string }, boolean>(
     return ctx.db.deleteUser(args.id);
   }
 );
+
+// GraphQL field name: createUser
+export const Mutation$createUser = defineMutation<
+  { input: CreateUserInput },
+  User
+>((_root, args, ctx) => {
+  return ctx.db.createUser(args.input);
+});
 ```
 
 Generates:

package/docs/schema/subscriptions.md

@@ -0,0 +1,173 @@
+---
+title: Defining Subscriptions
+description: Define Subscription fields using the @gqlkit-ts/runtime API.
+---
+
+# Subscriptions
+
+Define Subscription fields using the `@gqlkit-ts/runtime` API.
+
+> **Prerequisites**: This guide assumes you have completed the [basic setup](../getting-started.md#set-up-context-and-resolver-factories).
+
+## Setup
+
+Export `defineSubscription` from your `gqlkit.ts`:
+
+```typescript
+import { createGqlkitApis } from "@gqlkit-ts/runtime";
+import type { Context } from "./context";
+
+export const { defineQuery, defineMutation, defineSubscription } =
+  createGqlkitApis<Context>();
+```
+
+## Subscription Resolvers
+
+Use `defineSubscription` to define Subscription fields. The resolver is typically an async generator function:
+
+```typescript
+import { defineSubscription } from "../gqlkit";
+import type { Message } from "./message";
+
+// Subscription.messageAdded(channelId: String!)
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  messageAdded(channelId: String!): Message!
+}
+```
+
+The same export name conventions apply as with [Queries & Mutations](./queries-mutations.md):
+
+```typescript
+// GraphQL field name: messageAdded
+export const Subscription$messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+## NoArgs Subscriptions
+
+For subscriptions without arguments, use `NoArgs` as the first type parameter — same as with `defineQuery` and `defineMutation`. See [Queries & Mutations](./queries-mutations.md#noargs-queries) for details.
+
+## Resolver Function Signature
+
+Subscription resolvers receive the same four arguments as Query/Mutation resolvers, but return an `AsyncIterable` instead of a direct value:
+
+```typescript
+(root, args, ctx, info) => AsyncIterable<T> | Promise<AsyncIterable<T>>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `root` | The root value (always undefined) |
+| `args` | The arguments passed to the field |
+| `ctx` | The context object (typed via `createGqlkitApis<Context>()`) |
+| `info` | GraphQL resolve info |
+
+## Inline Object Arguments
+
+Subscription arguments support the same inline object types as queries and mutations:
+
+```typescript
+export const orderUpdated = defineSubscription<
+  {
+    filter: {
+      orderId: string | null;
+      status: string | null;
+    };
+  },
+  Order
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Order>("ORDER_UPDATED", args.filter);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  orderUpdated(filter: OrderUpdatedFilterInput!): Order!
+}
+
+input OrderUpdatedFilterInput {
+  orderId: String
+  status: String
+}
+```
+
+## Attaching Directives
+
+Add a third type parameter to attach directives:
+
+```typescript
+import { defineSubscription } from "../gqlkit";
+import type { AuthDirective } from "./directives";
+import type { Message } from "./message";
+
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message,
+  [AuthDirective<{ role: ["USER"] }>]
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  messageAdded(channelId: String!): Message! @auth(role: [USER])
+}
+```
+
+See [Directives](./directives.md) for more details on defining and using custom directives.
+
+## Documentation
+
+TSDoc comments on subscription exports are extracted as GraphQL descriptions:
+
+```typescript
+/** Subscribe to new messages in a channel. */
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+
+/**
+ * @deprecated Use messageAdded instead.
+ */
+export const onMessage = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  """Subscribe to new messages in a channel."""
+  messageAdded(channelId: String!): Message!
+  onMessage(channelId: String!): Message! @deprecated(reason: "Use messageAdded instead.")
+}
+```
+
+See [Documentation](./documentation.md) for more details.

package/docs/schema/unions.md

@@ -279,6 +279,123 @@ export type SearchResult = User | Post;
 // resolveType is automatically generated - no manual definition needed
 ```
 
+### Custom Discriminator Fields
+
+When union member types use a field other than `__typename` or `$typeName` for discrimination (e.g., external library types like AI SDK's `UIMessagePart`), you can configure custom discriminator fields via `gqlkit.config.ts`. gqlkit will automatically generate `__resolveType` based on the specified fields.
+
+```ts
+// gqlkit.config.ts
+import { defineConfig } from "@gqlkit-ts/cli";
+
+export default defineConfig({
+  discriminatorFields: {
+    ContentPart: "type",
+  },
+});
+```
+
+```typescript
+// src/gqlkit/schema/types.ts
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export interface ImagePart {
+  type: "image";
+  url: string;
+  alt: string;
+}
+
+export type ContentPart = TextPart | ImagePart;
+```
+
+Generates a `switch`-based `__resolveType`:
+
+```typescript
+ContentPart: {
+  __resolveType: (obj) => {
+    switch (obj.type) {
+      case "text": return "TextPart";
+      case "image": return "ImagePart";
+      default: return undefined;
+    }
+  },
+},
+```
+
+Unlike `__typename` or `$typeName`, custom discriminator fields remain as regular GraphQL fields in the generated schema:
+
+```graphql
+union ContentPart = ImagePart | TextPart
+
+type TextPart {
+  type: String!
+  text: String!
+}
+
+type ImagePart {
+  type: String!
+  url: String!
+  alt: String!
+}
+```
+
+#### Multiple Discriminator Fields
+
+When a single field is not enough to uniquely identify each member, you can specify multiple discriminator fields as an array. The first field must exist on all members with a string literal type. Secondary fields do not need to exist on every member.
+
+```ts
+// gqlkit.config.ts
+import { defineConfig } from "@gqlkit-ts/cli";
+
+export default defineConfig({
+  discriminatorFields: {
+    Content: ["type", "mediaType"],
+  },
+});
+```
+
+```typescript
+export type Content =
+  | { type: "text"; mediaType: "plain"; body: string }
+  | { type: "text"; mediaType: "html"; html: string }
+  | { type: "image"; url: string; alt: string };
+```
+
+Generates nested `switch` statements and type names derived from the discriminator values:
+
+```graphql
+union Content = ContentImage | ContentTextHtml | ContentTextPlain
+
+type ContentTextPlain {
+  type: String!
+  mediaType: String!
+  body: String!
+}
+
+type ContentTextHtml {
+  type: String!
+  mediaType: String!
+  html: String!
+}
+
+type ContentImage {
+  type: String!
+  url: String!
+  alt: String!
+}
+```
+
+#### Validation Rules
+
+- The **first** discriminator field must exist on **all** union members and have a string literal type
+- Secondary fields do not need to exist on every member, but the combination of values must be unique across all members
+- If a `defineResolveType` is manually defined for the same union, the manual definition takes priority
+- If `discriminatorFields` is configured for a union that also has `$typeName` or `__typename`, the `discriminatorFields` configuration takes priority
+
+See [Configuration](../configuration.md#custom-discriminator-fields) for the full config reference.
+
 ### Manual Resolution
 
 For types without `__typename` or `$typeName`, use `defineResolveType`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gqlkit-ts/cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Just types and functions — write TypeScript, generate GraphQL.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@graphql-tools/utils": "^11.0.0",
-    "gunshi": "^0.27.5",
+    "gunshi": "^0.29.0",
     "jiti": "^2.4.2",
     "shell-quote": "^1.8.3"
   },
@@ -59,9 +59,9 @@
   },
   "devDependencies": {
     "@types/shell-quote": "1.7.5",
-    "memfs": "4.56.10",
+    "memfs": "4.56.11",
     "@gqlkit-ts/docs": "0.0.1",
-    "@gqlkit-ts/runtime": "0.2.0"
+    "@gqlkit-ts/runtime": "0.3.0"
   },
   "scripts": {
     "build": "tsc --build && bundle-docs --target ./docs",