@gqlkit-ts/cli 0.0.1 → 0.2.0

package/docs/schema/inputs.md

@@ -0,0 +1,279 @@
+# Input Types
+
+TypeScript types with `Input` suffix are treated as GraphQL input types.
+
+## Basic Usage
+
+```typescript
+/** Input for creating a new user */
+export interface CreateUserInput {
+  name: string;
+  email: string | null;
+}
+```
+
+Generates:
+
+```graphql
+"""Input for creating a new user"""
+input CreateUserInput {
+  name: String!
+  email: String
+}
+```
+
+## Inline Objects
+
+Input types can use inline object literals for nested structures. gqlkit automatically generates Input Object types with the naming convention `{ParentTypeNameWithoutInputSuffix}{PascalCaseFieldName}Input`:
+
+```typescript
+import type { GqlField, Int } from "@gqlkit-ts/runtime";
+
+export type CreateUserInput = {
+  name: string;
+  /** Profile information */
+  profile: {
+    bio: string | null;
+    /** User's age with default value */
+    age: GqlField<Int | null, { defaultValue: 18 }>;
+  };
+};
+```
+
+Generates:
+
+```graphql
+input CreateUserInput {
+  name: String!
+  """Profile information"""
+  profile: CreateUserProfileInput!
+}
+
+input CreateUserProfileInput {
+  """User's age with default value"""
+  age: Int = 18
+  bio: String
+}
+```
+
+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:
+
+```typescript
+/**
+ * Specifies how to identify a product.
+ * Exactly one field must be provided.
+ */
+export type ProductInput =
+  | { id: string }
+  | { name: string }
+  | { location: LocationInput };
+```
+
+Generates:
+
+```graphql
+"""
+Specifies how to identify a product.
+Exactly one field must be provided.
+"""
+input ProductInput @oneOf {
+  id: String
+  location: LocationInput
+  name: String
+}
+```
+
+Each property becomes a nullable field in the generated input type. The `@oneOf` directive ensures exactly one field is provided at runtime.
+
+## Default Values
+
+Specify default values for Input Object fields using `GqlField` with the `defaultValue` option.
+
+### Basic Default Values
+
+```typescript
+import { type GqlField, type Int } from "@gqlkit-ts/runtime";
+
+export type PaginationInput = {
+  limit: GqlField<Int, { defaultValue: 10 }>;
+  offset: GqlField<Int, { defaultValue: 0 }>;
+  includeArchived: GqlField<boolean, { defaultValue: false }>;
+};
+
+export type SearchInput = {
+  query: string;
+  caseSensitive: GqlField<boolean, { defaultValue: true }>;
+  maxResults: GqlField<Int | null, { defaultValue: null }>;
+};
+
+export type GreetingInput = {
+  name: GqlField<string, { defaultValue: "World" }>;
+  prefix: GqlField<string, { defaultValue: "Hello" }>;
+};
+```
+
+Generates:
+
+```graphql
+input PaginationInput {
+  limit: Int! = 10
+  offset: Int! = 0
+  includeArchived: Boolean! = false
+}
+
+input SearchInput {
+  query: String!
+  caseSensitive: Boolean! = true
+  maxResults: Int = null
+}
+
+input GreetingInput {
+  name: String! = "World"
+  prefix: String! = "Hello"
+}
+```
+
+### Complex Default Values
+
+Default values support arrays, objects, and enum values:
+
+```typescript
+export type Status = "ACTIVE" | "INACTIVE" | "PENDING";
+
+export type Priority = "LOW" | "MEDIUM" | "HIGH";
+
+export type NestedConfig = {
+  enabled: boolean;
+  value: Int;
+};
+
+export type FilterInput = {
+  status: GqlField<Status, { defaultValue: "ACTIVE" }>;
+  priorities: GqlField<Priority[], { defaultValue: ["MEDIUM", "HIGH"] }>;
+  tags: GqlField<string[], { defaultValue: ["default"] }>;
+};
+
+export type SettingsInput = {
+  config: GqlField<NestedConfig, { defaultValue: { enabled: true; value: 100 } }>;
+  limits: GqlField<Int[], { defaultValue: [10, 20, 30] }>;
+};
+```
+
+Generates:
+
+```graphql
+input FilterInput {
+  status: Status! = ACTIVE
+  priorities: [Priority!]! = [MEDIUM, HIGH]
+  tags: [String!]! = ["default"]
+}
+
+input SettingsInput {
+  config: NestedConfig! = {enabled: true, value: 100}
+  limits: [Int!]! = [10, 20, 30]
+}
+```
+
+### Default Values with Directives
+
+You can combine `defaultValue` with `directives`:
+
+```typescript
+import { type GqlField, type GqlDirective, type Int } from "@gqlkit-ts/runtime";
+
+export type LengthDirective<TArgs extends { min: number; max: number }> =
+  GqlDirective<"length", TArgs, "INPUT_FIELD_DEFINITION" | "ARGUMENT_DEFINITION">;
+
+export type RangeDirective<TArgs extends { min: number; max: number }> =
+  GqlDirective<"range", TArgs, "INPUT_FIELD_DEFINITION" | "ARGUMENT_DEFINITION">;
+
+export type CreateUserInput = {
+  name: GqlField<string, {
+    defaultValue: "Anonymous";
+    directives: [LengthDirective<{ min: 1; max: 100 }>];
+  }>;
+  age: GqlField<Int, {
+    defaultValue: 18;
+    directives: [RangeDirective<{ min: 0; max: 150 }>];
+  }>;
+  email: GqlField<string | null, {
+    defaultValue: null;
+    directives: [LengthDirective<{ min: 5; max: 255 }>];
+  }>;
+};
+```
+
+Generates:
+
+```graphql
+input CreateUserInput {
+  name: String! = "Anonymous" @length(min: 1, max: 100)
+  age: Int! = 18 @range(min: 0, max: 150)
+  email: String = null @length(min: 5, max: 255)
+}
+```
+
+### Supported Default Value Types
+
+| Value type | Example | GraphQL output |
+|------------|---------|----------------|
+| String | `"hello"` | `"hello"` |
+| Number (Int) | `10` | `10` |
+| Number (Float) | `3.14` | `3.14` |
+| Boolean | `true`, `false` | `true`, `false` |
+| Null | `null` | `null` |
+| Array | `[1, 2, 3]` | `[1, 2, 3]` |
+| Object | `{ key: "value" }` | `{key: "value"}` |
+| Enum | `"ACTIVE"` (when field type is enum) | `ACTIVE` |
+
+### Literal Types Required
+
+Default values must be specified as TypeScript literal types. Non-literal types will cause a warning:
+
+```typescript
+// ✅ OK: Literal types
+export type GoodInput = {
+  limit: GqlField<Int, { defaultValue: 10 }>;
+  name: GqlField<string, { defaultValue: "default" }>;
+};
+
+// ❌ Error: Non-literal types
+export type BadInput = {
+  limit: GqlField<Int, { defaultValue: number }>;     // Warning: must be literal
+  name: GqlField<string, { defaultValue: string }>;   // Warning: must be literal
+};
+```
+
+## Invalid Field Names
+
+Input field names that are not valid GraphQL identifiers are automatically skipped with a warning. Valid GraphQL names must:
+
+- Match the pattern `/^[_A-Za-z][_0-9A-Za-z]*$/`
+- Not start with `__` (reserved for GraphQL introspection)
+
+```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
+};
+```
+
+Generates (invalid fields are skipped):
+
+```graphql
+input CreateUserInput {
+  name: String!
+  _metadata: String!
+}
+```
+
+When fields are skipped, gqlkit outputs a warning with the field name and location.

package/docs/schema/interfaces.md

@@ -0,0 +1,178 @@
+# Interface Types
+
+Define GraphQL interface types using the `GqlInterface` utility type.
+
+## Basic Usage
+
+```typescript
+// src/gqlkit/schema/node.ts
+import { type GqlInterface, type IDString } from "@gqlkit-ts/runtime";
+import type { DateTime } from "./scalars.js";
+
+/**
+ * Node interface - represents any entity with a unique identifier.
+ */
+export type Node = GqlInterface<{
+  /** Global unique identifier */
+  id: IDString;
+}>;
+
+/**
+ * Timestamped interface - entities that track creation time.
+ */
+export type Timestamped = GqlInterface<{
+  createdAt: DateTime;
+}>;
+```
+
+Generates:
+
+```graphql
+"""Node interface - represents any entity with a unique identifier."""
+interface Node {
+  """Global unique identifier"""
+  id: ID!
+}
+
+"""Timestamped interface - entities that track creation time."""
+interface Timestamped {
+  createdAt: DateTime!
+}
+```
+
+## GqlInterface Type Parameters
+
+`GqlInterface<T, Meta?>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `T` | The interface fields definition |
+| `Meta` | Optional: `{ implements: [...] }` for interface inheritance |
+
+## Interface Inheritance
+
+Interfaces can extend other interfaces:
+
+```typescript
+/**
+ * Entity interface - combines Node and Timestamped.
+ */
+export type Entity = GqlInterface<
+  {
+    id: IDString;
+    createdAt: DateTime;
+  },
+  { implements: [Node, Timestamped] }
+>;
+```
+
+Generates:
+
+```graphql
+"""Entity interface - combines Node and Timestamped."""
+interface Entity implements Node & Timestamped {
+  id: ID!
+  createdAt: DateTime!
+}
+```
+
+## Implementing Interfaces
+
+Use `GqlObject` with the `implements` option to declare that a type implements interfaces:
+
+```typescript
+import { type GqlObject, type IDString } from "@gqlkit-ts/runtime";
+import type { Node, Timestamped } from "./node.js";
+import type { DateTime } from "./scalars.js";
+
+/**
+ * A user in the system.
+ */
+export type User = GqlObject<
+  {
+    id: IDString;
+    name: string;
+    email: string | null;
+    createdAt: DateTime;
+  },
+  { implements: [Node, Timestamped] }
+>;
+```
+
+Generates:
+
+```graphql
+"""A user in the system."""
+type User implements Node & Timestamped {
+  id: ID!
+  name: String!
+  email: String
+  createdAt: DateTime!
+}
+```
+
+## Combining with Directives
+
+You can combine `implements` with `directives`:
+
+```typescript
+import { type GqlObject, type IDString } from "@gqlkit-ts/runtime";
+import type { Node, Timestamped } from "./node.js";
+import type { DateTime } from "./scalars.js";
+import type { CacheDirective } from "./directives.js";
+
+export type Post = GqlObject<
+  {
+    id: IDString;
+    title: string;
+    createdAt: DateTime;
+  },
+  {
+    implements: [Node, Timestamped],
+    directives: [CacheDirective<{ maxAge: 60 }>]
+  }
+>;
+```
+
+Generates:
+
+```graphql
+type Post @cache(maxAge: 60) implements Node & Timestamped {
+  id: ID!
+  title: String!
+  createdAt: DateTime!
+}
+```
+
+## Interface Field Resolvers
+
+Add computed fields to interface types using `defineField`:
+
+```typescript
+import { defineField } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { Node } from "./node.js";
+
+/** Get the typename of a Node */
+export const __typename = defineField<Node, NoArgs, string>(
+  (parent) => parent.constructor.name
+);
+```
+
+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.
+
+```typescript
+import { defineResolveType } from "../gqlkit";
+
+export const nodeResolveType = defineResolveType<Node>((value) => {
+  if ("name" in value) return "User";
+  if ("title" in value) return "Post";
+  throw new Error("Unknown Node type");
+});
+```
+
+See [Abstract Type Resolution](./abstract-resolvers.md) for complete documentation.

package/docs/schema/objects.md

@@ -0,0 +1,188 @@
+# Object Types
+
+Plain TypeScript type exports become GraphQL Object types.
+
+## Basic Usage
+
+Export a TypeScript type or interface:
+
+```typescript
+// src/gqlkit/schema/user.ts
+import { defineQuery, defineField } from "../gqlkit";
+import type { IDString, Int, NoArgs } from "@gqlkit-ts/runtime";
+
+/**
+ * A user in the system
+ */
+export type User = {
+  /** Unique identifier */
+  id: IDString;
+  /** Display name */
+  name: string;
+  /** Age in years */
+  age: Int;
+  /** Email address (null if not verified) */
+  email: string | null;
+};
+
+export const me = defineQuery<NoArgs, User | null>((_root, _args, ctx) => {
+  return findUserById(ctx.currentUserId);
+});
+
+/** Get user's profile URL */
+export const profileUrl = defineField<User, NoArgs, string>((parent) => {
+  return `https://example.com/users/${parent.id}`;
+});
+```
+
+## Nullability
+
+Use union with `null` to make fields nullable:
+
+```typescript
+export type User = {
+  email: string | null;  // nullable
+  name: string;          // non-null
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  email: String
+  name: String!
+}
+```
+
+## Arrays
+
+Arrays are automatically converted to GraphQL lists:
+
+```typescript
+export type User = {
+  tags: string[];           // [String!]!
+  posts: Post[] | null;     // [Post!]
+};
+```
+
+## Inline Objects
+
+Object type fields can use inline object literals for nested structures. gqlkit automatically generates Object types with the naming convention `{ParentTypeName}{PascalCaseFieldName}`:
+
+```typescript
+export type User = {
+  id: string;
+  name: string;
+  /** User's profile information */
+  profile: {
+    /** User's biography */
+    bio: string;
+    age: number;
+  };
+};
+```
+
+Generates:
+
+```graphql
+type User {
+  id: String!
+  name: String!
+  """User's profile information"""
+  profile: UserProfile!
+}
+
+type UserProfile {
+  """User's biography"""
+  bio: String!
+  age: Float!
+}
+```
+
+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:
+
+```typescript
+import { type GqlObject, type IDString } from "@gqlkit-ts/runtime";
+import type { Node, Timestamped } from "./node.js";
+import type { DateTime } from "./scalars.js";
+
+/**
+ * A user in the system.
+ */
+export type User = GqlObject<
+  {
+    id: IDString;
+    name: string;
+    email: string | null;
+    createdAt: DateTime;
+  },
+  { implements: [Node, Timestamped] }
+>;
+```
+
+Generates:
+
+```graphql
+"""A user in the system."""
+type User implements Node & Timestamped {
+  id: ID!
+  name: String!
+  email: String
+  createdAt: DateTime!
+}
+```
+
+You can combine `implements` with `directives`:
+
+```typescript
+export type Post = GqlObject<
+  {
+    id: IDString;
+    title: string;
+    createdAt: DateTime;
+  },
+  {
+    implements: [Node, Timestamped],
+    directives: [CacheDirective<{ maxAge: 60 }>]
+  }
+>;
+```
+
+See [Interfaces](./interfaces.md) for more details on defining interface types.
+
+## Invalid Field Names
+
+Field names that are not valid GraphQL identifiers are automatically skipped with a warning. Valid GraphQL names must:
+
+- Match the pattern `/^[_A-Za-z][_0-9A-Za-z]*$/`
+- Not start with `__` (reserved for GraphQL introspection)
+
+```typescript
+export type User = {
+  id: string;              // ✅ Valid
+  userName: string;        // ✅ Valid
+  _internal: string;       // ✅ Valid (single underscore is OK)
+  "0invalid": string;      // ⚠️ Skipped: starts with a number
+  __reserved: string;      // ⚠️ Skipped: starts with __
+  "field-name": string;    // ⚠️ Skipped: contains hyphen
+};
+```
+
+Generates (invalid fields are skipped):
+
+```graphql
+type User {
+  id: String!
+  userName: String!
+  _internal: String!
+}
+```
+
+When fields are skipped, gqlkit outputs a warning with the field name and location.