@gqlkit-ts/cli 0.2.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.
@@ -273,6 +278,54 @@ export type User = {
 };
 ```
 
+### 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:
@@ -310,6 +363,52 @@ export function createResolvers() {
 
 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:

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.
@@ -122,6 +127,65 @@ 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.
@@ -91,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.
@@ -250,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.
@@ -157,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:

package/docs/schema/queries-mutations.md

@@ -1,29 +1,13 @@
+---
+title: Defining Queries and Mutations
+description: Define Query and Mutation fields using the @gqlkit-ts/runtime API.
+---
+
 # Queries & Mutations
 
 Define Query and Mutation fields using the `@gqlkit-ts/runtime` API.
 
-## Setup
-
-Create `src/gqlkit/context.ts` to define your context type:
-
-```typescript
-export type Context = {
-  userId: string;
-  db: Database;
-};
-```
-
-Create `src/gqlkit/gqlkit.ts` to export resolver factories:
-
-```typescript
-import { createGqlkitApis } from "@gqlkit-ts/runtime";
-import type { Context } from "./context";
-
-export const { defineQuery, defineMutation, defineField } =
-  createGqlkitApis<Context>();
-```
-
-Then import the factories in your schema files.
+> **Prerequisites**: This guide assumes you have completed the [basic setup](../getting-started.md#set-up-context-and-resolver-factories).
 
 ## Query Resolvers
 
@@ -179,6 +163,136 @@ Inline string literal unions and external TypeScript enums in arguments are also
 
 See [Field Resolvers](./fields.md) for more details on inline object arguments.
 
+## Inline Payload Types
+
+Return types can use inline object literals. gqlkit automatically generates GraphQL Object types with the naming convention `{PascalCaseResolverName}Payload`:
+
+```typescript
+export const updateUser = defineMutation<
+  { input: UpdateUserInput },
+  { user: User; updatedAt: string }
+>((_root, args, ctx) => ({
+  user: ctx.db.updateUser(args.input),
+  updatedAt: new Date().toISOString(),
+}));
+```
+
+Generates:
+
+```graphql
+type Mutation {
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+}
+
+type UpdateUserPayload {
+  user: User!
+  updatedAt: String!
+}
+```
+
+### Inline Union Payloads
+
+Union types with inline object literals generate GraphQL Union types. Each union member must have a `__typename` property with a string literal type:
+
+```typescript
+export const updateUser = defineMutation<
+  { input: UpdateUserInput },
+  | { __typename: "UpdateUserSuccess"; user: User }
+  | { __typename: "UpdateUserError"; message: string }
+>((_root, args, ctx) => {
+  const result = ctx.db.updateUser(args.input);
+  if (result.ok) {
+    return { __typename: "UpdateUserSuccess", user: result.user };
+  }
+  return { __typename: "UpdateUserError", message: result.error };
+});
+```
+
+Generates:
+
+```graphql
+type Mutation {
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+}
+
+union UpdateUserPayload = UpdateUserError | UpdateUserSuccess
+
+type UpdateUserSuccess {
+  user: User!
+}
+
+type UpdateUserError {
+  message: String!
+}
+```
+
+The `__resolveType` function is automatically generated based on the `__typename` property. See [Abstract Type Resolution](./abstract-resolvers.md) for more details.
+
+### Inline Enum Payloads
+
+String literal unions in return types generate GraphQL Enum types:
+
+```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
+}
+```
+
+### Nested Inline Types
+
+Inline types can be nested within payload objects:
+
+```typescript
+export const createOrder = defineMutation<
+  { input: CreateOrderInput },
+  {
+    order: {
+      id: string;
+      status: "pending" | "confirmed";
+      items: { productId: string; quantity: number }[];
+    };
+  }
+>(/* ... */);
+```
+
+Generates:
+
+```graphql
+type CreateOrderPayload {
+  order: CreateOrderPayloadOrder!
+}
+
+type CreateOrderPayloadOrder {
+  id: String!
+  status: CreateOrderPayloadOrderStatus!
+  items: [CreateOrderPayloadOrderItems!]!
+}
+
+enum CreateOrderPayloadOrderStatus {
+  PENDING
+  CONFIRMED
+}
+
+type CreateOrderPayloadOrderItems {
+  productId: String!
+  quantity: Float!
+}
+```
+
 ## Attaching Directives
 
 Add a third type parameter to attach directives to Query/Mutation fields:

package/docs/schema/scalars.md

@@ -1,3 +1,8 @@
+---
+title: Defining Scalar Types
+description: gqlkit provides built-in scalar types and supports custom scalar definitions.
+---
+
 # Scalar Types
 
 gqlkit provides built-in scalar types and supports custom scalar definitions.