@gqlkit-ts/cli 0.2.0 → 0.3.0

package/docs/getting-started.md

@@ -1,3 +1,8 @@
+---
+title: Getting Started
+description: Install gqlkit and create your first GraphQL schema from TypeScript.
+---
+
 # Getting Started
 
 ## Installation
@@ -17,6 +22,10 @@ yarn add @gqlkit-ts/runtime @graphql-tools/schema graphql
 yarn add -D @gqlkit-ts/cli
 ```
 
+> [!TIP]
+>
+> If you use AI coding agents like Claude Code or Codex, run `gqlkit docs` to set up gqlkit skills. See [Coding Agents](./coding-agents) for details.
+
 ## Project Structure
 
 gqlkit expects your types and resolvers to be in `src/gqlkit/schema/`:
@@ -52,27 +61,21 @@ export const { defineQuery, defineMutation, defineField } =
   createGqlkitApis<Context>();
 ```
 
-## Define Your First Type
+## Define Your First Type and Query
 
-Create a simple User type in `src/gqlkit/schema/user.ts`:
+Create a simple User type and query in `src/gqlkit/schema/user.ts`:
 
 ```typescript
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+
 export type User = {
   id: string;
   name: string;
   email: string | null;
 };
-```
-
-## Define a Query
-
-Create a query resolver in `src/gqlkit/schema/query.ts`:
-
-```typescript
-import { defineQuery } from "../gqlkit";
-import type { NoArgs } from "@gqlkit-ts/runtime";
-import type { User } from "./user";
 
+// NoArgs indicates this query takes no arguments
 export const me = defineQuery<NoArgs, User | null>(
   (_root, _args, ctx) => ctx.currentUser
 );

package/docs/index.md

@@ -1,33 +1,47 @@
 # gqlkit
 
-> gqlkit is a convention-driven code generator for GraphQL servers in TypeScript. Define GraphQL types and resolver signatures in TypeScript, then `gqlkit gen` generates GraphQL schema AST and a resolver map from your codebase.
+gqlkit generates GraphQL schema and resolver maps from TypeScript types and functions.
+
+## How it works
+
+1. Write TypeScript types in `src/gqlkit/schema/` → become GraphQL types
+2. Write resolver functions using `defineQuery`, `defineMutation`, `defineField` → become GraphQL resolvers
+3. Run `gqlkit gen` → outputs `typeDefs` and `resolvers` to `src/gqlkit/__generated__/`
+
+## Design principles
+
+- **Implement first**: Write types and resolvers, generate schema when ready. No edit-regenerate-implement loops.
+- **Just types and functions**: Plain TypeScript with a thin API. No decorators, no complex generics.
+- **Type-safe**: TypeScript types become GraphQL types. Resolver signatures checked at compile time.
 
 ## Documentation
 
-- [What is gqlkit?](./what-is-gqlkit.md): gqlkit is a convention-driven code generator for GraphQL servers in TypeScript.
-- [Getting Started](./getting-started.md): gqlkit expects your types and resolvers to be in `src/gqlkit/schema/`:
+- [What is gqlkit?](./what-is-gqlkit.md): Just types and functions — write TypeScript, generate GraphQL.
+- [Getting Started](./getting-started.md): Install gqlkit and create your first GraphQL schema from TypeScript.
+- [Coding Agents](./coding-agents.md): Set up AI coding agents like Claude Code and Codex to understand gqlkit conventions. (skip if reading via `gqlkit-guide` skill)
 
-## Schema Definition
+## CLI
 
-- [Schema Definition](./schema.md): gqlkit generates GraphQL schema from your TypeScript types. All exported types from `src/gqlkit/schema/` are automatically scanned and converted to GraphQL types.
-- [Object Types](./schema/objects.md): Plain TypeScript type exports become GraphQL Object types.
-- [Input Types](./schema/inputs.md): TypeScript types with `Input` suffix are treated as GraphQL input types.
-- [Queries & Mutations](./schema/queries-mutations.md): Define Query and Mutation fields using the `@gqlkit-ts/runtime` API.
-- [Field Resolvers](./schema/fields.md): Add computed fields to object types using `defineField`. Define them alongside the type.
-- [Scalar Types](./schema/scalars.md): gqlkit provides built-in scalar types and supports custom scalar definitions.
-- [Enum Types](./schema/enums.md): gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
-- [Union Types](./schema/unions.md): TypeScript union types of object types are converted to GraphQL union types.
-- [Interface Types](./schema/interfaces.md): Define GraphQL interface types using the `GqlInterface` utility type.
-- [Abstract Type Resolution](./schema/abstract-resolvers.md): GraphQL abstract types (unions and interfaces) require runtime type resolution to determine the concrete type of returned values. gqlkit provides `defineResolveType` and `defineIsTypeOf` to handle this.
-- [Documentation](./schema/documentation.md): gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.
-- [Custom Directives](./schema/directives.md): Define custom directives using the `GqlDirective` utility type and attach them using `GqlField` or `GqlObject`.
+- [Configuration](./configuration.md): Configure gqlkit via gqlkit.config.ts in your project root.
 
-## Integration
+## Schema Definition
 
-- [graphql-yoga](./integration/yoga.md): [graphql-yoga](https://the-guild.dev/graphql/yoga-server) is a batteries-included GraphQL server that works in any JavaScript runtime.
-- [Apollo Server](./integration/apollo.md): [Apollo Server](https://www.apollographql.com/docs/apollo-server/) is a popular GraphQL server with extensive features and ecosystem.
-- [Drizzle ORM](./integration/drizzle.md): [Drizzle ORM](https://orm.drizzle.team/) is a TypeScript ORM with type-safe schema definitions. gqlkit integrates seamlessly with Drizzle by using `InferSelectModel` and `InferInsertModel` to derive GraphQL types from your table definitions.
+- [Schema Definition](./schema.md): gqlkit generates GraphQL schema from your TypeScript types.
+- [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 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.
+- [Defining Union Types](./schema/unions.md): TypeScript union types of object types are converted to GraphQL union types.
+- [Defining Interface Types](./schema/interfaces.md): Define GraphQL interface types using the GqlInterface utility type.
+- [Resolving Abstract Types](./schema/abstract-resolvers.md): Handle runtime type resolution for GraphQL unions and interfaces.
+- [Adding Documentation to Schema](./schema/documentation.md): gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.
+- [Defining Custom Directives](./schema/directives.md): Define custom directives using the GqlDirective utility type.
 
-## Guides
+## Integration
 
-- [Configuration](./configuration.md): gqlkit can be configured via `gqlkit.config.ts` in your project root.
+- [Integration with graphql-yoga](./integration/yoga.md): Use gqlkit with graphql-yoga, a batteries-included GraphQL server.
+- [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.

package/docs/integration/apollo.md

@@ -1,3 +1,8 @@
+---
+title: Integration with Apollo Server
+description: Use gqlkit with Apollo Server, a popular GraphQL server.
+---
+
 # Apollo Server
 
 [Apollo Server](https://www.apollographql.com/docs/apollo-server/) is a popular GraphQL server with extensive features and ecosystem.
@@ -16,18 +21,9 @@ pnpm add @apollo/server
 yarn add @apollo/server
 ```
 
-## Creating the Schema
-
-First, create an executable schema using `makeExecutableSchema`:
-
-```typescript
-// src/schema.ts
-import { makeExecutableSchema } from "@graphql-tools/schema";
-import { typeDefs } from "./gqlkit/__generated__/schema";
-import { resolvers } from "./gqlkit/__generated__/resolvers";
+## Prerequisites
 
-export const schema = makeExecutableSchema({ typeDefs, resolvers });
-```
+Create an executable schema following the [Getting Started guide](../getting-started.md#create-graphql-schema).
 
 ## Basic Server
 
@@ -50,35 +46,7 @@ console.log(`Server is running on ${url}`);
 
 ## With Context
 
-If your resolvers use a context type, provide a context factory:
-
-```typescript
-// src/gqlkit/context.ts
-export type Context = {
-  currentUser: User | null;
-  db: Database;
-};
-```
-
-```typescript
-// src/gqlkit/gqlkit.ts
-import { createGqlkitApis } from "@gqlkit-ts/runtime";
-import type { Context } from "./context";
-
-export const { defineQuery, defineMutation, defineField } =
-  createGqlkitApis<Context>();
-```
-
-```typescript
-// src/gqlkit/schema/query.ts
-import { defineQuery } from "../gqlkit";
-import type { NoArgs } from "@gqlkit-ts/runtime";
-import type { User } from "./user";
-
-export const me = defineQuery<NoArgs, User | null>(
-  (_root, _args, ctx) => ctx.currentUser
-);
-```
+If your resolvers use a context type, first [set up context and resolver factories](../getting-started.md#set-up-context-and-resolver-factories), then provide a context factory to your server:
 
 ```typescript
 // src/server.ts

package/docs/integration/drizzle.md

@@ -1,3 +1,8 @@
+---
+title: Integration with Drizzle ORM
+description: Derive GraphQL types from Drizzle table definitions.
+---
+
 # Drizzle ORM
 
 [Drizzle ORM](https://orm.drizzle.team/) is a TypeScript ORM with type-safe schema definitions. gqlkit integrates seamlessly with Drizzle by using `InferSelectModel` and `InferInsertModel` to derive GraphQL types from your table definitions.
@@ -145,7 +150,7 @@ export const posts = defineField<User, NoArgs, Post[]>(
 
 ## Context with Database
 
-Set up the context type to include your database instance:
+Set up the context type to include your database instance. For basic setup, see [Set Up Context and Resolver Factories](../getting-started.md#set-up-context-and-resolver-factories).
 
 ```typescript
 // src/db/db.ts
@@ -167,15 +172,6 @@ export type Context = {
 };
 ```
 
-```typescript
-// src/gqlkit/gqlkit.ts
-import { createGqlkitApis } from "@gqlkit-ts/runtime";
-import type { Context } from "./context.js";
-
-export const { defineQuery, defineMutation, defineField } =
-  createGqlkitApis<Context>();
-```
-
 ## Complete Example
 
 See the [examples/with-drizzle](https://github.com/gqlkit/gqlkit/tree/main/examples/with-drizzle) directory for a complete working example with:

package/docs/integration/prisma.md

@@ -0,0 +1,196 @@
+---
+title: Integration with Prisma
+description: Derive GraphQL types from Prisma model types.
+---
+
+# Prisma
+
+[Prisma](https://www.prisma.io/) is a next-generation ORM for Node.js and TypeScript. gqlkit integrates seamlessly with Prisma by using its generated model types to derive GraphQL types from your schema definitions.
+
+## Installation
+
+```sh filename="npm"
+npm install prisma @prisma/client
+```
+
+```sh filename="pnpm"
+pnpm add prisma @prisma/client
+```
+
+```sh filename="yarn"
+yarn add prisma @prisma/client
+```
+
+## Defining the Schema
+
+Define your database schema in `prisma/schema.prisma`:
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/__generated__/prisma"
+}
+
+datasource db {
+  provider = "sqlite"
+}
+
+enum UserStatus {
+  active
+  inactive
+  suspended
+}
+
+model User {
+  id        String     @id @default(uuid())
+  name      String
+  email     String     @unique
+  status    UserStatus @default(active)
+  createdAt DateTime   @default(now()) @map("created_at")
+  posts     Post[]
+
+  @@map("users")
+}
+
+enum PostPriority {
+  low
+  medium
+  high
+}
+
+model Post {
+  id        String       @id @default(uuid())
+  title     String
+  content   String?
+  priority  PostPriority @default(medium)
+  authorId  String       @map("author_id")
+  createdAt DateTime     @default(now()) @map("created_at")
+  author    User         @relation(fields: [authorId], references: [id])
+
+  @@map("posts")
+}
+```
+
+Enum types defined in the Prisma schema are automatically converted to corresponding GraphQL enum types by gqlkit.
+
+## Defining Custom Scalars
+
+Define custom scalar types using `GqlScalar` for fields like timestamps:
+
+```typescript
+// src/gqlkit/schema/scalars.ts
+import type { GqlScalar } from "@gqlkit-ts/runtime";
+
+export type DateTime = GqlScalar<"DateTime", Date>;
+```
+
+## Exporting GraphQL Types
+
+Use Prisma's generated model types to export GraphQL types from your schema definitions:
+
+```typescript
+// src/gqlkit/schema/user.ts
+import type { Prisma } from "../../__generated__/prisma/client.js";
+
+// Export as GraphQL object type
+export type User = Prisma.UserModel;
+```
+
+This generates the following GraphQL schema:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+  SUSPENDED
+}
+
+type User {
+  id: String!
+  name: String!
+  email: String!
+  status: UserStatus!
+  createdAt: DateTime!
+}
+```
+
+## Defining Resolvers
+
+Define resolvers that use the derived types:
+
+```typescript
+// src/gqlkit/schema/user.ts
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { Prisma } from "../../__generated__/prisma/client.js";
+import { defineField, defineMutation, defineQuery } from "../gqlkit.js";
+import type { Post } from "./post.js";
+
+export type User = Prisma.UserModel;
+
+export const allUsers = defineQuery<NoArgs, User[]>(
+  async (_root, _args, ctx) => {
+    return ctx.db.user.findMany();
+  },
+);
+
+export const user = defineQuery<{ id: string }, User | null>(
+  async (_root, args, ctx) => {
+    return ctx.db.user.findUnique({
+      where: { id: args.id },
+    });
+  },
+);
+
+export const createUser = defineMutation<
+  { input: Omit<Prisma.UserCreateInput, "id" | "createdAt" | "posts"> },
+  User
+>(async (_root, args, ctx) => {
+  return ctx.db.user.create({
+    data: args.input,
+  });
+});
+
+export const posts = defineField<User, NoArgs, Post[]>(
+  async (parent, _args, ctx) => {
+    return ctx.db.post.findMany({
+      where: { authorId: parent.id },
+    });
+  },
+);
+```
+
+## Context with Database
+
+Set up the context type to include your Prisma client instance. For basic setup, see [Set Up Context and Resolver Factories](../getting-started.md#set-up-context-and-resolver-factories).
+
+```typescript
+// src/db/db.ts
+import { PrismaClient } from "../__generated__/prisma/client.js";
+
+export const prisma = new PrismaClient();
+export type PrismaDatabase = typeof prisma;
+```
+
+```typescript
+// src/gqlkit/context.ts
+import type { PrismaDatabase } from "../db/db.js";
+
+export type Context = {
+  db: PrismaDatabase;
+};
+```
+
+## Complete Example
+
+See the [examples/with-prisma](https://github.com/gqlkit/gqlkit/tree/main/examples/with-prisma) directory for a complete working example with:
+
+- SQLite database with DateTime scalar
+- Enum types (`UserStatus`, `PostPriority`)
+- User and Post types with relationships
+- Query, Mutation, and Field resolvers
+
+## Further Reading
+
+- [Prisma Documentation](https://www.prisma.io/docs)
+- [Prisma Client API Reference](https://www.prisma.io/docs/orm/reference/prisma-client-reference)

package/docs/integration/yoga.md

@@ -1,3 +1,8 @@
+---
+title: Integration with graphql-yoga
+description: Use gqlkit with graphql-yoga, a batteries-included GraphQL server.
+---
+
 # graphql-yoga
 
 [graphql-yoga](https://the-guild.dev/graphql/yoga-server) is a batteries-included GraphQL server that works in any JavaScript runtime.
@@ -16,18 +21,9 @@ pnpm add graphql-yoga
 yarn add graphql-yoga
 ```
 
-## Creating the Schema
-
-First, create an executable schema using `makeExecutableSchema`:
-
-```typescript
-// src/schema.ts
-import { makeExecutableSchema } from "@graphql-tools/schema";
-import { typeDefs } from "./gqlkit/__generated__/schema";
-import { resolvers } from "./gqlkit/__generated__/resolvers";
+## Prerequisites
 
-export const schema = makeExecutableSchema({ typeDefs, resolvers });
-```
+Create an executable schema following the [Getting Started guide](../getting-started.md#create-graphql-schema).
 
 ## Basic Server
 
@@ -47,35 +43,7 @@ server.listen(4000, () => {
 
 ## With Context
 
-If your resolvers use a context type, provide a context factory:
-
-```typescript
-// src/gqlkit/context.ts
-export type Context = {
-  currentUser: User | null;
-  db: Database;
-};
-```
-
-```typescript
-// src/gqlkit/gqlkit.ts
-import { createGqlkitApis } from "@gqlkit-ts/runtime";
-import type { Context } from "./context";
-
-export const { defineQuery, defineMutation, defineField } =
-  createGqlkitApis<Context>();
-```
-
-```typescript
-// src/gqlkit/schema/query.ts
-import { defineQuery } from "../gqlkit";
-import type { NoArgs } from "@gqlkit-ts/runtime";
-import type { User } from "./user";
-
-export const me = defineQuery<NoArgs, User | null>(
-  (_root, _args, ctx) => ctx.currentUser
-);
-```
+If your resolvers use a context type, first [set up context and resolver factories](../getting-started.md#set-up-context-and-resolver-factories), then provide a context factory to your server:
 
 ```typescript
 // src/server.ts

package/docs/schema/abstract-resolvers.md

@@ -1,3 +1,8 @@
+---
+title: Resolving Abstract Types
+description: Handle runtime type resolution for GraphQL unions and interfaces.
+---
+
 # Abstract Type Resolution
 
 GraphQL abstract types (unions and interfaces) require runtime type resolution to determine the concrete type of returned values. gqlkit provides `defineResolveType` and `defineIsTypeOf` to handle this.
@@ -11,6 +16,118 @@ When a GraphQL query returns an abstract type, the server needs to determine whi
 | `resolveType` | Abstract type (union/interface) | Type name string | Single resolver decides the type |
 | `isTypeOf` | Object type | Boolean | Each type checks if value matches |
 
+## Automatic resolveType Generation
+
+When Union or Interface member types have `__typename` or `$typeName` fields with string literal values, gqlkit automatically generates the `resolveType` function. No manual definition is needed.
+
+### Basic Example
+
+```typescript
+export interface User {
+  __typename: "User";
+  id: string;
+  name: string;
+}
+
+export interface Post {
+  __typename: "Post";
+  id: string;
+  title: string;
+}
+
+export type SearchResult = User | Post;
+// resolveType is automatically generated: (obj) => obj.__typename
+```
+
+### Using `$typeName`
+
+If you prefer not to use `__typename` (e.g., to avoid conflicts with GraphQL introspection), you can use `$typeName` instead:
+
+```typescript
+export interface User {
+  $typeName: "User";
+  id: string;
+  name: string;
+}
+
+export interface Post {
+  $typeName: "Post";
+  id: string;
+  title: string;
+}
+
+export type SearchResult = User | Post;
+// resolveType is automatically generated: (obj) => obj.$typeName
+```
+
+### Priority Rules
+
+When both `__typename` and `$typeName` are present, `__typename` takes priority:
+
+```typescript
+export interface User {
+  __typename: "User";  // This value is used
+  $typeName: "UserType";
+  id: string;
+}
+```
+
+### Mixed Patterns
+
+When some members use `__typename` and others use `$typeName`, gqlkit generates a fallback pattern:
+
+```typescript
+export interface User {
+  __typename: "User";
+  id: string;
+}
+
+export interface Post {
+  $typeName: "Post";
+  id: string;
+}
+
+export type SearchResult = User | Post;
+// resolveType: (obj) => obj.__typename ?? obj.$typeName
+```
+
+### Requirements
+
+For automatic generation, the typename field must be:
+
+- Named `__typename` or `$typeName`
+- A **non-optional** field
+- A **non-nullable** type
+- A **string literal** type (not `string`)
+
+```typescript
+// ✅ OK: Valid typename fields
+interface Valid {
+  __typename: "TypeA";       // string literal, required
+}
+
+// ❌ Error: These will not trigger auto-generation
+interface Invalid1 {
+  __typename?: "TypeA";      // optional field
+}
+
+interface Invalid2 {
+  __typename: "TypeA" | null; // nullable type
+}
+
+interface Invalid3 {
+  __typename: string;        // not a string literal
+}
+```
+
+### When to Use Manual defineResolveType
+
+Use `defineResolveType` manually when:
+
+- Your types don't have `__typename` or `$typeName` fields
+- You need custom resolution logic (e.g., checking other properties)
+- You want to override the automatic generation
+
 ## Using resolveType
 
 Define a `resolveType` resolver on a union or interface type to determine the concrete type.

package/docs/schema/directives.md

@@ -1,3 +1,8 @@
+---
+title: Defining Custom Directives
+description: Define custom directives using the GqlDirective utility type.
+---
+
 # Custom Directives
 
 Define custom directives using the `GqlDirective` utility type and attach them using `GqlField` or `GqlObject`.

package/docs/schema/documentation.md

@@ -1,3 +1,8 @@
+---
+title: Adding Documentation to Schema
+description: gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.
+---
+
 # Documentation
 
 gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.