@gqlkit-ts/cli 0.0.1 → 0.1.0

package/docs/schema/fields.md

@@ -0,0 +1,184 @@
+# Field Resolvers
+
+Add computed fields to object types using `defineField`. Define them alongside the type.
+
+## Basic Usage
+
+```typescript
+// src/gqlkit/schema/user.ts
+import { defineField } from "../gqlkit";
+import type { IDString, NoArgs } from "@gqlkit-ts/runtime";
+import type { Post } from "./post.js";
+
+export type User = {
+  id: IDString;
+  name: string;
+};
+
+/** Get posts authored by this user */
+export const posts = defineField<User, NoArgs, Post[]>(
+  (parent) => findPostsByAuthor(parent.id)
+);
+
+/** Get user's post count */
+export const postCount = defineField<User, NoArgs, number>(
+  (parent) => countPostsByAuthor(parent.id)
+);
+```
+
+Generates:
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  """Get posts authored by this user"""
+  posts: [Post!]!
+  """Get user's post count"""
+  postCount: Float!
+}
+```
+
+## Resolver Function Signature
+
+Field resolvers receive four arguments:
+
+```typescript
+(parent, args, ctx, info) => ReturnType
+```
+
+| Argument | Description |
+|----------|-------------|
+| `parent` | The parent object (typed via the first type parameter) |
+| `args` | The arguments passed to the field |
+| `ctx` | The context object (typed via `gqlkit.ts`) |
+| `info` | GraphQL resolve info |
+
+## Type Parameters
+
+`defineField<TParent, TArgs, TResult>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `TParent` | The parent object type this field is defined on |
+| `TArgs` | The arguments type (use `NoArgs` if no arguments) |
+| `TResult` | The return type of the field |
+
+## Fields with Arguments
+
+```typescript
+export const posts = defineField<
+  User,
+  { limit: number; offset: number },
+  Post[]
+>((parent, args) => {
+  return findPostsByAuthor(parent.id, args.limit, args.offset);
+});
+```
+
+Generates:
+
+```graphql
+type User {
+  posts(limit: Float!, offset: Float!): [Post!]!
+}
+```
+
+## Inline Object Arguments
+
+Field resolver arguments can use inline object literals. gqlkit automatically generates Input Object types with the naming convention `{ParentTypeName}{PascalCaseFieldName}{PascalCaseArgName}Input`:
+
+```typescript
+import { defineField } from "../gqlkit";
+
+export const posts = defineField<
+  User,
+  {
+    /** Filter options */
+    filter: {
+      titlePattern: string | null;
+      status: PostStatus | null;
+    } | null;
+  },
+  Post[]
+>((parent, args) => []);
+```
+
+Generates:
+
+```graphql
+type User {
+  posts(
+    """Filter options"""
+    filter: UserPostsFilterInput
+  ): [Post!]!
+}
+
+input UserPostsFilterInput {
+  titlePattern: String
+  status: PostStatus
+}
+```
+
+## Default Values in Arguments
+
+Default values in Input Objects are applied to resolver arguments:
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { GqlField, Int } from "@gqlkit-ts/runtime";
+
+export type PaginationInput = {
+  limit: GqlField<Int, { defaultValue: 10 }>;
+  offset: GqlField<Int, { defaultValue: 0 }>;
+};
+
+export type User = {
+  id: string;
+  name: string;
+};
+
+export const users = defineQuery<PaginationInput, User[]>(() => []);
+```
+
+Generates:
+
+```graphql
+type Query {
+  users(limit: Int! = 10, offset: Int! = 0): [User!]!
+}
+```
+
+## 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
+);
+```
+
+## Attaching Directives
+
+Add a fourth type parameter to attach 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);
+```
+
+See [Directives](./directives.md) for more details on defining and using custom directives.

package/docs/schema/index.md

@@ -0,0 +1,38 @@
+# 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.
+
+## Type Mapping
+
+gqlkit maps TypeScript types to GraphQL types as follows:
+
+| TypeScript | GraphQL |
+|------------|---------|
+| `string` | `String!` |
+| `number` | `Float!` |
+| `boolean` | `Boolean!` |
+| `IDString`, `IDNumber` | `ID!` |
+| `Int` (branded) | `Int!` |
+| `Float` (branded) | `Float!` |
+| `T \| null` | `T` (nullable) |
+| `T[]` | `[T!]!` |
+| String literal union | Enum type |
+| TypeScript `enum` | Enum type |
+| Union of object types | Union type |
+| `*Input` suffix types | Input Object type |
+| Union with `*Input` suffix | `@oneOf` input object |
+| `GqlInterface<T>` | Interface type |
+| `GqlScalar<Name, Base>` | Custom scalar |
+
+## Project Layout
+
+Default project layout:
+
+```
+src/
+  gqlkit/
+    schema/        # Types and resolvers co-located
+    __generated__/ # Generated files (auto-created)
+```
+
+All TypeScript files (`.ts`, `.cts`, `.mts`) under `src/gqlkit/schema/` are scanned for types and resolvers.

package/docs/schema/inputs.md

@@ -0,0 +1,277 @@
+# 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`).
+
+## @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.