@gqlkit-ts/cli 0.0.1 → 0.1.0

package/docs/schema/objects.md

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

package/docs/schema/queries-mutations.md

@@ -0,0 +1,205 @@
+# 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.
+
+## Query Resolvers
+
+Use `defineQuery` to define Query fields. The export name becomes the GraphQL field name:
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { User } from "./user";
+
+// Query.me
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => {
+    return ctx.db.findUser(ctx.userId);
+  }
+);
+
+// Query.user(id: String!)
+export const user = defineQuery<{ id: string }, User | null>(
+  (_root, args, ctx) => {
+    return ctx.db.findUser(args.id);
+  }
+);
+
+// Query.users
+export const users = defineQuery<NoArgs, User[]>(
+  (_root, _args, ctx) => {
+    return ctx.db.findAllUsers();
+  }
+);
+```
+
+Generates:
+
+```graphql
+type Query {
+  me: User
+  user(id: String!): User
+  users: [User!]!
+}
+```
+
+## Mutation Resolvers
+
+Use `defineMutation` to define Mutation fields:
+
+```typescript
+import { defineMutation } from "../gqlkit";
+import type { User, CreateUserInput } from "./user";
+
+// Mutation.createUser(input: CreateUserInput!)
+export const createUser = defineMutation<{ input: CreateUserInput }, User>(
+  (_root, args, ctx) => {
+    return ctx.db.createUser(args.input);
+  }
+);
+
+// Mutation.deleteUser(id: String!)
+export const deleteUser = defineMutation<{ id: string }, boolean>(
+  (_root, args, ctx) => {
+    return ctx.db.deleteUser(args.id);
+  }
+);
+```
+
+Generates:
+
+```graphql
+type Mutation {
+  createUser(input: CreateUserInput!): User!
+  deleteUser(id: String!): Boolean!
+}
+```
+
+## Resolver Function Signature
+
+Query and Mutation resolvers receive four arguments:
+
+```typescript
+(root, args, ctx, info) => ReturnType
+```
+
+| Argument | Description |
+|----------|-------------|
+| `root` | The root value (usually undefined) |
+| `args` | The arguments passed to the field |
+| `ctx` | The context object (typed via `createGqlkitApis<Context>()`) |
+| `info` | GraphQL resolve info |
+
+## NoArgs Type
+
+Use the `NoArgs` type when a field has no arguments:
+
+```typescript
+import { type NoArgs } from "@gqlkit-ts/runtime";
+
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => ctx.currentUser
+);
+```
+
+## Arguments with Input Types
+
+Use Input types for complex arguments:
+
+```typescript
+export type SearchUsersInput = {
+  query: string;
+  limit: number | null;
+};
+
+export const searchUsers = defineQuery<{ input: SearchUsersInput }, User[]>(
+  (_root, args) => {
+    return findUsers(args.input.query, args.input.limit ?? 10);
+  }
+);
+```
+
+## Inline Object Arguments
+
+Arguments can use inline object literals. gqlkit automatically generates Input Object types:
+
+```typescript
+export const searchUsers = defineQuery<
+  {
+    /** Search filter */
+    filter: {
+      namePattern: string | null;
+      status: UserStatus | null;
+    };
+  },
+  User[]
+>((_root, args) => []);
+```
+
+Generates:
+
+```graphql
+type Query {
+  searchUsers(
+    """Search filter"""
+    filter: SearchUsersFilterInput!
+  ): [User!]!
+}
+
+input SearchUsersFilterInput {
+  namePattern: String
+  status: UserStatus
+}
+```
+
+See [Field Resolvers](./fields.md) for more details on inline object arguments.
+
+## Attaching Directives
+
+Add a third type parameter to attach directives to Query/Mutation fields:
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import { type AuthDirective } from "./directives.js";
+import type { User } from "./user.js";
+
+export const me = defineQuery<
+  NoArgs,
+  User,
+  [AuthDirective<{ role: ["USER"] }>]
+>((_root, _args, ctx) => ctx.currentUser);
+```
+
+Generates:
+
+```graphql
+type Query {
+  me: User! @auth(role: [USER])
+}
+```
+
+See [Directives](./directives.md) for more details on defining and using custom directives.

package/docs/schema/scalars.md

@@ -0,0 +1,194 @@
+# Scalar Types
+
+gqlkit provides built-in scalar types and supports custom scalar definitions.
+
+## Built-in Scalar Types
+
+gqlkit provides branded types to explicitly specify GraphQL scalar mappings:
+
+| TypeScript type | GraphQL type |
+|-----------------|--------------|
+| `IDString`      | `ID!`        |
+| `IDNumber`      | `ID!`        |
+| `Int`           | `Int!`       |
+| `Float`         | `Float!`     |
+| `string`        | `String!`    |
+| `number`        | `Float!`     |
+| `boolean`       | `Boolean!`   |
+
+### Usage
+
+```typescript
+import { type IDString, type Int, type Float } from "@gqlkit-ts/runtime";
+
+export type User = {
+  id: IDString;       // ID!
+  age: Int;           // Int!
+  score: Float;       // Float!
+  name: string;       // String!
+  balance: number;    // Float!
+  active: boolean;    // Boolean!
+};
+```
+
+## Custom Scalars with GqlScalar
+
+Define custom scalar types using the `GqlScalar` utility type:
+
+```typescript
+// src/gqlkit/schema/scalars.ts
+import { type GqlScalar } from "@gqlkit-ts/runtime";
+
+/**
+ * ISO 8601 format date-time string
+ */
+export type DateTime = GqlScalar<"DateTime", Date>;
+```
+
+Generates:
+
+```graphql
+"""ISO 8601 format date-time string"""
+scalar DateTime
+```
+
+### GqlScalar Type Parameters
+
+`GqlScalar<Name, Base, Only?>`:
+
+| Parameter | Description |
+|-----------|-------------|
+| `Name` | The GraphQL scalar name |
+| `Base` | The TypeScript type that backs this scalar |
+| `Only` | Optional: `"input"` or `"output"` to restrict usage |
+
+### Input-only and Output-only Scalars
+
+Restrict scalar usage to input or output positions:
+
+```typescript
+import { type GqlScalar } from "@gqlkit-ts/runtime";
+
+// Input-only scalar (for input positions only)
+export type DateTimeInput = GqlScalar<"DateTime", Date, "input">;
+
+// Output-only scalar (for output positions only)
+export type DateTimeOutput = GqlScalar<"DateTime", Date | string, "output">;
+```
+
+This is useful when input and output representations differ.
+
+## Config-based Custom Scalars
+
+Alternatively, map TypeScript types to GraphQL custom scalars via config:
+
+```typescript
+// gqlkit.config.ts
+import { defineConfig } from "@gqlkit-ts/cli";
+
+export default defineConfig({
+  scalars: [
+    {
+      name: "DateTime",
+      tsType: { from: "./src/gqlkit/schema/scalars", name: "DateTime" },
+      description: "ISO 8601 datetime string",
+    },
+    {
+      name: "UUID",
+      tsType: { name: "string" },  // Global type
+      only: "input",  // Input-only scalar
+    },
+  ],
+});
+```
+
+### Config Options
+
+| Option | Description |
+|--------|-------------|
+| `name` | The GraphQL scalar name |
+| `tsType.name` | The TypeScript type name |
+| `tsType.from` | Optional: import path for the type |
+| `description` | Optional: GraphQL description |
+| `only` | Optional: `"input"` or `"output"` |
+
+## Using Custom Scalars
+
+Once defined, use custom scalars in your types:
+
+```typescript
+import type { DateTime } from "./scalars.js";
+
+export type User = {
+  id: IDString;
+  name: string;
+  createdAt: DateTime;
+  updatedAt: DateTime | null;
+};
+
+export type CreateUserInput = {
+  name: string;
+  birthDate: DateTime;
+};
+```
+
+## Registering Scalar Resolvers
+
+Custom scalars require resolver implementations to handle serialization and parsing at runtime. Pass scalar resolvers to `createResolvers`:
+
+```typescript
+import { createResolvers } from "./gqlkit/__generated__/resolvers.js";
+
+const resolvers = createResolvers({
+  scalars: {
+    DateTime: myDateTimeScalar,
+  },
+});
+```
+
+### Using graphql-scalars (Recommended)
+
+The easiest way to implement custom scalars is to use [graphql-scalars](https://the-guild.dev/graphql/scalars), which provides ready-to-use implementations for common scalar types:
+
+```typescript
+import { GraphQLDateTime } from "graphql-scalars";
+
+const resolvers = createResolvers({
+  scalars: {
+    DateTime: GraphQLDateTime,
+  },
+});
+```
+
+This approach requires no manual serialize/parse implementation.
+
+### Custom Implementation
+
+For custom behavior, create your own `GraphQLScalarType`:
+
+```typescript
+import { GraphQLScalarType, Kind } from "graphql";
+
+const DateTimeScalar = new GraphQLScalarType({
+  name: "DateTime",
+  description: "ISO 8601 date-time string",
+  serialize(value) {
+    return value instanceof Date ? value.toISOString() : value;
+  },
+  parseValue(value) {
+    return new Date(value as string);
+  },
+  parseLiteral(ast) {
+    if (ast.kind === Kind.STRING) {
+      return new Date(ast.value);
+    }
+    return null;
+  },
+});
+
+const resolvers = createResolvers({
+  scalars: {
+    DateTime: DateTimeScalar,
+  },
+});
+```

package/docs/schema/unions.md

@@ -0,0 +1,90 @@
+# Union Types
+
+TypeScript union types of object types are converted to GraphQL union types.
+
+## Basic Usage
+
+```typescript
+import type { Post } from "./Post";
+import type { Comment } from "./Comment";
+
+/**
+ * Content that can be searched
+ */
+export type SearchResult = Post | Comment;
+```
+
+Generates:
+
+```graphql
+"""Content that can be searched"""
+union SearchResult = Comment | Post
+```
+
+## Using Unions in Resolvers
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { SearchResult } from "./types";
+
+export const search = defineQuery<{ query: string }, SearchResult[]>(
+  (_root, args, ctx) => {
+    return ctx.db.search(args.query);
+  }
+);
+```
+
+Generates:
+
+```graphql
+type Query {
+  search(query: String!): [SearchResult!]!
+}
+```
+
+## Union vs Enum
+
+- Use **Union** when each member is a distinct object type with different fields
+- Use **Enum** when you need a set of string constants
+
+```typescript
+// Union: Different object types
+export type SearchResult = Post | Comment | User;
+
+// Enum: String constants
+export type Status = "ACTIVE" | "INACTIVE" | "PENDING";
+```
+
+## Union vs Interface
+
+- Use **Union** when types share no common fields
+- Use **Interface** when types share common fields that should be queryable
+
+```typescript
+// Union: No common structure required
+export type SearchResult = Post | Comment;
+
+// Interface: Common fields enforced
+export type Node = GqlInterface<{
+  id: IDString;
+}>;
+```
+
+See [Interfaces](./interfaces.md) for more details on interface types.
+
+## Runtime Type Resolution
+
+When GraphQL executes a query that returns a union type, it needs to determine the concrete type at runtime. Use `defineResolveType` to handle this:
+
+```typescript
+import { defineResolveType } from "../gqlkit";
+
+export const searchResultResolveType = defineResolveType<SearchResult>(
+  (value) => {
+    if ("name" in value) return "User";
+    return "Post";
+  }
+);
+```
+
+See [Abstract Type Resolution](./abstract-resolvers.md) for complete documentation.

package/docs/what-is-gqlkit.md

@@ -0,0 +1,22 @@
+# What is gqlkit?
+
+gqlkit is a convention-driven code generator for GraphQL servers in TypeScript.
+
+## Core Concept
+
+Define GraphQL types and resolver signatures in TypeScript → `gqlkit gen` generates GraphQL schema AST and a resolver map from your codebase.
+
+## Design Principles
+
+- **Type-First**: Define types using plain TypeScript, no decorators needed
+- **Fail fast with actionable errors**: Invalid resolver references, type mismatches, etc.
+- **No runtime schema mutation**: Pure static analysis of TypeScript code
+- **Deterministic**: Same code → same outputs, always
+- **GraphQL-tools compatible**: Generated outputs work seamlessly with `makeExecutableSchema`
+
+## How It Works
+
+1. You write TypeScript types and resolvers in `src/gqlkit/schema/`
+2. Run `gqlkit gen`
+3. gqlkit scans your code, builds internal type graph, and validates resolver signatures
+4. Outputs `typeDefs` (GraphQL AST) and `resolvers` map to `src/gqlkit/__generated__/`