@gqlkit-ts/cli 0.0.1 → 0.1.0

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 |

package/docs/schema/directives.md

@@ -0,0 +1,196 @@
+# Custom Directives
+
+Define custom directives using the `GqlDirective` utility type and attach them using `GqlField` or `GqlObject`.
+
+## Defining Directives
+
+```typescript
+// src/gqlkit/schema/directives.ts
+import { type GqlDirective } from "@gqlkit-ts/runtime";
+
+export type Role = "USER" | "ADMIN";
+
+// Directive with typed arguments
+export type AuthDirective<TArgs extends { role: Role[] }> = GqlDirective<
+  "auth",
+  TArgs,
+  "FIELD_DEFINITION"
+>;
+
+// Directive with multiple locations
+export type CacheDirective<TArgs extends { maxAge: number }> = GqlDirective<
+  "cache",
+  TArgs,
+  ["FIELD_DEFINITION", "OBJECT"]
+>;
+```
+
+Generates:
+
+```graphql
+directive @auth(role: [Role!]!) on FIELD_DEFINITION
+directive @cache(maxAge: Float!) on FIELD_DEFINITION | OBJECT
+```
+
+## GqlDirective Type Parameters
+
+`GqlDirective<Name, Args, Location>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `Name` | The directive name (without `@`) |
+| `Args` | The directive arguments type |
+| `Location` | Where the directive can be used (single or array) |
+
+### Directive Locations
+
+Common directive locations:
+
+| Location | Description |
+|----------|-------------|
+| `FIELD_DEFINITION` | Object type fields |
+| `OBJECT` | Object types |
+| `INPUT_FIELD_DEFINITION` | Input type fields |
+| `ARGUMENT_DEFINITION` | Field arguments |
+| `ENUM_VALUE` | Enum values |
+| `INTERFACE` | Interface types |
+
+## Attaching Directives to Fields
+
+Use `GqlField` to attach directives to object type fields:
+
+```typescript
+import { type GqlField, type IDString } from "@gqlkit-ts/runtime";
+import { type AuthDirective } from "./directives.js";
+
+export type User = {
+  id: IDString;
+  name: string;
+  // Field with directive
+  email: GqlField<string, { directives: [AuthDirective<{ role: ["ADMIN"] }>] }>;
+  // Nullable field with directive
+  phone: GqlField<string | null, { directives: [AuthDirective<{ role: ["USER"] }>] }>;
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  email: String! @auth(role: [ADMIN])
+  phone: String @auth(role: [USER])
+}
+```
+
+## Attaching Directives to Types
+
+Use `GqlObject` to attach directives to type definitions:
+
+```typescript
+import { type GqlObject, type IDString } from "@gqlkit-ts/runtime";
+import { type CacheDirective } from "./directives.js";
+
+export type Post = GqlObject<
+  {
+    id: IDString;
+    title: string;
+  },
+  { directives: [CacheDirective<{ maxAge: 60 }>] }
+>;
+```
+
+Generates:
+
+```graphql
+type Post @cache(maxAge: 60) {
+  id: ID!
+  title: String!
+}
+```
+
+## Attaching Directives to Query/Mutation Fields
+
+Add a third type parameter to `defineQuery`, `defineMutation`, or `defineField`:
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import { type AuthDirective } from "./directives.js";
+import type { User } from "./user.js";
+
+// Query field with directive
+export const me = defineQuery<
+  NoArgs,
+  User,
+  [AuthDirective<{ role: ["USER"] }>]
+>((_root, _args, ctx) => ctx.currentUser);
+```
+
+Generates:
+
+```graphql
+type Query {
+  me: User! @auth(role: [USER])
+}
+```
+
+## Attaching Directives to Field Resolvers
+
+```typescript
+import { defineField } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import { type AuthDirective } from "./directives.js";
+
+export const email = defineField<
+  User,
+  NoArgs,
+  string,
+  [AuthDirective<{ role: ["ADMIN"] }>]
+>((parent) => parent.email);
+```
+
+## Multiple Directives
+
+Attach multiple directives by adding them to the array:
+
+```typescript
+export type Post = GqlObject<
+  {
+    id: IDString;
+    title: string;
+  },
+  {
+    directives: [
+      CacheDirective<{ maxAge: 60 }>,
+      AuthDirective<{ role: ["USER"] }>
+    ]
+  }
+>;
+```
+
+## Combining with Other Options
+
+Combine directives with `implements` and `defaultValue`:
+
+```typescript
+export type Post = GqlObject<
+  {
+    id: IDString;
+    title: string;
+    createdAt: DateTime;
+  },
+  {
+    implements: [Node, Timestamped],
+    directives: [CacheDirective<{ maxAge: 60 }>]
+  }
+>;
+
+export type CreatePostInput = {
+  title: GqlField<string, {
+    defaultValue: "Untitled";
+    directives: [LengthDirective<{ min: 1; max: 200 }>];
+  }>;
+};
+```

package/docs/schema/documentation.md

@@ -0,0 +1,176 @@
+# Documentation
+
+gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.
+
+## Type Descriptions
+
+Add descriptions to types using TSDoc/JSDoc comments:
+
+```typescript
+/**
+ * A user in the system
+ */
+export type User = {
+  /** Unique identifier */
+  id: IDString;
+  /** Display name */
+  name: string;
+};
+```
+
+Generates:
+
+```graphql
+"""
+A user in the system
+
+Defined in: src/gqlkit/schema/user.ts
+"""
+type User {
+  """Unique identifier"""
+  id: ID!
+  """Display name"""
+  name: String!
+}
+```
+
+## Field Descriptions
+
+Add descriptions to individual fields:
+
+```typescript
+export type User = {
+  /** Unique identifier for the user */
+  id: IDString;
+
+  /**
+   * The user's display name.
+   * This is shown in the UI and can be changed by the user.
+   */
+  name: string;
+
+  /** Email address (null if not verified) */
+  email: string | null;
+};
+```
+
+## Resolver Descriptions
+
+Add descriptions to Query, Mutation, and Field resolvers:
+
+```typescript
+/** Get the currently authenticated user */
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => ctx.currentUser
+);
+
+/** Create a new user account */
+export const createUser = defineMutation<{ input: CreateUserInput }, User>(
+  (_root, args, ctx) => ctx.db.createUser(args.input)
+);
+
+/** Get user's profile URL */
+export const profileUrl = defineField<User, NoArgs, string>(
+  (parent) => `https://example.com/users/${parent.id}`
+);
+```
+
+## @deprecated Directive
+
+Mark fields and enum values as deprecated using the `@deprecated` JSDoc tag:
+
+### Deprecating Fields
+
+```typescript
+export type User = {
+  id: IDString;
+  name: string;
+  /**
+   * Legacy username
+   * @deprecated Use `name` field instead
+   */
+  username: string | null;
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  """Legacy username"""
+  username: String @deprecated(reason: "Use `name` field instead")
+}
+```
+
+### Deprecating Enum Values
+
+```typescript
+export enum UserStatus {
+  Active = "ACTIVE",
+  /**
+   * @deprecated Use `Inactive` instead
+   */
+  Pending = "PENDING",
+  Inactive = "INACTIVE",
+}
+```
+
+Generates:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  PENDING @deprecated(reason: "Use `Inactive` instead")
+  INACTIVE
+}
+```
+
+### Deprecating Resolvers
+
+```typescript
+/**
+ * Get user by username
+ * @deprecated Use `user(id: ID!)` instead
+ */
+export const userByUsername = defineQuery<{ username: string }, User | null>(
+  (_root, args, ctx) => ctx.db.findUserByUsername(args.username)
+);
+```
+
+## Multi-line Descriptions
+
+Multi-line comments are preserved:
+
+```typescript
+/**
+ * Represents a blog post.
+ *
+ * Posts can be in draft or published state.
+ * Only published posts are visible to other users.
+ */
+export type Post = {
+  id: IDString;
+  title: string;
+  content: string;
+};
+```
+
+Generates:
+
+```graphql
+"""
+Represents a blog post.
+
+Posts can be in draft or published state.
+Only published posts are visible to other users.
+
+Defined in: src/gqlkit/schema/post.ts
+"""
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+}
+```

package/docs/schema/enums.md

@@ -0,0 +1,162 @@
+# Enum Types
+
+gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
+
+## String Literal Unions
+
+String literal unions are automatically converted to GraphQL enum types:
+
+```typescript
+/**
+ * User account status
+ */
+export type UserStatus = "ACTIVE" | "INACTIVE" | "PENDING";
+```
+
+Generates:
+
+```graphql
+"""User account status"""
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+  PENDING
+}
+```
+
+## TypeScript Enums
+
+TypeScript string enums are also supported:
+
+```typescript
+export enum UserStatus {
+  Active = "ACTIVE",
+  Inactive = "INACTIVE",
+  Pending = "PENDING",
+}
+```
+
+Generates:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+  PENDING
+}
+```
+
+## Deprecating Enum Values
+
+Use the `@deprecated` JSDoc tag to mark enum values as deprecated:
+
+```typescript
+export enum UserStatus {
+  Active = "ACTIVE",
+  /**
+   * @deprecated Use `Inactive` instead
+   */
+  Pending = "PENDING",
+  Inactive = "INACTIVE",
+}
+```
+
+For string literal unions, use a separate type with JSDoc:
+
+```typescript
+/**
+ * User account status
+ */
+export type UserStatus =
+  | "ACTIVE"
+  | /** @deprecated Use INACTIVE instead */ "PENDING"
+  | "INACTIVE";
+```
+
+Generates:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  PENDING @deprecated(reason: "Use INACTIVE instead")
+  INACTIVE
+}
+```
+
+## Using Enums in Types
+
+```typescript
+export type User = {
+  id: string;
+  name: string;
+  status: UserStatus;
+};
+
+export type UpdateUserInput = {
+  status: UserStatus | null;
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: String!
+  name: String!
+  status: UserStatus!
+}
+
+input UpdateUserInput {
+  status: UserStatus
+}
+```
+
+## Invalid Enum Values
+
+Enum values that are not valid GraphQL identifiers are automatically skipped with a warning. gqlkit converts enum values to `SCREAMING_SNAKE_CASE`, and the converted name must:
+
+- Match the pattern `/^[_A-Za-z][_0-9A-Za-z]*$/`
+- Not start with `__` (reserved for GraphQL introspection)
+
+### String Literal Unions
+
+```typescript
+export type Status =
+  | "active"      // ✅ Converts to ACTIVE
+  | "inProgress"  // ✅ Converts to IN_PROGRESS
+  | "0pending"    // ⚠️ Skipped: converts to 0PENDING (starts with number)
+  | "__internal"; // ⚠️ Skipped: converts to __INTERNAL (starts with __)
+```
+
+Generates:
+
+```graphql
+enum Status {
+  ACTIVE
+  IN_PROGRESS
+}
+```
+
+### TypeScript Enums
+
+```typescript
+export enum Priority {
+  HIGH = "HIGH",           // ✅ Valid
+  MEDIUM = "MEDIUM",       // ✅ Valid
+  LOW = "LOW",             // ✅ Valid
+  "0INVALID" = "0INVALID", // ⚠️ Skipped: starts with number
+  __RESERVED = "__RESERVED", // ⚠️ Skipped: starts with __
+}
+```
+
+Generates:
+
+```graphql
+enum Priority {
+  HIGH
+  MEDIUM
+  LOW
+}
+```
+
+When enum values are skipped, gqlkit outputs a warning with the original name, converted name, and location.