@constructive-io/graphql-codegen 4.5.2 → 4.6.0

package/core/codegen/hooks-docs-generator.js

@@ -43,14 +43,14 @@ function generateHooksReadme(tables, customOperations) {
     lines.push('|------|------|-------------|');
     for (const table of tables) {
         const { singularName, pluralName } = (0, utils_1.getTableNames)(table);
-        lines.push(`| \`${(0, utils_1.getListQueryHookName)(table)}\` | Query | List all ${pluralName} |`);
+        lines.push(`| \`${(0, utils_1.getListQueryHookName)(table)}\` | Query | ${table.description || `List all ${pluralName}`} |`);
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
-            lines.push(`| \`${(0, utils_1.getSingleQueryHookName)(table)}\` | Query | Get one ${singularName} |`);
+            lines.push(`| \`${(0, utils_1.getSingleQueryHookName)(table)}\` | Query | ${table.description || `Get one ${singularName}`} |`);
         }
-        lines.push(`| \`${(0, utils_1.getCreateMutationHookName)(table)}\` | Mutation | Create a ${singularName} |`);
+        lines.push(`| \`${(0, utils_1.getCreateMutationHookName)(table)}\` | Mutation | ${table.description || `Create a ${singularName}`} |`);
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
-            lines.push(`| \`${(0, utils_1.getUpdateMutationHookName)(table)}\` | Mutation | Update a ${singularName} |`);
-            lines.push(`| \`${(0, utils_1.getDeleteMutationHookName)(table)}\` | Mutation | Delete a ${singularName} |`);
+            lines.push(`| \`${(0, utils_1.getUpdateMutationHookName)(table)}\` | Mutation | ${table.description || `Update a ${singularName}`} |`);
+            lines.push(`| \`${(0, utils_1.getDeleteMutationHookName)(table)}\` | Mutation | ${table.description || `Delete a ${singularName}`} |`);
         }
     }
     for (const op of customOperations) {
@@ -151,7 +151,7 @@ function generateHooksAgentsDocs(tables, customOperations) {
         const scalarFields = (0, utils_1.getScalarFields)(table);
         lines.push(`### HOOK: ${(0, utils_1.getListQueryHookName)(table)}`);
         lines.push('');
-        lines.push(`List all ${pluralName}.`);
+        lines.push(`${table.description || `List all ${pluralName}`}.`);
         lines.push('');
         lines.push('```');
         lines.push(`TYPE: query`);
@@ -170,7 +170,7 @@ function generateHooksAgentsDocs(tables, customOperations) {
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
             lines.push(`### HOOK: ${(0, utils_1.getSingleQueryHookName)(table)}`);
             lines.push('');
-            lines.push(`Get a single ${singularName} by ${pk.name}.`);
+            lines.push(`${table.description || `Get a single ${singularName} by ${pk.name}`}.`);
             lines.push('');
             lines.push('```');
             lines.push(`TYPE: query`);
@@ -190,7 +190,7 @@ function generateHooksAgentsDocs(tables, customOperations) {
         }
         lines.push(`### HOOK: ${(0, utils_1.getCreateMutationHookName)(table)}`);
         lines.push('');
-        lines.push(`Create a new ${singularName}.`);
+        lines.push(`${table.description || `Create a new ${singularName}`}.`);
         lines.push('');
         lines.push('```');
         lines.push('TYPE: mutation');
@@ -202,7 +202,7 @@ function generateHooksAgentsDocs(tables, customOperations) {
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
             lines.push(`### HOOK: ${(0, utils_1.getUpdateMutationHookName)(table)}`);
             lines.push('');
-            lines.push(`Update an existing ${singularName}.`);
+            lines.push(`${table.description || `Update an existing ${singularName}`}.`);
             lines.push('');
             lines.push('```');
             lines.push('TYPE: mutation');
@@ -213,7 +213,7 @@ function generateHooksAgentsDocs(tables, customOperations) {
             lines.push('');
             lines.push(`### HOOK: ${(0, utils_1.getDeleteMutationHookName)(table)}`);
             lines.push('');
-            lines.push(`Delete a ${singularName}.`);
+            lines.push(`${table.description || `Delete a ${singularName}`}.`);
             lines.push('');
             lines.push('```');
             lines.push('TYPE: mutation');
@@ -273,7 +273,7 @@ function getHooksMcpTools(tables, customOperations) {
         const scalarFields = (0, utils_1.getScalarFields)(table);
         tools.push({
             name: `hooks_${(0, utils_1.lcFirst)(pluralName)}_query`,
-            description: `React Query hook to list all ${pluralName}`,
+            description: table.description || `React Query hook to list all ${pluralName}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -287,7 +287,7 @@ function getHooksMcpTools(tables, customOperations) {
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
             tools.push({
                 name: `hooks_${(0, utils_1.lcFirst)(singularName)}_query`,
-                description: `React Query hook to get a single ${singularName} by ${pk.name}`,
+                description: table.description || `React Query hook to get a single ${singularName} by ${pk.name}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -302,7 +302,7 @@ function getHooksMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `hooks_create_${(0, utils_1.lcFirst)(singularName)}_mutation`,
-            description: `React Query mutation hook to create a ${singularName}`,
+            description: table.description || `React Query mutation hook to create a ${singularName}`,
             inputSchema: {
                 type: 'object',
                 properties: Object.fromEntries(scalarFields
@@ -322,7 +322,7 @@ function getHooksMcpTools(tables, customOperations) {
         if ((0, utils_1.hasValidPrimaryKey)(table)) {
             tools.push({
                 name: `hooks_update_${(0, utils_1.lcFirst)(singularName)}_mutation`,
-                description: `React Query mutation hook to update a ${singularName}`,
+                description: table.description || `React Query mutation hook to update a ${singularName}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -336,7 +336,7 @@ function getHooksMcpTools(tables, customOperations) {
             });
             tools.push({
                 name: `hooks_delete_${(0, utils_1.lcFirst)(singularName)}_mutation`,
-                description: `React Query mutation hook to delete a ${singularName}`,
+                description: table.description || `React Query mutation hook to delete a ${singularName}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -390,7 +390,7 @@ function generateHooksSkills(tables, customOperations) {
             fileName: `skills/${(0, utils_1.lcFirst)(singularName)}.md`,
             content: (0, docs_utils_1.buildSkillFile)({
                 name: `hooks-${(0, utils_1.lcFirst)(singularName)}`,
-                description: `React Query hooks for ${table.name} data operations`,
+                description: table.description || `React Query hooks for ${table.name} data operations`,
                 language: 'typescript',
                 usage: [
                     `${(0, utils_1.getListQueryHookName)(table)}({ selection: { fields: { ${selectFields} } } })`,

package/core/codegen/mutations.js

@@ -115,7 +115,7 @@ function generateCreateMutationHook(table, options = {}) {
     ]);
     const o1 = (0, hooks_ast_1.exportDeclareFunction)(hookName, (0, hooks_ast_1.createSTypeParam)(selectTypeName), [(0, hooks_ast_1.createFunctionParam)('params', o1ParamType)], (0, hooks_ast_1.useMutationResultType)(resultType((0, hooks_ast_1.sRef)()), createVarType));
     (0, hooks_ast_1.addJSDocComment)(o1, [
-        `Mutation hook for creating a ${typeName}`,
+        table.description || `Mutation hook for creating a ${typeName}`,
         '',
         '@example',
         '```tsx',
@@ -168,7 +168,7 @@ function generateCreateMutationHook(table, options = {}) {
     statements.push((0, hooks_ast_1.exportFunction)(hookName, null, [(0, hooks_ast_1.createFunctionParam)('params', implParamType)], body));
     return {
         fileName: (0, utils_1.getCreateMutationFileName)(table),
-        content: (0, hooks_ast_1.generateHookFileCode)(`Create mutation hook for ${typeName}`, statements),
+        content: (0, hooks_ast_1.generateHookFileCode)(table.description || `Create mutation hook for ${typeName}`, statements),
     };
 }
 function generateUpdateMutationHook(table, options = {}) {
@@ -224,7 +224,7 @@ function generateUpdateMutationHook(table, options = {}) {
     ]);
     const o1 = (0, hooks_ast_1.exportDeclareFunction)(hookName, (0, hooks_ast_1.createSTypeParam)(selectTypeName), [(0, hooks_ast_1.createFunctionParam)('params', o1ParamType)], (0, hooks_ast_1.useMutationResultType)(resultType((0, hooks_ast_1.sRef)()), updateVarType));
     (0, hooks_ast_1.addJSDocComment)(o1, [
-        `Mutation hook for updating a ${typeName}`,
+        table.description || `Mutation hook for updating a ${typeName}`,
         '',
         '@example',
         '```tsx',
@@ -295,7 +295,7 @@ function generateUpdateMutationHook(table, options = {}) {
     statements.push((0, hooks_ast_1.exportFunction)(hookName, null, [(0, hooks_ast_1.createFunctionParam)('params', implParamType)], body));
     return {
         fileName: (0, utils_1.getUpdateMutationFileName)(table),
-        content: (0, hooks_ast_1.generateHookFileCode)(`Update mutation hook for ${typeName}`, statements),
+        content: (0, hooks_ast_1.generateHookFileCode)(table.description || `Update mutation hook for ${typeName}`, statements),
     };
 }
 function generateDeleteMutationHook(table, options = {}) {
@@ -348,7 +348,7 @@ function generateDeleteMutationHook(table, options = {}) {
     ]);
     const o1 = (0, hooks_ast_1.exportDeclareFunction)(hookName, (0, hooks_ast_1.createSTypeParam)(selectTypeName), [(0, hooks_ast_1.createFunctionParam)('params', o1ParamType)], (0, hooks_ast_1.useMutationResultType)(resultType((0, hooks_ast_1.sRef)()), deleteVarType));
     (0, hooks_ast_1.addJSDocComment)(o1, [
-        `Mutation hook for deleting a ${typeName} with typed selection`,
+        table.description || `Mutation hook for deleting a ${typeName} with typed selection`,
         '',
         '@example',
         '```tsx',
@@ -413,7 +413,7 @@ function generateDeleteMutationHook(table, options = {}) {
     statements.push((0, hooks_ast_1.exportFunction)(hookName, null, [(0, hooks_ast_1.createFunctionParam)('params', implParamType)], body));
     return {
         fileName: (0, utils_1.getDeleteMutationFileName)(table),
-        content: (0, hooks_ast_1.generateHookFileCode)(`Delete mutation hook for ${typeName}`, statements),
+        content: (0, hooks_ast_1.generateHookFileCode)(table.description || `Delete mutation hook for ${typeName}`, statements),
     };
 }
 function generateAllMutationHooks(tables, options = {}) {

package/core/codegen/orm/custom-ops-generator.d.ts

@@ -6,8 +6,8 @@ export interface GeneratedCustomOpsFile {
 /**
  * Generate the query/index.ts file for custom query operations
  */
-export declare function generateCustomQueryOpsFile(operations: CleanOperation[]): GeneratedCustomOpsFile;
+export declare function generateCustomQueryOpsFile(operations: CleanOperation[], comments?: boolean): GeneratedCustomOpsFile;
 /**
  * Generate the mutation/index.ts file for custom mutation operations
  */
-export declare function generateCustomMutationOpsFile(operations: CleanOperation[]): GeneratedCustomOpsFile;
+export declare function generateCustomMutationOpsFile(operations: CleanOperation[], comments?: boolean): GeneratedCustomOpsFile;

package/core/codegen/orm/custom-ops-generator.js

@@ -104,7 +104,7 @@ function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false
     decl.importKind = typeOnly ? 'type' : 'value';
     return decl;
 }
-function createVariablesInterface(op) {
+function createVariablesInterface(op, comments = true) {
     if (op.args.length === 0)
         return null;
     const varTypeName = `${(0, utils_1.ucFirst)(op.name)}Variables`;
@@ -112,10 +112,19 @@ function createVariablesInterface(op) {
         const optional = !(0, type_resolver_1.isTypeRequired)(arg.type);
         const prop = t.tsPropertySignature(t.identifier(arg.name), t.tsTypeAnnotation(parseTypeAnnotation((0, type_resolver_1.typeRefToTsType)(arg.type))));
         prop.optional = optional;
+        const argDescription = (0, utils_1.stripSmartComments)(arg.description, comments);
+        if (argDescription) {
+            (0, babel_ast_1.addJSDocComment)(prop, argDescription.split('\n'));
+        }
         return prop;
     });
     const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(varTypeName), null, null, t.tsInterfaceBody(props));
-    return t.exportNamedDeclaration(interfaceDecl);
+    const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+    const opDescription = (0, utils_1.stripSmartComments)(op.description, comments);
+    if (opDescription) {
+        (0, babel_ast_1.addJSDocComment)(exportDecl, [`Variables for ${op.name}`, opDescription]);
+    }
+    return exportDecl;
 }
 function parseTypeAnnotation(typeStr) {
     if (typeStr === 'string')
@@ -287,7 +296,7 @@ function buildOperationMethod(op, operationType) {
 /**
  * Generate the query/index.ts file for custom query operations
  */
-function generateCustomQueryOpsFile(operations) {
+function generateCustomQueryOpsFile(operations, comments = true) {
     const statements = [];
     // Collect all input type names and payload type names
     const inputTypeNames = collectInputTypeNamesFromOps(operations);
@@ -315,7 +324,7 @@ function generateCustomQueryOpsFile(operations) {
     statements.push(createImportDeclaration('../input-types', ['connectionFieldsMap']));
     // Generate variable interfaces
     for (const op of operations) {
-        const varInterface = createVariablesInterface(op);
+        const varInterface = createVariablesInterface(op, comments);
         if (varInterface)
             statements.push(varInterface);
     }
@@ -337,7 +346,7 @@ function generateCustomQueryOpsFile(operations) {
 /**
  * Generate the mutation/index.ts file for custom mutation operations
  */
-function generateCustomMutationOpsFile(operations) {
+function generateCustomMutationOpsFile(operations, comments = true) {
     const statements = [];
     // Collect all input type names and payload type names
     const inputTypeNames = collectInputTypeNamesFromOps(operations);
@@ -365,7 +374,7 @@ function generateCustomMutationOpsFile(operations) {
     statements.push(createImportDeclaration('../input-types', ['connectionFieldsMap']));
     // Generate variable interfaces
     for (const op of operations) {
-        const varInterface = createVariablesInterface(op);
+        const varInterface = createVariablesInterface(op, comments);
         if (varInterface)
             statements.push(varInterface);
     }

package/core/codegen/orm/docs-generator.js

@@ -230,7 +230,7 @@ function getOrmMcpTools(tables, customOperations) {
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
         tools.push({
             name: `orm_${(0, utils_1.lcFirst)(singularName)}_findMany`,
-            description: `List all ${table.name} records via ORM`,
+            description: table.description || `List all ${table.name} records via ORM`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -247,7 +247,7 @@ function getOrmMcpTools(tables, customOperations) {
         });
         tools.push({
             name: `orm_${(0, utils_1.lcFirst)(singularName)}_findOne`,
-            description: `Get a single ${table.name} record by ${pk.name}`,
+            description: table.description || `Get a single ${table.name} record by ${pk.name}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -268,7 +268,7 @@ function getOrmMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `orm_${(0, utils_1.lcFirst)(singularName)}_create`,
-            description: `Create a new ${table.name} record`,
+            description: table.description || `Create a new ${table.name} record`,
             inputSchema: {
                 type: 'object',
                 properties: createProps,
@@ -289,7 +289,7 @@ function getOrmMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `orm_${(0, utils_1.lcFirst)(singularName)}_update`,
-            description: `Update an existing ${table.name} record`,
+            description: table.description || `Update an existing ${table.name} record`,
             inputSchema: {
                 type: 'object',
                 properties: updateProps,
@@ -298,7 +298,7 @@ function getOrmMcpTools(tables, customOperations) {
         });
         tools.push({
             name: `orm_${(0, utils_1.lcFirst)(singularName)}_delete`,
-            description: `Delete a ${table.name} record by ${pk.name}`,
+            description: table.description || `Delete a ${table.name} record by ${pk.name}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -356,7 +356,7 @@ function generateOrmSkills(tables, customOperations) {
             fileName: `skills/${(0, utils_1.lcFirst)(singularName)}.md`,
             content: (0, docs_utils_1.buildSkillFile)({
                 name: `orm-${(0, utils_1.lcFirst)(singularName)}`,
-                description: `ORM operations for ${table.name} records`,
+                description: table.description || `ORM operations for ${table.name} records`,
                 language: 'typescript',
                 usage: [
                     `db.${(0, utils_1.lcFirst)(singularName)}.findMany({ select: { id: true } }).execute()`,

package/core/codegen/orm/index.js

@@ -12,6 +12,7 @@ const model_generator_1 = require("./model-generator");
  */
 function generateOrm(options) {
     const { tables, customOperations, sharedTypesPath } = options;
+    const commentsEnabled = options.config.codegen?.comments !== false;
     const files = [];
     // Use shared types when a sharedTypesPath is provided (unified output mode)
     const useSharedTypes = !!sharedTypesPath;
@@ -69,7 +70,7 @@ function generateOrm(options) {
                 }
             }
         }
-        const inputTypesFile = (0, input_types_generator_1.generateInputTypesFile)(typeRegistry ?? new Map(), usedInputTypes, tables, usedPayloadTypes);
+        const inputTypesFile = (0, input_types_generator_1.generateInputTypesFile)(typeRegistry ?? new Map(), usedInputTypes, tables, usedPayloadTypes, commentsEnabled);
         files.push({
             path: inputTypesFile.fileName,
             content: inputTypesFile.content,
@@ -77,11 +78,11 @@ function generateOrm(options) {
     }
     // 5. Generate custom operations (if any)
     if (hasCustomQueries && customOperations?.queries) {
-        const queryOpsFile = (0, custom_ops_generator_1.generateCustomQueryOpsFile)(customOperations.queries);
+        const queryOpsFile = (0, custom_ops_generator_1.generateCustomQueryOpsFile)(customOperations.queries, commentsEnabled);
         files.push({ path: queryOpsFile.fileName, content: queryOpsFile.content });
     }
     if (hasCustomMutations && customOperations?.mutations) {
-        const mutationOpsFile = (0, custom_ops_generator_1.generateCustomMutationOpsFile)(customOperations.mutations);
+        const mutationOpsFile = (0, custom_ops_generator_1.generateCustomMutationOpsFile)(customOperations.mutations, commentsEnabled);
         files.push({
             path: mutationOpsFile.fileName,
             content: mutationOpsFile.content,

package/core/codegen/orm/input-types-generator.d.ts

@@ -18,4 +18,4 @@ export declare function collectPayloadTypeNames(operations: Array<{
 /**
  * Generate comprehensive input-types.ts file using Babel AST
  */
-export declare function generateInputTypesFile(typeRegistry: TypeRegistry, usedInputTypes: Set<string>, tables?: CleanTable[], usedPayloadTypes?: Set<string>): GeneratedInputTypesFile;
+export declare function generateInputTypesFile(typeRegistry: TypeRegistry, usedInputTypes: Set<string>, tables?: CleanTable[], usedPayloadTypes?: Set<string>, comments?: boolean): GeneratedInputTypesFile;

package/core/codegen/orm/input-types-generator.js

@@ -155,19 +155,26 @@ function parseTypeString(typeStr) {
 /**
  * Create an interface property signature
  */
-function createPropertySignature(name, typeStr, optional) {
+function createPropertySignature(name, typeStr, optional, description) {
     const prop = t.tsPropertySignature(t.identifier(name), t.tsTypeAnnotation(parseTypeString(typeStr)));
     prop.optional = optional;
+    if (description) {
+        (0, babel_ast_1.addJSDocComment)(prop, description.split('\n'));
+    }
     return prop;
 }
 /**
  * Create an exported interface declaration
  */
-function createExportedInterface(name, properties) {
-    const props = properties.map((p) => createPropertySignature(p.name, p.type, p.optional));
+function createExportedInterface(name, properties, description) {
+    const props = properties.map((p) => createPropertySignature(p.name, p.type, p.optional, p.description));
     const body = t.tsInterfaceBody(props);
     const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(name), null, null, body);
-    return t.exportNamedDeclaration(interfaceDecl);
+    const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+    if (description) {
+        (0, babel_ast_1.addJSDocComment)(exportDecl, description.split('\n'));
+    }
+    return exportDecl;
 }
 /**
  * Create an exported type alias declaration
@@ -348,7 +355,7 @@ function collectEnumTypesFromTables(tables, typeRegistry) {
 /**
  * Generate enum type statements
  */
-function generateEnumTypes(typeRegistry, enumTypeNames) {
+function generateEnumTypes(typeRegistry, enumTypeNames, comments = true) {
     if (enumTypeNames.size === 0)
         return [];
     const statements = [];
@@ -358,7 +365,12 @@ function generateEnumTypes(typeRegistry, enumTypeNames) {
             continue;
         const unionType = createStringLiteralUnion(typeInfo.enumValues);
         const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-        statements.push(t.exportNamedDeclaration(typeAlias));
+        const exportDecl = t.exportNamedDeclaration(typeAlias);
+        const enumDescription = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+        if (enumDescription) {
+            (0, babel_ast_1.addJSDocComment)(exportDecl, enumDescription.split('\n'));
+        }
+        statements.push(exportDecl);
     }
     if (statements.length > 0) {
         addSectionComment(statements, 'Enum Types');
@@ -418,6 +430,7 @@ function buildEntityProperties(table) {
             name: field.name,
             type: isNullable ? `${tsType} | null` : tsType,
             optional: isNullable,
+            description: field.description,
         });
     }
     return properties;
@@ -429,7 +442,7 @@ function generateEntityTypes(tables) {
     const statements = [];
     for (const table of tables) {
         const { typeName } = (0, utils_1.getTableNames)(table);
-        statements.push(createExportedInterface(typeName, buildEntityProperties(table)));
+        statements.push(createExportedInterface(typeName, buildEntityProperties(table), table.description));
     }
     if (statements.length > 0) {
         addSectionComment(statements, 'Entity Types');
@@ -1000,7 +1013,7 @@ function buildTableCrudTypeNames(tables) {
 /**
  * Generate custom input type statements from TypeRegistry
  */
-function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes) {
+function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes, comments = true) {
     const statements = [];
     const generatedTypes = new Set();
     const typesToGenerate = new Set(Array.from(usedInputTypes));
@@ -1036,7 +1049,12 @@ function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes)
             for (const field of typeInfo.inputFields) {
                 const optional = !isRequired(field.type);
                 const tsType = typeRefToTs(field.type);
-                properties.push({ name: field.name, type: tsType, optional });
+                properties.push({
+                    name: field.name,
+                    type: tsType,
+                    optional,
+                    description: (0, utils_1.stripSmartComments)(field.description, comments),
+                });
                 // Follow nested Input types
                 const baseType = (0, type_resolver_1.getTypeBaseName)(field.type);
                 if (baseType &&
@@ -1045,12 +1063,17 @@ function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes)
                     typesToGenerate.add(baseType);
                 }
             }
-            statements.push(createExportedInterface(typeName, properties));
+            statements.push(createExportedInterface(typeName, properties, (0, utils_1.stripSmartComments)(typeInfo.description, comments)));
         }
         else if (typeInfo.kind === 'ENUM' && typeInfo.enumValues) {
             const unionType = createStringLiteralUnion(typeInfo.enumValues);
             const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-            statements.push(t.exportNamedDeclaration(typeAlias));
+            const enumExportDecl = t.exportNamedDeclaration(typeAlias);
+            const enumDescription = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+            if (enumDescription) {
+                (0, babel_ast_1.addJSDocComment)(enumExportDecl, enumDescription.split('\n'));
+            }
+            statements.push(enumExportDecl);
         }
         else {
             // Add comment for unsupported type kind
@@ -1084,7 +1107,7 @@ function collectPayloadTypeNames(operations) {
 /**
  * Generate payload/return type statements
  */
-function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes) {
+function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes, comments = true) {
     const statements = [];
     const generatedTypes = new Set(alreadyGeneratedTypes);
     const typesToGenerate = new Set(Array.from(usedPayloadTypes));
@@ -1132,6 +1155,7 @@ function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTy
                 name: field.name,
                 type: isNullable ? `${tsType} | null` : tsType,
                 optional: isNullable,
+                description: (0, utils_1.stripSmartComments)(field.description, comments),
             });
             // Follow nested OBJECT types
             if (baseType &&
@@ -1143,7 +1167,7 @@ function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTy
                 }
             }
         }
-        statements.push(createExportedInterface(typeName, interfaceProps));
+        statements.push(createExportedInterface(typeName, interfaceProps, (0, utils_1.stripSmartComments)(typeInfo.description, comments)));
         // Build Select type
         const selectMembers = [];
         for (const field of typeInfo.fields) {
@@ -1224,7 +1248,7 @@ function generateConnectionFieldsMap(tables, tableByName) {
 /**
  * Generate comprehensive input-types.ts file using Babel AST
  */
-function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloadTypes) {
+function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloadTypes, comments = true) {
     const statements = [];
     const tablesList = tables ?? [];
     const hasTables = tablesList.length > 0;
@@ -1236,7 +1260,7 @@ function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloa
     // 1. Scalar filter types
     statements.push(...generateScalarFilterTypes());
     // 2. Enum types used by table fields
-    statements.push(...generateEnumTypes(typeRegistry, enumTypes));
+    statements.push(...generateEnumTypes(typeRegistry, enumTypes, comments));
     // 2b. Unknown/custom scalar aliases for schema-specific scalars
     statements.push(...generateCustomScalarTypes(customScalarTypes));
     // 3. Entity and relation types (if tables provided)
@@ -1260,7 +1284,7 @@ function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloa
     statements.push(...generateConnectionFieldsMap(tablesList, tableByName));
     // 7. Custom input types from TypeRegistry
     const tableCrudTypes = tables ? buildTableCrudTypeNames(tables) : undefined;
-    statements.push(...generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes));
+    statements.push(...generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes, comments));
     // 8. Payload/return types for custom operations
     if (usedPayloadTypes && usedPayloadTypes.size > 0) {
         const alreadyGeneratedTypes = new Set();
@@ -1270,7 +1294,7 @@ function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloa
                 alreadyGeneratedTypes.add(typeName);
             }
         }
-        statements.push(...generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes));
+        statements.push(...generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes, comments));
     }
     // Generate code with file header
     const header = (0, utils_1.getGeneratedFileHeader)('GraphQL types for ORM client');

package/core/codegen/queries.js

@@ -132,8 +132,9 @@ function generateListQueryHook(table, options = {}) {
     };
     // Hook
     if (reactQueryEnabled) {
+        const descLine = table.description || `Query hook for fetching ${typeName} list`;
         const docLines = [
-            `Query hook for fetching ${typeName} list`,
+            descLine,
             '',
             '@example',
             '```tsx',
@@ -205,7 +206,7 @@ function generateListQueryHook(table, options = {}) {
         ]);
         const f1Decl = (0, hooks_ast_1.exportAsyncDeclareFunction)(fetchFnName, (0, hooks_ast_1.createSTypeParam)(selectTypeName), [(0, hooks_ast_1.createFunctionParam)('params', f1ParamType)], (0, hooks_ast_1.typeRef)('Promise', [listResultTypeAST((0, hooks_ast_1.sRef)())]));
         (0, hooks_ast_1.addJSDocComment)(f1Decl, [
-            `Fetch ${typeName} list without React hooks`,
+            table.description || `Fetch ${typeName} list without React hooks`,
             '',
             '@example',
             '```ts',
@@ -247,7 +248,7 @@ function generateListQueryHook(table, options = {}) {
             (0, hooks_ast_1.createFunctionParam)('params', p1ParamType),
         ], (0, hooks_ast_1.typeRef)('Promise', [t.tsVoidKeyword()]));
         (0, hooks_ast_1.addJSDocComment)(p1Decl, [
-            `Prefetch ${typeName} list for SSR or cache warming`,
+            table.description || `Prefetch ${typeName} list for SSR or cache warming`,
             '',
             '@example',
             '```ts',
@@ -283,9 +284,9 @@ function generateListQueryHook(table, options = {}) {
             (0, hooks_ast_1.createFunctionParam)('params', pImplParamType),
         ], pBody, (0, hooks_ast_1.typeRef)('Promise', [t.tsVoidKeyword()])));
     }
-    const headerText = reactQueryEnabled
+    const headerText = table.description || (reactQueryEnabled
         ? `List query hook for ${typeName}`
-        : `List query functions for ${typeName}`;
+        : `List query functions for ${typeName}`);
     return {
         fileName: (0, utils_1.getListQueryFileName)(table),
         content: (0, hooks_ast_1.generateHookFileCode)(headerText, statements),
@@ -369,8 +370,9 @@ function generateSingleQueryHook(table, options = {}) {
     };
     // Hook
     if (reactQueryEnabled) {
+        const singleDescLine = table.description || `Query hook for fetching a single ${typeName}`;
         const docLines = [
-            `Query hook for fetching a single ${typeName}`,
+            singleDescLine,
             '',
             '@example',
             '```tsx',
@@ -447,7 +449,7 @@ function generateSingleQueryHook(table, options = {}) {
         ]);
         const f1Decl = (0, hooks_ast_1.exportAsyncDeclareFunction)(fetchFnName, (0, hooks_ast_1.createSTypeParam)(selectTypeName), [(0, hooks_ast_1.createFunctionParam)('params', f1ParamType)], (0, hooks_ast_1.typeRef)('Promise', [singleResultTypeAST((0, hooks_ast_1.sRef)())]));
         (0, hooks_ast_1.addJSDocComment)(f1Decl, [
-            `Fetch a single ${typeName} without React hooks`,
+            table.description || `Fetch a single ${typeName} without React hooks`,
             '',
             '@example',
             '```ts',
@@ -489,7 +491,7 @@ function generateSingleQueryHook(table, options = {}) {
             (0, hooks_ast_1.createFunctionParam)('params', p1ParamType),
         ], (0, hooks_ast_1.typeRef)('Promise', [t.tsVoidKeyword()]));
         (0, hooks_ast_1.addJSDocComment)(p1Decl, [
-            `Prefetch a single ${typeName} for SSR or cache warming`,
+            table.description || `Prefetch a single ${typeName} for SSR or cache warming`,
             '',
             '@example',
             '```ts',
@@ -527,9 +529,9 @@ function generateSingleQueryHook(table, options = {}) {
             (0, hooks_ast_1.createFunctionParam)('params', pImplParamType),
         ], pBody, (0, hooks_ast_1.typeRef)('Promise', [t.tsVoidKeyword()])));
     }
-    const headerText = reactQueryEnabled
+    const headerText = table.description || (reactQueryEnabled
         ? `Single item query hook for ${typeName}`
-        : `Single item query functions for ${typeName}`;
+        : `Single item query functions for ${typeName}`);
     return {
         fileName: (0, utils_1.getSingleQueryFileName)(table),
         content: (0, hooks_ast_1.generateHookFileCode)(headerText, statements),

package/core/codegen/schema-types-generator.d.ts

@@ -22,6 +22,8 @@ export interface GeneratedSchemaTypesFile {
 export interface GenerateSchemaTypesOptions {
     typeRegistry: TypeRegistry;
     tableTypeNames: Set<string>;
+    /** Include descriptions as JSDoc comments. @default true */
+    comments?: boolean;
 }
 export interface PayloadTypesResult {
     statements: t.Statement[];