@gqlkit-ts/cli 0.1.0 → 0.3.0

package/docs/integration/drizzle.md

@@ -0,0 +1,187 @@
+---
+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.
+
+## Installation
+
+```sh filename="npm"
+npm install drizzle-orm postgres
+```
+
+```sh filename="pnpm"
+pnpm add drizzle-orm postgres
+```
+
+```sh filename="yarn"
+yarn add drizzle-orm postgres
+```
+
+## Defining Tables
+
+Define your database tables with Drizzle:
+
+```typescript
+// src/db/schema.ts
+import { pgEnum, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const userStatusEnum = pgEnum("user_status", [
+  "active",
+  "inactive",
+  "suspended",
+]);
+
+export const users = pgTable("users", {
+  id: uuid().primaryKey().defaultRandom(),
+  name: text().notNull(),
+  email: text().notNull().unique(),
+  status: userStatusEnum().notNull().default("active"),
+  createdAt: timestamp().notNull().defaultNow(),
+});
+
+export const posts = pgTable("posts", {
+  id: uuid().primaryKey().defaultRandom(),
+  title: text().notNull(),
+  content: text(),
+  priority: text({ enum: ["low", "medium", "high"] }).notNull().default("medium"),
+  authorId: uuid()
+    .notNull()
+    .references(() => users.id),
+  createdAt: timestamp().notNull().defaultNow(),
+});
+```
+
+Both `pgEnum()` and `text({ enum: [...] })` are supported for defining enum columns. gqlkit automatically generates corresponding GraphQL enum types from these definitions.
+
+## 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 Drizzle's type inference utilities to export GraphQL types from your table definitions:
+
+```typescript
+// src/gqlkit/schema/user.ts
+import type { InferSelectModel } from "drizzle-orm";
+import { users as usersTable } from "../../db/schema.js";
+
+// Export as GraphQL object type
+export type User = InferSelectModel<typeof usersTable>;
+```
+
+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 { InferInsertModel, InferSelectModel } from "drizzle-orm";
+import { eq } from "drizzle-orm";
+import { posts as postsTable, users as usersTable } from "../../db/schema.js";
+import { defineField, defineMutation, defineQuery } from "../gqlkit.js";
+import type { Post } from "./post.js";
+
+export type User = InferSelectModel<typeof usersTable>;
+
+export const allUsers = defineQuery<NoArgs, User[]>(
+  async (_root, _args, ctx) => {
+    return ctx.db.select().from(usersTable);
+  },
+);
+
+export const user = defineQuery<{ id: string }, User | null>(
+  async (_root, args, ctx) => {
+    const result = await ctx.db
+      .select()
+      .from(usersTable)
+      .where(eq(usersTable.id, args.id));
+    return result[0] ?? null;
+  },
+);
+
+export const createUser = defineMutation<
+  { input: Omit<InferInsertModel<typeof usersTable>, "id" | "createdAt"> },
+  User
+>(async (_root, args, ctx) => {
+  const result = await ctx.db.insert(usersTable).values(args.input).returning();
+  return result[0]!;
+});
+
+export const posts = defineField<User, NoArgs, Post[]>(
+  async (parent, _args, ctx) => {
+    return ctx.db
+      .select()
+      .from(postsTable)
+      .where(eq(postsTable.authorId, parent.id));
+  },
+);
+```
+
+## Context with Database
+
+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
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import * as schema from "./schema.js";
+
+const client = postgres(process.env.DATABASE_URL!);
+export const db = drizzle(client, { schema, casing: "snake_case" });
+export type Database = typeof db;
+```
+
+```typescript
+// src/gqlkit/context.ts
+import type { Database } from "../db/db.js";
+
+export type Context = {
+  db: Database;
+};
+```
+
+## Complete Example
+
+See the [examples/with-drizzle](https://github.com/gqlkit/gqlkit/tree/main/examples/with-drizzle) directory for a complete working example with:
+
+- PostgreSQL tables with DateTime scalar
+- Enum types using both `pgEnum()` and `text({ enum: [...] })`
+- User and Post types with relationships
+- Query, Mutation, and Field resolvers
+
+## Further Reading
+
+- [Drizzle ORM Documentation](https://orm.drizzle.team/docs/overview)
+- [Drizzle with PostgreSQL](https://orm.drizzle.team/docs/get-started/postgresql-new)

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.