@gqlkit-ts/cli 0.5.0 → 0.6.0

package/dist/type-extractor/types/diagnostics.d.ts

@@ -3,7 +3,7 @@ export interface SourceLocation {
     readonly line: number;
     readonly column: number;
 }
-export type DiagnosticCode = "DIRECTORY_NOT_FOUND" | "PARSE_ERROR" | "UNSUPPORTED_SYNTAX" | "RESERVED_TYPE_NAME" | "UNRESOLVED_REFERENCE" | "NAMING_CONVENTION_MISMATCH" | "INVALID_RESOLVER_SIGNATURE" | "UNSUPPORTED_RETURN_TYPE" | "UNSUPPORTED_ARG_TYPE" | "UNKNOWN_TARGET_TYPE" | "PARENT_TYPE_MISMATCH" | "MISSING_PARENT_TYPE" | "UNSUPPORTED_ENUM_TYPE" | "INVALID_ENUM_MEMBER" | "INVALID_INPUT_TYPE" | "UNKNOWN_ARGUMENT_TYPE" | "OUTPUT_TYPE_IN_INPUT" | "CIRCULAR_INPUT_REFERENCE" | "UNKNOWN_BRANDED_SCALAR" | "INVALID_SCALAR_IMPORT" | "CONFLICTING_SCALAR_TYPE" | "INVALID_DEFINE_CALL" | "CONFIG_SYNTAX_ERROR" | "CONFIG_FILE_NOT_FOUND" | "CONFIG_MISSING_PROPERTY" | "CONFIG_INVALID_TYPE" | "CONFIG_INVALID_PATH" | "CONFIG_BUILTIN_OVERRIDE" | "CONFIG_DUPLICATE_MAPPING" | "CONFIG_DUPLICATE_TYPE" | "CONFIG_INVALID_OUTPUT_TYPE" | "CONFIG_INVALID_OUTPUT_PATH" | "CONFIG_INVALID_SOURCE_DIR" | "CONFIG_INVALID_IGNORE_GLOBS" | "CONFIG_INVALID_HOOK_TYPE" | "CONFIG_INVALID_HOOK_COMMAND" | "CONFIG_INVALID_ONLY_VALUE" | "CONFIG_INVALID_IMPORT_EXTENSION" | "CUSTOM_SCALAR_TYPE_NOT_FOUND" | "TSCONFIG_NOT_FOUND" | "TSCONFIG_PARSE_ERROR" | "TSCONFIG_INVALID" | "ONEOF_FIELD_NAME_CONFLICT" | "ONEOF_MULTIPLE_PROPERTIES" | "ONEOF_EMPTY_OBJECT" | "ONEOF_INVALID_FIELD_TYPE" | "ONEOF_DUPLICATE_PROPERTY" | "ONEOF_MIXED_MEMBERS" | "ONEOF_NAMED_TYPE_UNION" | "MULTIPLE_INPUT_TYPES" | "MISSING_INPUT_TYPE" | "MISSING_OUTPUT_TYPE" | "EMPTY_DIRECTIVE_NAME" | "UNRESOLVABLE_ARGUMENT" | "UNRESOLVABLE_ARG_TYPE" | "INVALID_LOCATION" | "INVALID_DIRECTIVE_LOCATION" | "UNSUPPORTED_DIRECTIVE_LOCATION" | "UNDEFINED_DIRECTIVE" | "INTERFACE_NOT_FOUND" | "INTERFACE_NOT_INTERFACE" | "INTERFACE_MISSING_FIELD" | "INTERFACE_FIELD_TYPE_MISMATCH" | "INTERFACE_CIRCULAR_REFERENCE" | "UNRESOLVABLE_DEFAULT_VALUE" | "AUTO_TYPE_NAME_COLLISION_USER" | "AUTO_TYPE_NAME_COLLISION_AUTO" | "MODULE_RESOLUTION_ERROR" | "SKIPPED_FIELD" | "SKIPPED_ENUM_VALUE" | "INDEX_SIGNATURE_ONLY" | "UNKNOWN_ABSTRACT_TYPE" | "INVALID_ABSTRACT_TYPE_KIND" | "INVALID_OBJECT_TYPE_KIND" | "DUPLICATE_RESOLVE_TYPE" | "DUPLICATE_IS_TYPE_OF" | "MISSING_ABSTRACT_TYPE_RESOLVER" | "DUPLICATE_ENUM_VALUE" | "DUPLICATE_ENUM_VALUE_AFTER_CONVERSION" | "INVALID_ENUM_MEMBER_NAME" | "AMBIGUOUS_SCALAR_BASE_TYPE" | "INLINE_UNION_PRIMITIVE_MEMBER" | "INLINE_UNION_ENUM_MEMBER" | "INLINE_UNION_UNRESOLVABLE_MEMBER" | "MISSING_TYPENAME_PROPERTY" | "INVALID_TYPENAME_TYPE" | "OPTIONAL_TYPENAME_PROPERTY" | "NULLABLE_TYPENAME_PROPERTY" | "TYPENAME_FIELD_STRUCTURE_MISMATCH" | "DUPLICATE_TYPENAME_VALUE" | "IGNORE_FIELD_NOT_FOUND" | "IGNORE_ALL_FIELDS";
+export type DiagnosticCode = "DIRECTORY_NOT_FOUND" | "PARSE_ERROR" | "UNSUPPORTED_SYNTAX" | "RESERVED_TYPE_NAME" | "UNRESOLVED_REFERENCE" | "NAMING_CONVENTION_MISMATCH" | "INVALID_RESOLVER_SIGNATURE" | "UNSUPPORTED_RETURN_TYPE" | "UNSUPPORTED_ARG_TYPE" | "UNKNOWN_TARGET_TYPE" | "PARENT_TYPE_MISMATCH" | "MISSING_PARENT_TYPE" | "UNSUPPORTED_ENUM_TYPE" | "INVALID_ENUM_MEMBER" | "INVALID_INPUT_TYPE" | "UNKNOWN_ARGUMENT_TYPE" | "OUTPUT_TYPE_IN_INPUT" | "CIRCULAR_INPUT_REFERENCE" | "UNKNOWN_BRANDED_SCALAR" | "INVALID_SCALAR_IMPORT" | "CONFLICTING_SCALAR_TYPE" | "INVALID_DEFINE_CALL" | "CONFIG_SYNTAX_ERROR" | "CONFIG_FILE_NOT_FOUND" | "CONFIG_MISSING_PROPERTY" | "CONFIG_INVALID_TYPE" | "CONFIG_INVALID_PATH" | "CONFIG_BUILTIN_OVERRIDE" | "CONFIG_DUPLICATE_MAPPING" | "CONFIG_DUPLICATE_TYPE" | "CONFIG_INVALID_OUTPUT_TYPE" | "CONFIG_INVALID_OUTPUT_PATH" | "CONFIG_INVALID_SOURCE_DIR" | "CONFIG_INVALID_IGNORE_GLOBS" | "CONFIG_INVALID_HOOK_TYPE" | "CONFIG_INVALID_HOOK_COMMAND" | "CONFIG_INVALID_ONLY_VALUE" | "CONFIG_INVALID_IMPORT_EXTENSION" | "CUSTOM_SCALAR_TYPE_NOT_FOUND" | "TSCONFIG_NOT_FOUND" | "TSCONFIG_PARSE_ERROR" | "TSCONFIG_INVALID" | "ONEOF_FIELD_NAME_CONFLICT" | "ONEOF_MULTIPLE_PROPERTIES" | "ONEOF_EMPTY_OBJECT" | "ONEOF_INVALID_FIELD_TYPE" | "ONEOF_DUPLICATE_PROPERTY" | "ONEOF_MIXED_MEMBERS" | "ONEOF_NAMED_TYPE_UNION" | "MULTIPLE_INPUT_TYPES" | "MISSING_INPUT_TYPE" | "MISSING_OUTPUT_TYPE" | "EMPTY_DIRECTIVE_NAME" | "UNRESOLVABLE_ARGUMENT" | "UNRESOLVABLE_ARG_TYPE" | "INVALID_LOCATION" | "INVALID_DIRECTIVE_LOCATION" | "UNSUPPORTED_DIRECTIVE_LOCATION" | "UNDEFINED_DIRECTIVE" | "INTERFACE_NOT_FOUND" | "INTERFACE_NOT_INTERFACE" | "INTERFACE_MISSING_FIELD" | "INTERFACE_FIELD_TYPE_MISMATCH" | "INTERFACE_CIRCULAR_REFERENCE" | "UNRESOLVABLE_DEFAULT_VALUE" | "AUTO_TYPE_NAME_COLLISION_USER" | "AUTO_TYPE_NAME_COLLISION_AUTO" | "MODULE_RESOLUTION_ERROR" | "SKIPPED_FIELD" | "SKIPPED_ENUM_VALUE" | "INDEX_SIGNATURE_ONLY" | "UNKNOWN_ABSTRACT_TYPE" | "INVALID_ABSTRACT_TYPE_KIND" | "INVALID_OBJECT_TYPE_KIND" | "DUPLICATE_RESOLVE_TYPE" | "DUPLICATE_IS_TYPE_OF" | "MISSING_ABSTRACT_TYPE_RESOLVER" | "DUPLICATE_ENUM_VALUE" | "DUPLICATE_ENUM_VALUE_AFTER_CONVERSION" | "INVALID_ENUM_MEMBER_NAME" | "AMBIGUOUS_SCALAR_BASE_TYPE" | "INLINE_UNION_PRIMITIVE_MEMBER" | "INLINE_UNION_ENUM_MEMBER" | "INLINE_UNION_UNRESOLVABLE_MEMBER" | "MISSING_TYPENAME_PROPERTY" | "INVALID_TYPENAME_TYPE" | "OPTIONAL_TYPENAME_PROPERTY" | "NULLABLE_TYPENAME_PROPERTY" | "TYPENAME_FIELD_STRUCTURE_MISMATCH" | "DUPLICATE_TYPENAME_VALUE" | "IGNORE_FIELD_NOT_FOUND" | "IGNORE_ALL_FIELDS" | "DUPLICATE_TYPE_EXPORT";
 export interface Diagnostic {
     readonly code: DiagnosticCode;
     readonly message: string;

package/dist/type-extractor/types/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/type-extractor/types/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GACtB,qBAAqB,GACrB,aAAa,GACb,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,4BAA4B,GAC5B,4BAA4B,GAC5B,yBAAyB,GACzB,sBAAsB,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,qBAAqB,GACrB,uBAAuB,GACvB,qBAAqB,GACrB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,yBAAyB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,GACvB,yBAAyB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,GACzB,0BAA0B,GAC1B,uBAAuB,GACvB,4BAA4B,GAC5B,4BAA4B,GAC5B,2BAA2B,GAC3B,6BAA6B,GAC7B,0BAA0B,GAC1B,6BAA6B,GAC7B,2BAA2B,GAC3B,iCAAiC,GACjC,8BAA8B,GAC9B,oBAAoB,GACpB,sBAAsB,GACtB,kBAAkB,GAClB,2BAA2B,GAC3B,2BAA2B,GAC3B,oBAAoB,GACpB,0BAA0B,GAC1B,0BAA0B,GAC1B,qBAAqB,GACrB,wBAAwB,GACxB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,kBAAkB,GAClB,4BAA4B,GAC5B,gCAAgC,GAChC,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,GACzB,yBAAyB,GACzB,+BAA+B,GAC/B,8BAA8B,GAC9B,4BAA4B,GAC5B,+BAA+B,GAC/B,+BAA+B,GAC/B,yBAAyB,GACzB,eAAe,GACf,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,GACvB,4BAA4B,GAC5B,0BAA0B,GAC1B,wBAAwB,GACxB,sBAAsB,GACtB,gCAAgC,GAChC,sBAAsB,GACtB,uCAAuC,GACvC,0BAA0B,GAC1B,4BAA4B,GAC5B,+BAA+B,GAC/B,0BAA0B,GAC1B,kCAAkC,GAClC,2BAA2B,GAC3B,uBAAuB,GACvB,4BAA4B,GAC5B,4BAA4B,GAC5B,mCAAmC,GACnC,0BAA0B,GAC1B,wBAAwB,GACxB,mBAAmB,CAAC;AAExB,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/type-extractor/types/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GACtB,qBAAqB,GACrB,aAAa,GACb,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,4BAA4B,GAC5B,4BAA4B,GAC5B,yBAAyB,GACzB,sBAAsB,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,qBAAqB,GACrB,uBAAuB,GACvB,qBAAqB,GACrB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,yBAAyB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,GACvB,yBAAyB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,GACzB,0BAA0B,GAC1B,uBAAuB,GACvB,4BAA4B,GAC5B,4BAA4B,GAC5B,2BAA2B,GAC3B,6BAA6B,GAC7B,0BAA0B,GAC1B,6BAA6B,GAC7B,2BAA2B,GAC3B,iCAAiC,GACjC,8BAA8B,GAC9B,oBAAoB,GACpB,sBAAsB,GACtB,kBAAkB,GAClB,2BAA2B,GAC3B,2BAA2B,GAC3B,oBAAoB,GACpB,0BAA0B,GAC1B,0BAA0B,GAC1B,qBAAqB,GACrB,wBAAwB,GACxB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,kBAAkB,GAClB,4BAA4B,GAC5B,gCAAgC,GAChC,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,GACzB,yBAAyB,GACzB,+BAA+B,GAC/B,8BAA8B,GAC9B,4BAA4B,GAC5B,+BAA+B,GAC/B,+BAA+B,GAC/B,yBAAyB,GACzB,eAAe,GACf,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,GACvB,4BAA4B,GAC5B,0BAA0B,GAC1B,wBAAwB,GACxB,sBAAsB,GACtB,gCAAgC,GAChC,sBAAsB,GACtB,uCAAuC,GACvC,0BAA0B,GAC1B,4BAA4B,GAC5B,+BAA+B,GAC/B,0BAA0B,GAC1B,kCAAkC,GAClC,2BAA2B,GAC3B,uBAAuB,GACvB,4BAA4B,GAC5B,4BAA4B,GAC5B,mCAAmC,GACnC,0BAA0B,GAC1B,wBAAwB,GACxB,mBAAmB,GACnB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CAC9C"}

package/docs/getting-started.md

@@ -57,7 +57,7 @@ Create `src/gqlkit/gqlkit.ts` to export resolver factories:
 import { createGqlkitApis } from "@gqlkit-ts/runtime";
 import type { Context } from "./context";
 
-export const { defineQuery, defineMutation, defineField } =
+export const { defineQuery, defineMutation, defineSubscription, defineField } =
   createGqlkitApis<Context>();
 ```
 
@@ -118,3 +118,4 @@ export const schema = makeExecutableSchema({ typeDefs, resolvers });
 - [HTTP Server Integration](./integration/yoga) - Connect your schema to graphql-yoga, Apollo Server, or other HTTP servers
 - [Object Types](./schema/objects) - Learn more about defining types
 - [Queries & Mutations](./schema/queries-mutations) - Advanced resolver patterns
+- [Subscriptions](./schema/subscriptions) - Real-time data with subscriptions

package/docs/index.md

@@ -25,6 +25,7 @@ gqlkit generates GraphQL schema and resolver maps from TypeScript types and func
 - [Defining Object Types](./schema/objects.md): Plain TypeScript type exports become GraphQL Object types.
 - [Defining Input Types](./schema/inputs.md): TypeScript types with Input suffix are treated as GraphQL input types.
 - [Defining Queries and Mutations](./schema/queries-mutations.md): Define Query and Mutation fields using the @gqlkit-ts/runtime API.
+- [Defining Subscriptions](./schema/subscriptions.md): Define Subscription fields using the @gqlkit-ts/runtime API.
 - [Defining Field Resolvers](./schema/fields.md): Add computed fields to object types using defineField.
 - [Defining Scalar Types](./schema/scalars.md): gqlkit provides built-in scalar types and supports custom scalar definitions.
 - [Defining Enum Types](./schema/enums.md): gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.

package/docs/schema/conventions.md

@@ -34,6 +34,13 @@ gqlkit maps TypeScript types to GraphQL types as follows:
 
 gqlkit generates type names using predictable conventions:
 
+For `defineQuery`, `defineMutation`, and `defineField`, GraphQL field names are also derived from exported variable names:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- Common usage is a single prefix (for example, `Query$users` -> `users`).
+- If the export name ends with `$`, gqlkit reports an error.
+
 | Context | Pattern | Example |
 |---------|---------|---------|
 | Object field (inline) | `{ParentType}{Field}` | `User.profile` → `UserProfile` |

package/docs/schema/fields.md

@@ -7,6 +7,12 @@ description: Add computed fields to object types using defineField.
 
 Add computed fields to object types using `defineField`. Define them alongside the type.
 
+GraphQL field names are derived from the exported variable name:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- If the export name ends with `$`, gqlkit reports an error.
+
 ## Basic Usage
 
 ```typescript
@@ -44,6 +50,15 @@ type User {
 }
 ```
 
+Example with `$` delimiter:
+
+```typescript
+// GraphQL field name: posts
+export const User$posts = defineField<User, NoArgs, Post[]>(
+  (parent) => findPostsByAuthor(parent.id)
+);
+```
+
 ## Resolver Function Signature
 
 Field resolvers receive four arguments:

package/docs/schema/queries-mutations.md

@@ -11,7 +11,11 @@ Define Query and Mutation fields using the `@gqlkit-ts/runtime` API.
 
 ## Query Resolvers
 
-Use `defineQuery` to define Query fields. The export name becomes the GraphQL field name:
+Use `defineQuery` to define Query fields. GraphQL field names are derived from the exported variable name:
+
+- Default: the full export name is used as-is.
+- If the export name contains `$`, gqlkit uses the substring after the last `$`.
+- If the export name ends with `$`, gqlkit reports an error.
 
 ```typescript
 import { defineQuery } from "../gqlkit";
@@ -50,9 +54,16 @@ type Query {
 }
 ```
 
+Example with `$` delimiter:
+
+```typescript
+// GraphQL field name: users
+export const Query$users = defineQuery<NoArgs, User[]>(() => []);
+```
+
 ## Mutation Resolvers
 
-Use `defineMutation` to define Mutation fields:
+Use `defineMutation` to define Mutation fields. The same export-name rule applies:
 
 ```typescript
 import { defineMutation } from "../gqlkit";
@@ -71,6 +82,14 @@ export const deleteUser = defineMutation<{ id: string }, boolean>(
     return ctx.db.deleteUser(args.id);
   }
 );
+
+// GraphQL field name: createUser
+export const Mutation$createUser = defineMutation<
+  { input: CreateUserInput },
+  User
+>((_root, args, ctx) => {
+  return ctx.db.createUser(args.input);
+});
 ```
 
 Generates:

package/docs/schema/subscriptions.md

@@ -0,0 +1,173 @@
+---
+title: Defining Subscriptions
+description: Define Subscription fields using the @gqlkit-ts/runtime API.
+---
+
+# Subscriptions
+
+Define Subscription fields using the `@gqlkit-ts/runtime` API.
+
+> **Prerequisites**: This guide assumes you have completed the [basic setup](../getting-started.md#set-up-context-and-resolver-factories).
+
+## Setup
+
+Export `defineSubscription` from your `gqlkit.ts`:
+
+```typescript
+import { createGqlkitApis } from "@gqlkit-ts/runtime";
+import type { Context } from "./context";
+
+export const { defineQuery, defineMutation, defineSubscription } =
+  createGqlkitApis<Context>();
+```
+
+## Subscription Resolvers
+
+Use `defineSubscription` to define Subscription fields. The resolver is typically an async generator function:
+
+```typescript
+import { defineSubscription } from "../gqlkit";
+import type { Message } from "./message";
+
+// Subscription.messageAdded(channelId: String!)
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  messageAdded(channelId: String!): Message!
+}
+```
+
+The same export name conventions apply as with [Queries & Mutations](./queries-mutations.md):
+
+```typescript
+// GraphQL field name: messageAdded
+export const Subscription$messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+## NoArgs Subscriptions
+
+For subscriptions without arguments, use `NoArgs` as the first type parameter — same as with `defineQuery` and `defineMutation`. See [Queries & Mutations](./queries-mutations.md#noargs-queries) for details.
+
+## Resolver Function Signature
+
+Subscription resolvers receive the same four arguments as Query/Mutation resolvers, but return an `AsyncIterable` instead of a direct value:
+
+```typescript
+(root, args, ctx, info) => AsyncIterable<T> | Promise<AsyncIterable<T>>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `root` | The root value (always undefined) |
+| `args` | The arguments passed to the field |
+| `ctx` | The context object (typed via `createGqlkitApis<Context>()`) |
+| `info` | GraphQL resolve info |
+
+## Inline Object Arguments
+
+Subscription arguments support the same inline object types as queries and mutations:
+
+```typescript
+export const orderUpdated = defineSubscription<
+  {
+    filter: {
+      orderId: string | null;
+      status: string | null;
+    };
+  },
+  Order
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Order>("ORDER_UPDATED", args.filter);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  orderUpdated(filter: OrderUpdatedFilterInput!): Order!
+}
+
+input OrderUpdatedFilterInput {
+  orderId: String
+  status: String
+}
+```
+
+## Attaching Directives
+
+Add a third type parameter to attach directives:
+
+```typescript
+import { defineSubscription } from "../gqlkit";
+import type { AuthDirective } from "./directives";
+import type { Message } from "./message";
+
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message,
+  [AuthDirective<{ role: ["USER"] }>]
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  messageAdded(channelId: String!): Message! @auth(role: [USER])
+}
+```
+
+See [Directives](./directives.md) for more details on defining and using custom directives.
+
+## Documentation
+
+TSDoc comments on subscription exports are extracted as GraphQL descriptions:
+
+```typescript
+/** Subscribe to new messages in a channel. */
+export const messageAdded = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+
+/**
+ * @deprecated Use messageAdded instead.
+ */
+export const onMessage = defineSubscription<
+  { channelId: string },
+  Message
+>(async function* (_root, args, ctx) {
+  yield* ctx.pubsub.subscribe<Message>("MESSAGE_ADDED", args.channelId);
+});
+```
+
+Generates:
+
+```graphql
+type Subscription {
+  """Subscribe to new messages in a channel."""
+  messageAdded(channelId: String!): Message!
+  onMessage(channelId: String!): Message! @deprecated(reason: "Use messageAdded instead.")
+}
+```
+
+See [Documentation](./documentation.md) for more details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gqlkit-ts/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Just types and functions — write TypeScript, generate GraphQL.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@graphql-tools/utils": "^11.0.0",
-    "gunshi": "^0.27.5",
+    "gunshi": "^0.29.0",
     "jiti": "^2.4.2",
     "shell-quote": "^1.8.3"
   },
@@ -61,7 +61,7 @@
     "@types/shell-quote": "1.7.5",
     "memfs": "4.56.10",
     "@gqlkit-ts/docs": "0.0.1",
-    "@gqlkit-ts/runtime": "0.2.0"
+    "@gqlkit-ts/runtime": "0.3.0"
   },
   "scripts": {
     "build": "tsc --build && bundle-docs --target ./docs",

package/src/auto-type-generator/auto-type-generator.ts

@@ -52,7 +52,10 @@ import {
   isInputTypeName,
 } from "./naming-convention.js";
 import type { ResolveTypeFieldPattern } from "./resolve-type-generator.js";
-import { forEachResolverField } from "./resolver-field-iterator.js";
+import {
+  forEachResolverField,
+  type ResolverType,
+} from "./resolver-field-iterator.js";
 import {
   createFieldNameSet,
   findTypenameProperty,
@@ -353,7 +356,7 @@ function collectInlineObjectsFromResolvers(
 
 function collectInlineObjectsFromResolverArgs(
   field: GraphQLFieldDefinition,
-  resolverType: "query" | "mutation" | "field",
+  resolverType: ResolverType,
   parentTypeName: string | null,
   results: InlineObjectWithContext[],
 ): void {
@@ -420,7 +423,7 @@ function collectInlinePayloadsFromResolvers(
 
 function collectInlinePayloadFromReturnType(
   field: GraphQLFieldDefinition,
-  resolverType: "query" | "mutation" | "field",
+  resolverType: ResolverType,
   parentTypeName: string | null,
   results: InlineObjectWithContext[],
 ): void {
@@ -716,6 +719,11 @@ function updateResolversResult(
         updateResolverField(field, params, "mutation", null),
       ),
     },
+    subscriptionFields: {
+      fields: resolversResult.subscriptionFields.fields.map((field) =>
+        updateResolverField(field, params, "subscription", null),
+      ),
+    },
     typeExtensions: resolversResult.typeExtensions.map((ext) => ({
       ...ext,
       fields: ext.fields.map((field) =>
@@ -728,7 +736,7 @@ function updateResolversResult(
 function updateResolverField(
   field: GraphQLFieldDefinition,
   params: UpdateTypeNamesParams,
-  resolverType: "query" | "mutation" | "field",
+  resolverType: "query" | "mutation" | "subscription" | "field",
   parentTypeName: string | null,
 ): GraphQLFieldDefinition {
   const { generatedTypeNames, enumTypeNames, unionTypeNames } = params;

package/src/auto-type-generator/naming-convention.ts

@@ -34,7 +34,7 @@ export interface InputFieldContext {
  */
 export interface ResolverArgContext {
   readonly kind: "resolverArg";
-  readonly resolverType: "query" | "mutation" | "field";
+  readonly resolverType: "query" | "mutation" | "subscription" | "field";
   readonly fieldName: string;
   readonly argName: string;
   readonly parentTypeName: string | null;
@@ -49,7 +49,7 @@ export interface ResolverArgContext {
  */
 export interface ResolverPayloadContext {
   readonly kind: "resolverPayload";
-  readonly resolverType: "query" | "mutation" | "field";
+  readonly resolverType: "query" | "mutation" | "subscription" | "field";
   readonly fieldName: string;
   readonly parentTypeName: string | null;
   readonly fieldPath: ReadonlyArray<string>;

package/src/auto-type-generator/resolver-field-iterator.ts

@@ -3,7 +3,7 @@ import type {
   GraphQLFieldDefinition,
 } from "../resolver-extractor/index.js";
 
-export type ResolverType = "query" | "mutation" | "field";
+export type ResolverType = "query" | "mutation" | "field" | "subscription";
 
 export interface ResolverFieldInfo {
   readonly field: GraphQLFieldDefinition;
@@ -27,6 +27,10 @@ export function forEachResolverField(
     visitor({ field, resolverType: "mutation", parentTypeName: null });
   }
 
+  for (const field of resolversResult.subscriptionFields.fields) {
+    visitor({ field, resolverType: "subscription", parentTypeName: null });
+  }
+
   for (const ext of resolversResult.typeExtensions) {
     for (const field of ext.fields) {
       visitor({

package/src/gen-orchestrator/orchestrator.ts

@@ -34,6 +34,7 @@ import {
   collectScalars,
   type ScalarMetadataInfo,
 } from "../type-extractor/collector/scalar-collector.js";
+import { isEligibleField } from "../type-extractor/converter/field-eligibility.js";
 import { convertToGraphQL } from "../type-extractor/converter/graphql-converter.js";
 import {
   extractTypesFromProgram,
@@ -86,6 +87,7 @@ interface TypesResult {
 interface ResolversResult {
   queryFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
   mutationFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
+  subscriptionFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
   typeExtensions: ReadonlyArray<TypeExtension>;
   abstractTypeResolvers: ReadonlyArray<AbstractResolverInfo>;
   diagnostics: Diagnostics;
@@ -279,20 +281,42 @@ function convertDefineApiToFields(
 ): {
   queryFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
   mutationFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
+  subscriptionFields: { fields: ReadonlyArray<GraphQLFieldDefinition> };
   typeExtensions: ReadonlyArray<TypeExtension>;
+  diagnostics: ReadonlyArray<Diagnostic>;
 } {
   const queryFields: GraphQLFieldDefinition[] = [];
   const mutationFields: GraphQLFieldDefinition[] = [];
+  const subscriptionFields: GraphQLFieldDefinition[] = [];
   const typeExtensionMap = new Map<string, GraphQLFieldDefinition[]>();
+  const diagnostics: Diagnostic[] = [];
 
   for (const resolver of resolvers) {
+    const eligibility = isEligibleField({
+      fieldName: resolver.fieldName,
+      kind: "object",
+    });
+    if (!eligibility.eligible) {
+      diagnostics.push({
+        code: "SKIPPED_FIELD",
+        message: eligibility.skipReason.message,
+        severity: "warning",
+        location: {
+          file: resolver.sourceLocation.file,
+          line: resolver.sourceLocation.line,
+          column: resolver.sourceLocation.column,
+        },
+      });
+      continue;
+    }
+
     const returnType = resolver.returnType;
     const fieldDef: GraphQLFieldDefinition = {
       name: resolver.fieldName,
       type: convertTsTypeToGraphQLType(returnType),
       args: resolver.args ? convertArgsToInputValues(resolver.args) : null,
       sourceLocation: resolver.sourceLocation,
-      resolverExportName: resolver.fieldName,
+      resolverExportName: resolver.resolverExportName,
       description: resolver.description,
       deprecated: resolver.deprecated,
       directives: resolver.directives,
@@ -316,6 +340,8 @@ function convertDefineApiToFields(
       queryFields.push(fieldDef);
     } else if (resolver.resolverType === "mutation") {
       mutationFields.push(fieldDef);
+    } else if (resolver.resolverType === "subscription") {
+      subscriptionFields.push(fieldDef);
     } else if (resolver.resolverType === "field" && resolver.parentTypeName) {
       const existing = typeExtensionMap.get(resolver.parentTypeName) ?? [];
       existing.push(fieldDef);
@@ -331,7 +357,9 @@ function convertDefineApiToFields(
   return {
     queryFields: { fields: queryFields },
     mutationFields: { fields: mutationFields },
+    subscriptionFields: { fields: subscriptionFields },
     typeExtensions,
+    diagnostics,
   };
 }
 
@@ -411,9 +439,11 @@ function extractResolversCore(
   allDiagnostics.push(...defineApiExtractionResult.diagnostics);
 
   const result = convertDefineApiToFields(defineApiExtractionResult.resolvers);
+  allDiagnostics.push(...result.diagnostics);
   return {
     queryFields: result.queryFields,
     mutationFields: result.mutationFields,
+    subscriptionFields: result.subscriptionFields,
     typeExtensions: result.typeExtensions,
     abstractTypeResolvers: defineApiExtractionResult.abstractTypeResolvers,
     diagnostics: collectDiagnostics(allDiagnostics),
@@ -514,11 +544,18 @@ function collectTypeNamesStep(ctx: PipelineContext): PipelineContext {
 
   const result = collectDeclaredTypeNames(ctx.program, ctx.sourceFiles);
 
+  const diagnostics = [...ctx.diagnostics, ...result.diagnostics];
+  const hasDiagnosticErrors = result.diagnostics.some(
+    (d) => d.severity === "error",
+  );
+
   return {
     ...ctx,
     knownTypeNames: result.typeNames,
     knownTypeSymbols: result.typeSymbols,
     underlyingSymbolToTypeName: result.underlyingSymbolToTypeName,
+    diagnostics,
+    aborted: hasDiagnosticErrors,
   };
 }
 

package/src/resolver-extractor/extract-resolvers.ts

@@ -68,6 +68,10 @@ export interface MutationFieldDefinitions {
   readonly fields: ReadonlyArray<GraphQLFieldDefinition>;
 }
 
+export interface SubscriptionFieldDefinitions {
+  readonly fields: ReadonlyArray<GraphQLFieldDefinition>;
+}
+
 export interface TypeExtension {
   readonly targetTypeName: string;
   readonly fields: ReadonlyArray<GraphQLFieldDefinition>;
@@ -76,6 +80,7 @@ export interface TypeExtension {
 export interface ExtractResolversResult {
   readonly queryFields: QueryFieldDefinitions;
   readonly mutationFields: MutationFieldDefinitions;
+  readonly subscriptionFields: SubscriptionFieldDefinitions;
   readonly typeExtensions: ReadonlyArray<TypeExtension>;
   readonly abstractTypeResolvers: ReadonlyArray<AbstractResolverInfo>;
   readonly diagnostics: Diagnostics;