@gqlkit-ts/cli 0.5.1 → 0.6.0

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.1",
+  "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),

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;

package/src/resolver-extractor/extractor/define-api-extractor.ts

@@ -35,7 +35,11 @@ import type {
   TSTypeReference,
 } from "../../type-extractor/types/index.js";
 
-export type DefineApiResolverType = "query" | "mutation" | "field";
+export type DefineApiResolverType =
+  | "query"
+  | "mutation"
+  | "field"
+  | "subscription";
 
 export type AbstractResolverKind = "resolveType" | "isTypeOf";
 
@@ -56,6 +60,7 @@ export interface ArgumentDefinition {
 
 export interface DefineApiResolverInfo {
   readonly fieldName: string;
+  readonly resolverExportName: string;
   readonly resolverType: DefineApiResolverType;
   readonly parentTypeName: string | null;
   readonly argsType: TSTypeReference | null;
@@ -222,7 +227,12 @@ function detectResolverFromMetadataType(
   const kindType = checker.getTypeOfSymbol(kindProp);
   if (kindType.isStringLiteral()) {
     const kind = kindType.value;
-    if (kind === "query" || kind === "mutation" || kind === "field") {
+    if (
+      kind === "query" ||
+      kind === "mutation" ||
+      kind === "field" ||
+      kind === "subscription"
+    ) {
       return kind;
     }
   }
@@ -230,6 +240,20 @@ function detectResolverFromMetadataType(
   return null;
 }
 
+function resolveFieldNameFromExportName(exportName: string): string | null {
+  const delimiterIndex = exportName.lastIndexOf("$");
+  if (delimiterIndex === -1) {
+    return exportName;
+  }
+
+  const fieldName = exportName.slice(delimiterIndex + 1);
+  if (fieldName.length === 0) {
+    return null;
+  }
+
+  return fieldName;
+}
+
 function isInlineTypeLiteralDeclaration(declaration: ts.Declaration): boolean {
   if (!ts.isPropertySignature(declaration)) {
     return false;
@@ -633,7 +657,7 @@ export function extractDefineApiResolvers(
           continue;
         }
 
-        const fieldName = declaration.name.getText(sourceFile);
+        const exportName = declaration.name.getText(sourceFile);
         const initializer = declaration.initializer;
 
         if (!initializer) {
@@ -647,11 +671,11 @@ export function extractDefineApiResolvers(
           ) {
             const hasDefineCall = initializer
               .getText(sourceFile)
-              .match(/define(Query|Mutation|Field)/);
+              .match(/define(Query|Mutation|Field|Subscription)/);
             if (hasDefineCall) {
               diagnostics.push({
                 code: "INVALID_DEFINE_CALL",
-                message: `Complex expressions with define* functions are not supported. Use a simple 'export const ${fieldName} = defineXxx(...)' pattern.`,
+                message: `Complex expressions with define* functions are not supported. Use a simple 'export const ${exportName} = defineXxx(...)' pattern.`,
                 severity: "error",
                 location: getSourceLocationFromNode(declaration.name),
               });
@@ -671,7 +695,7 @@ export function extractDefineApiResolvers(
             abstractTypeResolvers.push({
               kind: abstractResolverInfo.kind,
               targetTypeName: abstractResolverInfo.targetTypeName,
-              exportName: fieldName,
+              exportName,
               sourceFile: filePath,
               sourceLocation,
             });
@@ -688,6 +712,17 @@ export function extractDefineApiResolvers(
           continue;
         }
 
+        const fieldName = resolveFieldNameFromExportName(exportName);
+        if (fieldName === null) {
+          diagnostics.push({
+            code: "INVALID_DEFINE_CALL",
+            message: `Resolver export '${exportName}' must have a non-empty field name after '$'.`,
+            severity: "error",
+            location: getSourceLocationFromNode(declaration.name),
+          });
+          continue;
+        }
+
         const funcName = ts.isIdentifier(initializer.expression)
           ? initializer.expression.text
           : undefined;
@@ -702,7 +737,7 @@ export function extractDefineApiResolvers(
         if (!typeInfo) {
           diagnostics.push({
             code: "INVALID_DEFINE_CALL",
-            message: `Failed to extract type arguments from ${funcName ?? "define*"} call for '${fieldName}'`,
+            message: `Failed to extract type arguments from ${funcName ?? "define*"} call for '${exportName}'`,
             severity: "error",
             location: getSourceLocationFromNode(declaration.name),
           });
@@ -720,6 +755,7 @@ export function extractDefineApiResolvers(
 
         resolvers.push({
           fieldName,
+          resolverExportName: exportName,
           resolverType,
           parentTypeName: typeInfo.parentTypeName,
           argsType: typeInfo.argsType,

package/src/resolver-extractor/index.ts

@@ -5,6 +5,7 @@ export type {
   GraphQLInputValue,
   MutationFieldDefinitions,
   QueryFieldDefinitions,
+  SubscriptionFieldDefinitions,
   TypeExtension,
 } from "./extract-resolvers.js";
 export type {

package/src/schema-generator/emitter/code-emitter.ts

@@ -15,6 +15,7 @@ import type {
 } from "../integrator/result-integrator.js";
 import type {
   AbstractTypeResolverInfo,
+  FieldResolver,
   ResolverInfo,
   TypeResolvers,
 } from "../resolver-collector/resolver-collector.js";
@@ -315,21 +316,33 @@ function buildStringEnumResolvers(
   return stringEnumMappings.map(buildStringEnumResolver);
 }
 
+function buildFieldResolverValue(
+  localName: string,
+  field: FieldResolver,
+): string {
+  if (field.isDirectExport) {
+    return localName;
+  }
+  return `${localName}.${field.fieldName}`;
+}
+
 function buildTypeResolverEntry(
   type: TypeResolvers,
   abstractResolverForType: AbstractTypeResolverInfo | null,
 ): string {
   const entries: string[] = [];
+  const isSubscription = type.typeName === "Subscription";
 
   for (const field of type.fields) {
     const localName = makeResolverLocalName(type.typeName, field.fieldName);
+    const resolverValue = buildFieldResolverValue(localName, field);
 
-    if (field.isDirectExport) {
-      entries.push(`      ${field.fieldName}: ${localName},`);
-    } else {
+    if (isSubscription) {
       entries.push(
-        `      ${field.fieldName}: ${localName}.${field.fieldName},`,
+        `      ${field.fieldName}: { subscribe: ${resolverValue}, resolve: (event: unknown) => event },`,
       );
+    } else {
+      entries.push(`      ${field.fieldName}: ${resolverValue},`);
     }
   }
 

package/src/schema-generator/integrator/result-integrator.ts

@@ -145,6 +145,7 @@ export interface IntegratedResult {
   readonly stringEnumMappings: ReadonlyArray<StringEnumMappingInfo>;
   readonly hasQuery: boolean;
   readonly hasMutation: boolean;
+  readonly hasSubscription: boolean;
   readonly hasErrors: boolean;
   readonly diagnostics: ReadonlyArray<Diagnostic>;
 }
@@ -469,8 +470,10 @@ export function integrate(params: IntegrateParams): IntegratedResult {
 
   const hasQuery = resolversResult.queryFields.fields.length > 0;
   const hasMutation = resolversResult.mutationFields.fields.length > 0;
+  const hasSubscription = resolversResult.subscriptionFields.fields.length > 0;
 
-  if (hasQuery) {
+  // GraphQL spec requires Query root type even when only Subscription/Mutation are defined
+  if (hasQuery || hasMutation || hasSubscription) {
     baseTypes.push({
       name: "Query",
       kind: "Object",
@@ -502,6 +505,22 @@ export function integrate(params: IntegrateParams): IntegratedResult {
       directives: null,
     });
   }
+  if (hasSubscription) {
+    baseTypes.push({
+      name: "Subscription",
+      kind: "Object",
+      fields: [],
+      unionMembers: null,
+      enumValues: null,
+      isNumericEnum: false,
+      needsStringEnumMapping: false,
+      implementedInterfaces: null,
+      description: null,
+      deprecated: null,
+      sourceFile: null,
+      directives: null,
+    });
+  }
 
   const typenameAutoResolveTypeNames = new Set([
     ...(typenameAutoResolveTypes?.map((t) => t.abstractTypeName) ?? []),
@@ -540,6 +559,15 @@ export function integrate(params: IntegrateParams): IntegratedResult {
     });
   }
 
+  if (hasSubscription) {
+    typeExtensions.push({
+      targetTypeName: "Subscription",
+      fields: resolversResult.subscriptionFields.fields.map(
+        convertToExtensionField,
+      ),
+    });
+  }
+
   for (const ext of resolversResult.typeExtensions) {
     if (!knownTypeNames.has(ext.targetTypeName)) {
       const firstField = ext.fields[0];
@@ -712,6 +740,7 @@ export function integrate(params: IntegrateParams): IntegratedResult {
     stringEnumMappings,
     hasQuery,
     hasMutation,
+    hasSubscription,
     hasErrors,
     diagnostics,
   };