@gqlkit-ts/cli 0.2.0 → 0.3.0

package/docs/schema/unions.md

@@ -1,3 +1,8 @@
+---
+title: Defining Union Types
+description: TypeScript union types of object types are converted to GraphQL union types.
+---
+
 # Union Types
 
 TypeScript union types of object types are converted to GraphQL union types.
@@ -42,6 +47,100 @@ type Query {
 }
 ```
 
+## Inline Unions
+
+When a field type is an inline union of object types, gqlkit automatically generates a GraphQL Union type. The generated type name follows the convention `{ParentTypeName}{PascalCaseFieldName}`:
+
+```typescript
+import type { User } from "./User";
+import type { Post } from "./Post";
+
+export type SearchResult = {
+  id: string;
+  /**
+   * The matched item - either a User or a Post
+   */
+  item: User | Post;
+};
+```
+
+Generates:
+
+```graphql
+type SearchResult {
+  id: String!
+  """The matched item - either a User or a Post"""
+  item: SearchResultItem!
+}
+
+union SearchResultItem = Post | User
+```
+
+### Nullable Inline Unions
+
+Inline unions can be nullable:
+
+```typescript
+export type Container = {
+  id: string;
+  result: User | Post | null;
+};
+```
+
+Generates:
+
+```graphql
+type Container {
+  id: String!
+  result: ContainerResult
+}
+
+union ContainerResult = Post | User
+```
+
+### Known Type References
+
+When union members are exported types in the schema directory (`knownTypeNames`), they are preserved as references. Unknown inline object types are automatically generated:
+
+```typescript
+import type { User } from "./User"; // known type
+
+export type Activity = {
+  actor: User | { id: string; type: string }; // User is referenced, anonymous object is generated
+};
+```
+
+Generates:
+
+```graphql
+type Activity {
+  actor: ActivityActor!
+}
+
+union ActivityActor = ActivityActorAnonymous | User
+
+type ActivityActorAnonymous {
+  id: String!
+  type: String!
+}
+```
+
+### Validation
+
+Inline unions in output context must contain only object types. The following are not allowed:
+
+- Primitive types (string, number, boolean)
+- Enum types
+- Scalar types
+
+```typescript
+// These will produce errors:
+export type Invalid = {
+  value: string | number;        // Error: primitives not allowed
+  status: User | "active";       // Error: cannot mix object and enum
+};
+```
+
 ## Union vs Enum
 
 - Use **Union** when each member is a distinct object type with different fields
@@ -72,9 +171,117 @@ export type Node = GqlInterface<{
 
 See [Interfaces](./interfaces.md) for more details on interface types.
 
+## Inline Union Payloads
+
+When a resolver return type is an inline union with object literals, gqlkit generates a GraphQL Union type. 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 }
+>(/* ... */);
+```
+
+Generates:
+
+```graphql
+type Mutation {
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+}
+
+union UpdateUserPayload = UpdateUserError | UpdateUserSuccess
+
+type UpdateUserSuccess {
+  user: User!
+}
+
+type UpdateUserError {
+  message: String!
+}
+```
+
+### `__typename` Requirement
+
+For inline union payloads, the `__typename` property is required and must be a string literal type:
+
+```typescript
+// ✅ OK: __typename with string literal type
+type Result =
+  | { __typename: "Success"; data: string }
+  | { __typename: "Error"; message: string };
+
+// ❌ Error: __typename missing
+type Invalid =
+  | { data: string }
+  | { message: string };
+
+// ❌ Error: __typename is not a string literal
+type AlsoInvalid =
+  | { __typename: string; data: string }
+  | { __typename: string; message: string };
+```
+
+### Automatic `__resolveType` Generation
+
+For inline union payloads, gqlkit automatically generates a `__resolveType` function that returns the `__typename` property value. You don't need to define it manually.
+
+If you need custom type resolution logic, use [defineResolveType](./abstract-resolvers.md#defineresolveType).
+
+### Mixed Union Payloads
+
+You can mix inline object literals with named types. Only inline objects require `__typename`:
+
+```typescript
+import type { User } from "./user";
+
+export const findEntity = defineQuery<
+  { id: string },
+  | User // named type - __typename determined by type
+  | { __typename: "Guest"; sessionId: string } // inline type - __typename required
+>(/* ... */);
+```
+
+Generates:
+
+```graphql
+union FindEntityPayload = Guest | User
+
+type Guest {
+  sessionId: String!
+}
+```
+
+See [Queries & Mutations](./queries-mutations.md#inline-payload-types) for more details on inline payload 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:
+When GraphQL executes a query that returns a union type, it needs to determine the concrete type at runtime.
+
+### Automatic Resolution
+
+If your union member types have `__typename` or `$typeName` fields with string literal values, gqlkit automatically generates the `resolveType` function:
+
+```typescript
+export interface User {
+  __typename: "User";
+  id: string;
+  name: string;
+}
+
+export interface Post {
+  __typename: "Post";
+  id: string;
+  title: string;
+}
+
+export type SearchResult = User | Post;
+// resolveType is automatically generated - no manual definition needed
+```
+
+### Manual Resolution
+
+For types without `__typename` or `$typeName`, use `defineResolveType`:
 
 ```typescript
 import { defineResolveType } from "../gqlkit";

package/docs/what-is-gqlkit.md

@@ -1,22 +1,27 @@
+---
+title: What is gqlkit?
+description: Just types and functions — write TypeScript, generate GraphQL.
+---
+
 # What is gqlkit?
 
-gqlkit is a convention-driven code generator for GraphQL servers in TypeScript.
+Just types and functions — write TypeScript, generate GraphQL.
 
 ## Core Concept
 
-Define GraphQL types and resolver signatures in TypeScript → `gqlkit gen` generates GraphQL schema AST and a resolver map from your codebase.
+Write types and resolvers in TypeScript → run `gqlkit gen` → get GraphQL schema AST and resolver map.
 
 ## 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`
+- **Implement first**: Write types and resolvers, generate schema when ready. No edit-regenerate-implement loops.
+- **Just types and functions**: Plain TypeScript with a thin API. No complex generics, no decorators.
+- **Type-safe**: TypeScript types become GraphQL types. Resolver signatures checked at compile time.
+- **Fail fast with actionable errors**: Invalid resolver references, type mismatches, and convention violations.
+- **GraphQL-tools compatible**: Generated outputs work seamlessly with `makeExecutableSchema`.
 
 ## How It Works
 
-1. You write TypeScript types and resolvers in `src/gqlkit/schema/`
+1. 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__/`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gqlkit-ts/cli",
-  "version": "0.2.0",
-  "description": "gqlkit is a toolkit for building GraphQL servers by following simple TypeScript conventions. Write types and resolvers, and you get a complete GraphQL API — schema included.",
+  "version": "0.3.0",
+  "description": "Just types and functions — write TypeScript, generate GraphQL.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -12,6 +12,7 @@
     "docs",
     "src",
     "!**/testdata/**",
+    "!**/testing/**",
     "!**/*.test.ts",
     "!**/*.test.js",
     "!**/*.test.d.ts",
@@ -58,8 +59,9 @@
   },
   "devDependencies": {
     "@types/shell-quote": "1.7.5",
-    "@gqlkit-ts/docs": "0.0.1",
-    "@gqlkit-ts/runtime": "0.1.1"
+    "memfs": "4.56.10",
+    "@gqlkit-ts/runtime": "0.2.0",
+    "@gqlkit-ts/docs": "0.0.1"
   },
   "scripts": {
     "build": "tsc --build && bundle-docs --target ./docs",