@gqlkit-ts/cli 0.0.1 → 0.2.0

package/docs/integration/apollo.md

@@ -0,0 +1,109 @@
+# Apollo Server
+
+[Apollo Server](https://www.apollographql.com/docs/apollo-server/) is a popular GraphQL server with extensive features and ecosystem.
+
+## Installation
+
+```sh filename="npm"
+npm install @apollo/server
+```
+
+```sh filename="pnpm"
+pnpm add @apollo/server
+```
+
+```sh filename="yarn"
+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";
+
+export const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+## Basic Server
+
+Using the standalone server:
+
+```typescript
+// src/server.ts
+import { ApolloServer } from "@apollo/server";
+import { startStandaloneServer } from "@apollo/server/standalone";
+import { schema } from "./schema";
+
+const server = new ApolloServer({ schema });
+
+const { url } = await startStandaloneServer(server, {
+  listen: { port: 4000 },
+});
+
+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
+);
+```
+
+```typescript
+// src/server.ts
+import { ApolloServer } from "@apollo/server";
+import { startStandaloneServer } from "@apollo/server/standalone";
+import { schema } from "./schema";
+import type { Context } from "./gqlkit/context";
+
+const server = new ApolloServer<Context>({ schema });
+
+const { url } = await startStandaloneServer(server, {
+  listen: { port: 4000 },
+  context: async ({ req }) => {
+    const user = await getUserFromRequest(req);
+    return {
+      currentUser: user,
+      db: database,
+    };
+  },
+});
+
+console.log(`Server is running on ${url}`);
+```
+
+## Further Reading
+
+- [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
+- [Apollo Server Plugins](https://www.apollographql.com/docs/apollo-server/builtin-plugins)

package/docs/integration/drizzle.md

@@ -0,0 +1,191 @@
+# 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:
+
+```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;
+};
+```
+
+```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:
+
+- 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/yoga.md

@@ -0,0 +1,108 @@
+# graphql-yoga
+
+[graphql-yoga](https://the-guild.dev/graphql/yoga-server) is a batteries-included GraphQL server that works in any JavaScript runtime.
+
+## Installation
+
+```sh filename="npm"
+npm install graphql-yoga
+```
+
+```sh filename="pnpm"
+pnpm add graphql-yoga
+```
+
+```sh filename="yarn"
+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";
+
+export const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+## Basic Server
+
+```typescript
+// src/server.ts
+import { createServer } from "node:http";
+import { createYoga } from "graphql-yoga";
+import { schema } from "./schema";
+
+const yoga = createYoga({ schema });
+const server = createServer(yoga);
+
+server.listen(4000, () => {
+  console.log("Server is running on http://localhost:4000/graphql");
+});
+```
+
+## 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
+);
+```
+
+```typescript
+// src/server.ts
+import { createServer } from "node:http";
+import { createYoga } from "graphql-yoga";
+import { schema } from "./schema";
+import type { Context } from "./gqlkit/context";
+
+const yoga = createYoga<{}, Context>({
+  schema,
+  context: async ({ request }) => {
+    const user = await getUserFromRequest(request);
+    return {
+      currentUser: user,
+      db: database,
+    };
+  },
+});
+
+const server = createServer(yoga);
+
+server.listen(4000, () => {
+  console.log("Server is running on http://localhost:4000/graphql");
+});
+```
+
+## Further Reading
+
+- [graphql-yoga Documentation](https://the-guild.dev/graphql/yoga-server/docs)
+- [Envelop Plugins](https://the-guild.dev/graphql/envelop/plugins)

package/docs/schema/abstract-resolvers.md

@@ -0,0 +1,146 @@
+# 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.
+
+## Overview
+
+When a GraphQL query returns an abstract type, the server needs to determine which concrete type to use. There are two approaches:
+
+| Approach | Defined On | Returns | Use Case |
+|----------|------------|---------|----------|
+| `resolveType` | Abstract type (union/interface) | Type name string | Single resolver decides the type |
+| `isTypeOf` | Object type | Boolean | Each type checks if value matches |
+
+## Using resolveType
+
+Define a `resolveType` resolver on a union or interface type to determine the concrete type.
+
+### Union Example
+
+```typescript
+import { defineResolveType } from "../gqlkit";
+
+export interface User {
+  id: string;
+  name: string;
+}
+
+export interface Post {
+  id: string;
+  title: string;
+}
+
+export type SearchResult = User | Post;
+
+export const searchResultResolveType = defineResolveType<SearchResult>(
+  (value) => {
+    if ("name" in value) {
+      return "User";
+    }
+    return "Post";
+  }
+);
+```
+
+### Interface Example
+
+```typescript
+import { defineResolveType } from "../gqlkit";
+import { type GqlInterface, type IDString } from "@gqlkit-ts/runtime";
+
+export type Node = GqlInterface<{
+  id: IDString;
+}>;
+
+export const nodeResolveType = defineResolveType<Node>((value) => {
+  if ("name" in value) {
+    return "User";
+  }
+  if ("title" in value) {
+    return "Post";
+  }
+  throw new Error("Unknown Node type");
+});
+```
+
+### Resolver Function Signature
+
+```typescript
+(value: TAbstract, context: TContext, info: GraphQLResolveInfo) => string | Promise<string>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `value` | The resolved value to determine the type of |
+| `context` | The context object |
+| `info` | GraphQL resolve info |
+
+### Type Parameters
+
+`defineResolveType<TAbstract>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `TAbstract` | The abstract type (union or interface) to resolve |
+
+## Using isTypeOf
+
+Define an `isTypeOf` resolver on an object type to check if a value is of that type.
+
+### Basic Usage
+
+```typescript
+import { defineIsTypeOf } from "../gqlkit";
+
+export interface Dog {
+  kind: string;
+  name: string;
+  breed: string;
+}
+
+export interface Cat {
+  kind: string;
+  name: string;
+  indoor: boolean;
+}
+
+export type Animal = Dog | Cat;
+
+export const dogIsTypeOf = defineIsTypeOf<Dog>((value) => {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "dog"
+  );
+});
+
+export const catIsTypeOf = defineIsTypeOf<Cat>((value) => {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "cat"
+  );
+});
+```
+
+### Resolver Function Signature
+
+```typescript
+(value: unknown, context: TContext, info: GraphQLResolveInfo) => boolean | Promise<boolean>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `value` | The value to check (typed as `unknown`) |
+| `context` | The context object |
+| `info` | GraphQL resolve info |
+
+### Type Parameters
+
+`defineIsTypeOf<TObject>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `TObject` | The object type to check against |