@gqlkit-ts/cli 0.0.1 → 0.2.0

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!
+}
+```