@gqlkit-ts/cli 0.6.0 → 0.7.0

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/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.6.0",
+  "version": "0.7.0",
   "description": "Just types and functions — write TypeScript, generate GraphQL.",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,7 @@
   },
   "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.3.0"
   },