@gqlkit-ts/cli 0.1.0 → 0.3.0

package/docs/schema/enums.md

@@ -1,3 +1,8 @@
+---
+title: Defining Enum Types
+description: gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
+---
+
 # Enum Types
 
 gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
@@ -111,6 +116,308 @@ input UpdateUserInput {
 }
 ```
 
+## Inline Enums
+
+When you define a string literal union or reference a TypeScript enum **inline** (without exporting it from the schema directory), gqlkit automatically generates a GraphQL enum type. This follows the same pattern as [inline objects](./objects.md#inline-objects).
+
+### Inline String Literal Unions
+
+String literal unions used directly in field or argument types generate enum types automatically:
+
+```typescript
+export type User = {
+  id: string;
+  name: string;
+  /** Current account status */
+  status: "active" | "inactive" | "pendingReview";
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: String!
+  name: String!
+  """Current account status"""
+  status: UserStatus!
+}
+
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+  PENDING_REVIEW
+}
+```
+
+The generated enum type name follows the convention `{ParentTypeName}{PascalCaseFieldName}`.
+
+### External TypeScript Enums
+
+TypeScript enums defined outside the schema directory are also automatically converted:
+
+```typescript
+// src/types/order.ts (outside schema directory)
+/**
+ * Order status in the system
+ */
+export enum OrderStatus {
+  /** Order is pending payment */
+  Pending = "pending",
+  /** Order is being processed */
+  Processing = "processing",
+  /** Order has been shipped */
+  Shipped = "shipped",
+}
+
+// src/gqlkit/schema/order.ts
+import { OrderStatus } from "../../types/order.js";
+
+export type Order = {
+  id: string;
+  status: OrderStatus;
+};
+```
+
+Generates:
+
+```graphql
+type Order {
+  id: String!
+  status: OrderStatus!
+}
+
+"""Order status in the system"""
+enum OrderStatus {
+  """Order is pending payment"""
+  PENDING
+  """Order is being processed"""
+  PROCESSING
+  """Order has been shipped"""
+  SHIPPED
+}
+```
+
+TSDoc comments on the enum and its values are preserved as GraphQL descriptions. The `@deprecated` tag is also supported.
+
+When the same external TypeScript enum is referenced in multiple places, gqlkit generates a single GraphQL enum type and reuses it across all references.
+
+### Inline Enum Naming Convention
+
+The naming convention for auto-generated enum types matches [inline objects](./objects.md#inline-objects):
+
+| Context | Naming Pattern | Example |
+|---------|----------------|---------|
+| Object field | `{ParentTypeName}{PascalCaseFieldName}` | `User.status` → `UserStatus` |
+| Input field | `{ParentTypeNameWithoutInputSuffix}{PascalCaseFieldName}Input` | `CreateUserInput.role` → `CreateUserRoleInput` |
+| Query/Mutation argument | `{PascalCaseFieldName}{PascalCaseArgName}Input` | `searchUsers(status: ...)` → `SearchUsersStatusInput` |
+| Field resolver argument | `{ParentTypeName}{PascalCaseFieldName}{PascalCaseArgName}Input` | `User.posts(filter: ...)` → `UserPostsFilterInput` |
+
+### Nullable Inline Enums
+
+Nullable inline enums are supported:
+
+```typescript
+export type User = {
+  id: string;
+  status: "active" | "inactive" | null;
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: String!
+  status: UserStatus
+}
+
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+}
+```
+
+### Arrays of Inline Enums
+
+Inline enums in array types are also supported:
+
+```typescript
+export type User = {
+  id: string;
+  roles: ("admin" | "editor" | "viewer")[];
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: String!
+  roles: [UserRoles!]!
+}
+
+enum UserRoles {
+  ADMIN
+  EDITOR
+  VIEWER
+}
+```
+
+### When Enums Are NOT Auto-Generated
+
+If you export a type from the schema directory, it is treated as an explicit type declaration and not auto-generated:
+
+```typescript
+// Exported from schema - used as-is, not auto-generated
+export type UserStatus = "active" | "inactive" | "pending";
+
+export type User = {
+  id: string;
+  status: UserStatus;  // References the exported type
+};
+```
+
+### Inline Enum Payloads
+
+String literal unions in resolver return types generate GraphQL Enum types with the naming convention `{ResolverName}Payload`:
+
+```typescript
+export const getStatus = defineQuery<NoArgs, "active" | "inactive" | "pending">(
+  (_root, _args, ctx) => ctx.db.getStatus()
+);
+```
+
+Generates:
+
+```graphql
+type Query {
+  getStatus: GetStatusPayload!
+}
+
+enum GetStatusPayload {
+  ACTIVE
+  INACTIVE
+  PENDING
+}
+```
+
+For field resolvers, the naming convention is `{ParentTypeName}{PascalCaseFieldName}Payload`:
+
+```typescript
+export const status = defineField<User, NoArgs, "online" | "offline" | "away">(
+  (parent) => parent.currentStatus
+);
+```
+
+Generates:
+
+```graphql
+type User {
+  status: UserStatusPayload!
+}
+
+enum UserStatusPayload {
+  ONLINE
+  OFFLINE
+  AWAY
+}
+```
+
+See [Queries & Mutations](./queries-mutations.md#inline-payload-types) for more details on inline payload types.
+
+## Automatic Case Conversion
+
+gqlkit automatically converts enum values to `SCREAMING_SNAKE_CASE` format, which is the GraphQL convention:
+
+```typescript
+export type UserStatus = "active" | "inProgress" | "pending_review" | "on-hold";
+```
+
+Generates:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  IN_PROGRESS
+  PENDING_REVIEW
+  ON_HOLD
+}
+```
+
+When conversion changes the original value, gqlkit generates resolver mappings to translate between GraphQL and TypeScript values:
+
+```typescript
+// Generated resolvers.ts
+export function createResolvers() {
+  return {
+    UserStatus: {
+      ACTIVE: "active",
+      IN_PROGRESS: "inProgress",
+      PENDING_REVIEW: "pending_review",
+      ON_HOLD: "on-hold",
+    },
+  };
+}
+```
+
+If values are already in `SCREAMING_SNAKE_CASE`, no resolver mapping is generated.
+
+### Automatic Prefix Stripping
+
+When all enum values share a common prefix that matches the enum name, gqlkit automatically strips the prefix to produce cleaner GraphQL values:
+
+```typescript
+export type UserStatus = "USER_STATUS_ACTIVE" | "USER_STATUS_INACTIVE" | "USER_STATUS_PENDING";
+```
+
+Generates:
+
+```graphql
+enum UserStatus {
+  ACTIVE
+  INACTIVE
+  PENDING
+}
+```
+
+This works with various naming conventions:
+
+| TypeScript Enum | Values | Generated GraphQL Values |
+|-----------------|--------|--------------------------|
+| `UserStatus` | `USER_STATUS_ACTIVE`, `USER_STATUS_INACTIVE` | `ACTIVE`, `INACTIVE` |
+| `orderStatus` | `ORDER_STATUS_PENDING`, `ORDER_STATUS_SHIPPED` | `PENDING`, `SHIPPED` |
+| `Status` | `STATUS_ACTIVE`, `STATUS_INACTIVE` | `ACTIVE`, `INACTIVE` |
+
+Prefix stripping is **not applied** when:
+
+- Not all values share the common prefix
+- Stripping would result in an empty value (e.g., `USER_STATUS_` for `UserStatus`)
+
+When prefix stripping is applied, gqlkit generates resolver mappings to preserve the original TypeScript values:
+
+```typescript
+// Generated resolvers.ts
+export function createResolvers() {
+  return {
+    UserStatus: {
+      ACTIVE: "USER_STATUS_ACTIVE",
+      INACTIVE: "USER_STATUS_INACTIVE",
+      PENDING: "USER_STATUS_PENDING",
+    },
+  };
+}
+```
+
+### Duplicate Value Detection
+
+If multiple TypeScript values convert to the same GraphQL enum value, gqlkit reports a `DUPLICATE_ENUM_VALUE_AFTER_CONVERSION` error:
+
+```typescript
+// Error: 'activeUser' and 'active_user' both convert to ACTIVE_USER
+export type Status = "activeUser" | "active_user" | "pending";
+```
+
 ## 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:

package/docs/schema/fields.md

@@ -1,3 +1,8 @@
+---
+title: Defining Field Resolvers
+description: Add computed fields to object types using defineField.
+---
+
 # Field Resolvers
 
 Add computed fields to object types using `defineField`. Define them alongside the type.
@@ -120,6 +125,67 @@ input UserPostsFilterInput {
 }
 ```
 
+Inline string literal unions and external TypeScript enums in arguments are also automatically converted to GraphQL enum types. See [Inline Enums](./enums.md#inline-enums) for details.
+
+## Inline Payload Types
+
+Field resolver return types can use inline object literals. gqlkit automatically generates GraphQL Object types with the naming convention `{ParentTypeName}{PascalCaseFieldName}Payload`:
+
+```typescript
+export const statistics = defineField<
+  User,
+  NoArgs,
+  { postCount: number; followerCount: number; isActive: boolean }
+>((parent, _args, ctx) => ctx.db.getUserStatistics(parent.id));
+```
+
+Generates:
+
+```graphql
+type User {
+  statistics: UserStatisticsPayload!
+}
+
+type UserStatisticsPayload {
+  postCount: Float!
+  followerCount: Float!
+  isActive: Boolean!
+}
+```
+
+### Inline Union Payloads
+
+Union types with inline object literals generate GraphQL Union types. Each union member must have a `__typename` property:
+
+```typescript
+export const verification = defineField<
+  User,
+  NoArgs,
+  | { __typename: "Verified"; verifiedAt: string }
+  | { __typename: "Unverified"; reason: string }
+>((parent) => parent.verification);
+```
+
+Generates:
+
+```graphql
+type User {
+  verification: UserVerificationPayload!
+}
+
+union UserVerificationPayload = Unverified | Verified
+
+type Verified {
+  verifiedAt: String!
+}
+
+type Unverified {
+  reason: String!
+}
+```
+
+See [Queries & Mutations](./queries-mutations.md#inline-payload-types) for more details on inline payload types.
+
 ## Default Values in Arguments
 
 Default values in Input Objects are applied to resolver arguments:

package/docs/schema/index.md

@@ -1,3 +1,8 @@
+---
+title: Schema Definition
+description: gqlkit generates GraphQL schema from your TypeScript types.
+---
+
 # Schema Definition
 
 gqlkit generates GraphQL schema from your TypeScript types. All exported types from `src/gqlkit/schema/` are automatically scanned and converted to GraphQL types.
@@ -23,6 +28,22 @@ gqlkit maps TypeScript types to GraphQL types as follows:
 | Union with `*Input` suffix | `@oneOf` input object |
 | `GqlInterface<T>` | Interface type |
 | `GqlScalar<Name, Base>` | Custom scalar |
+| `NoArgs` | Indicates resolver takes no arguments |
+
+## Naming Conventions
+
+gqlkit generates type names using predictable conventions:
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| Object field (inline) | `{ParentType}{Field}` | `User.profile` → `UserProfile` |
+| Input field (inline) | `{ParentWithoutInput}{Field}Input` | `CreateUserInput.address` → `CreateUserAddressInput` |
+| Query/Mutation arg | `{Resolver}{Arg}Input` | `searchUsers(filter)` → `SearchUsersFilterInput` |
+| Field resolver arg | `{Parent}{Field}{Arg}Input` | `User.posts(filter)` → `UserPostsFilterInput` |
+| Inline enum | Same as parent context | `User.status` → `UserStatus` |
+| Payload type | `{Resolver}Payload` | `updateUser` → `UpdateUserPayload` |
+
+For complete details on inline enum naming, see [Inline Enums](./enums.md#inline-enums).
 
 ## Project Layout
 

package/docs/schema/inputs.md

@@ -1,3 +1,8 @@
+---
+title: Defining Input Types
+description: TypeScript types with Input suffix are treated as GraphQL input types.
+---
+
 # Input Types
 
 TypeScript types with `Input` suffix are treated as GraphQL input types.
@@ -58,6 +63,8 @@ input CreateUserProfileInput {
 
 Nested inline objects generate types with concatenated names (e.g., `UserProfileInput.address` → `UserProfileAddressInput`).
 
+Similarly, inline string literal unions and external TypeScript enums are automatically converted to GraphQL enum types. See [Inline Enums](./enums.md#inline-enums) for details.
+
 ## @oneOf Input Objects
 
 Union types with `Input` suffix using inline object literals generate `@oneOf` input objects. Each union member must be an inline object literal with exactly one property. Property values can be scalar types, enum types, or references to Input Object types:
@@ -89,6 +96,94 @@ input ProductInput @oneOf {
 
 Each property becomes a nullable field in the generated input type. The `@oneOf` directive ensures exactly one field is provided at runtime.
 
+### Inline @oneOf in Input Fields
+
+Union types can be used as field types within Input Objects to create nested `@oneOf` input objects. The generated type name follows the convention `{ParentTypeNameWithoutInputSuffix}{PascalCaseFieldName}Input`:
+
+```typescript
+export type CreateUserInput = {
+  name: string;
+  /**
+   * User identifier - either by ID or email
+   */
+  identifier: { id: string } | { email: string };
+};
+```
+
+Generates:
+
+```graphql
+input CreateUserInput {
+  name: String!
+  """User identifier - either by ID or email"""
+  identifier: CreateUserIdentifierInput!
+}
+
+input CreateUserIdentifierInput @oneOf {
+  email: String
+  id: String
+}
+```
+
+### Inline @oneOf in Resolver Arguments
+
+Inline unions in resolver arguments are also converted to `@oneOf` input objects:
+
+**Query/Mutation arguments** - naming convention: `{PascalCaseResolverName}{PascalCaseArgPath}Input`
+
+```typescript
+export const findUser = defineQuery<
+  {
+    criteria: {
+      identifier: { id: string } | { email: string };
+    };
+  },
+  User | null
+>(...);
+```
+
+Generates:
+
+```graphql
+input FindUserCriteriaIdentifierInput @oneOf {
+  email: String
+  id: String
+}
+
+input FindUserCriteriaInput {
+  identifier: FindUserCriteriaIdentifierInput!
+}
+
+type Query {
+  findUser(criteria: FindUserCriteriaInput!): User
+}
+```
+
+**Field resolver arguments** - naming convention: `{ParentTypeName}{PascalCaseFieldName}{PascalCaseArgPath}Input`
+
+```typescript
+export const posts = defineField<
+  User,
+  {
+    filter: { status: string } | { createdAfter: string } | null;
+  },
+  Post[]
+>(...);
+```
+
+Generates:
+
+```graphql
+input UserPostsFilterInput @oneOf {
+  createdAfter: String
+  status: String
+}
+
+type User {
+  posts(filter: UserPostsFilterInput): [Post!]!
+}
+```
+
 ## Default Values
 
 Specify default values for Input Object fields using `GqlField` with the `defaultValue` option.
@@ -248,30 +343,37 @@ export type BadInput = {
 };
 ```
 
-## Invalid Field Names
-
-Input field names that are not valid GraphQL identifiers are automatically skipped with a warning. Valid GraphQL names must:
+## Excluding Fields
 
-- Match the pattern `/^[_A-Za-z][_0-9A-Za-z]*$/`
-- Not start with `__` (reserved for GraphQL introspection)
+Use `GqlObject` with the `ignoreFields` option to exclude specific fields from the generated Input Object. This is useful for internal fields that should not be accepted from clients:
 
 ```typescript
-export type CreateUserInput = {
-  name: string;            // ✅ Valid
-  _metadata: string;       // ✅ Valid (single underscore is OK)
-  "123abc": string;        // ⚠️ Skipped: starts with a number
-  __private: string;       // ⚠️ Skipped: starts with __
-  "hyphen-field": string;  // ⚠️ Skipped: contains hyphen
-};
+import { type GqlObject } from "@gqlkit-ts/runtime";
+
+/**
+ * Input for creating a user.
+ */
+export type CreateUserInput = GqlObject<
+  {
+    name: string;
+    email: string;
+    internalData: string;  // Internal field - excluded from schema
+    trackingId: string;    // Internal field - excluded from schema
+  },
+  { ignoreFields: "internalData" | "trackingId" }
+>;
 ```
 
-Generates (invalid fields are skipped):
+Generates:
 
 ```graphql
+"""Input for creating a user."""
 input CreateUserInput {
   name: String!
-  _metadata: String!
+  email: String!
 }
 ```
 
-When fields are skipped, gqlkit outputs a warning with the field name and location.
+## Invalid Field Names
+
+Input field names follow the same validation rules as object type fields. See [Invalid Field Names](./objects.md#invalid-field-names) for details.

package/docs/schema/interfaces.md

@@ -1,3 +1,8 @@
+---
+title: Defining Interface Types
+description: Define GraphQL interface types using the GqlInterface utility type.
+---
+
 # Interface Types
 
 Define GraphQL interface types using the `GqlInterface` utility type.
@@ -163,7 +168,32 @@ See [Object Types](./objects.md) for more details on implementing interfaces.
 
 ## Runtime Type Resolution
 
-When GraphQL executes a query that returns an interface type, it needs to determine the concrete type at runtime. You can use either `defineResolveType` on the interface or `defineIsTypeOf` on each implementing type.
+When GraphQL executes a query that returns an interface type, it needs to determine the concrete type at runtime.
+
+### Automatic Resolution
+
+If all implementing types have `__typename` or `$typeName` fields with string literal values, gqlkit automatically generates the `resolveType` function:
+
+```typescript
+export interface User {
+  __typename: "User";
+  id: IDString;
+  name: string;
+}
+
+export interface Post {
+  __typename: "Post";
+  id: IDString;
+  title: string;
+}
+
+// Both User and Post implement Node
+// resolveType is automatically generated - no manual definition needed
+```
+
+### Manual Resolution
+
+For types without `__typename` or `$typeName`, use `defineResolveType` on the interface or `defineIsTypeOf` on each implementing type:
 
 ```typescript
 import { defineResolveType } from "../gqlkit";

package/docs/schema/objects.md

@@ -1,3 +1,8 @@
+---
+title: Defining Object Types
+description: Plain TypeScript type exports become GraphQL Object types.
+---
+
 # Object Types
 
 Plain TypeScript type exports become GraphQL Object types.
@@ -102,6 +107,8 @@ type UserProfile {
 
 Nested inline objects generate types with concatenated names (e.g., `User.profile.address` → `UserProfileAddress`).
 
+Similarly, inline string literal unions and external TypeScript enums are automatically converted to GraphQL enum types. See [Inline Enums](./enums.md#inline-enums) for details.
+
 ## Implementing Interfaces
 
 Use `GqlObject` with the `implements` option to declare that a type implements interfaces:
@@ -155,6 +162,41 @@ export type Post = GqlObject<
 
 See [Interfaces](./interfaces.md) for more details on defining interface types.
 
+## Excluding Fields
+
+Use `GqlObject` with the `ignoreFields` option to exclude specific fields from the generated GraphQL schema. This is useful for internal fields that should not be exposed in the public API:
+
+```typescript
+import { type GqlObject, type IDString } from "@gqlkit-ts/runtime";
+
+/**
+ * A user in the system.
+ */
+export type User = GqlObject<
+  {
+    id: IDString;
+    name: string;
+    email: string | null;
+    internalId: string;  // Internal field - excluded from schema
+    cacheKey: string;    // Internal field - excluded from schema
+  },
+  { ignoreFields: "internalId" | "cacheKey" }
+>;
+```
+
+Generates:
+
+```graphql
+"""A user in the system."""
+type User {
+  id: ID!
+  name: String!
+  email: String
+}
+```
+
+The excluded fields (`internalId` and `cacheKey`) are not included in the generated schema, and no resolvers are generated for them.
+
 ## Invalid Field Names
 
 Field names that are not valid GraphQL identifiers are automatically skipped with a warning. Valid GraphQL names must: