@constructive-io/graphql-codegen 4.5.3 → 4.6.0

package/esm/core/introspect/infer-tables.js

@@ -13,6 +13,7 @@
  * - Mutation operations: create{Name}, update{Name}, delete{Name}
  */
 import { lcFirst, pluralize, singularize, ucFirst } from 'inflekt';
+import { stripSmartComments } from '../codegen/utils';
 import { getBaseTypeName, isList, unwrapType } from '../../types/introspection';
 // ============================================================================
 // Pattern Matching Constants
@@ -81,6 +82,7 @@ function isInternalType(name) {
 export function inferTablesFromIntrospection(introspection, options = {}) {
     const { __schema: schema } = introspection;
     const { types, queryType, mutationType } = schema;
+    const commentsEnabled = options.comments !== false;
     // Build lookup maps for efficient access
     const typeMap = buildTypeMap(types);
     const { entityNames, entityToConnection, connectionToEntity } = buildEntityConnectionMaps(types, typeMap);
@@ -95,7 +97,7 @@ export function inferTablesFromIntrospection(introspection, options = {}) {
         if (!entityType)
             continue;
         // Infer all metadata for this entity
-        const { table, hasRealOperation } = buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity);
+        const { table, hasRealOperation } = buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity, commentsEnabled);
         // Only include tables that have at least one real operation
         if (hasRealOperation) {
             tables.push(table);
@@ -169,9 +171,9 @@ function resolveEntityNameFromConnectionType(connectionType, typeMap) {
 /**
  * Build a complete CleanTable from an entity type
  */
-function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity) {
+function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity, commentsEnabled) {
     // Extract scalar fields from entity type
-    const fields = extractEntityFields(entityType, typeMap, entityToConnection);
+    const fields = extractEntityFields(entityType, typeMap, entityToConnection, commentsEnabled);
     // Infer relations from entity fields
     const relations = inferRelations(entityType, entityToConnection, connectionToEntity);
     // Match query and mutation operations
@@ -199,9 +201,12 @@ function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationF
         delete: mutationOps.delete,
         patchFieldName,
     };
+    // Extract description from entity type (PostgreSQL COMMENT), strip smart comments
+    const description = commentsEnabled ? stripSmartComments(entityType.description) : undefined;
     return {
         table: {
             name: entityName,
+            ...(description ? { description } : {}),
             fields,
             relations,
             inflection,
@@ -218,7 +223,7 @@ function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationF
  * Extract scalar fields from an entity type
  * Excludes relation fields (those returning other entity types or connections)
  */
-function extractEntityFields(entityType, typeMap, entityToConnection) {
+function extractEntityFields(entityType, typeMap, entityToConnection, commentsEnabled) {
     const fields = [];
     if (!entityType.fields)
         return fields;
@@ -236,8 +241,10 @@ function extractEntityFields(entityType, typeMap, entityToConnection) {
             }
         }
         // Include scalar, enum, and other non-relation fields
+        const fieldDescription = commentsEnabled ? stripSmartComments(field.description) : undefined;
         fields.push({
             name: field.name,
+            ...(fieldDescription ? { description: fieldDescription } : {}),
             type: convertToCleanFieldType(field.type),
         });
     }

package/esm/core/pipeline/index.js

@@ -23,7 +23,8 @@ export async function runCodegenPipeline(options) {
     const { introspection } = await source.fetch();
     // 2. Infer tables from introspection (replaces _meta)
     log('Inferring table metadata from schema...');
-    let tables = inferTablesFromIntrospection(introspection);
+    const commentsEnabled = config.codegen?.comments !== false;
+    let tables = inferTablesFromIntrospection(introspection, { comments: commentsEnabled });
     const totalTables = tables.length;
     log(`  Found ${totalTables} tables`);
     // 3. Filter tables by config (combine exclude and systemExclude)

package/esm/types/config.d.ts

@@ -279,6 +279,12 @@ export interface GraphQLSDKConfigTarget {
     codegen?: {
         /** Skip 'query' field on mutation payloads (default: true) */
         skipQueryField?: boolean;
+        /**
+         * Include PostgreSQL COMMENT descriptions as JSDoc comments in generated code.
+         * PostGraphile smart comments and boilerplate descriptions are automatically stripped.
+         * @default true
+         */
+        comments?: boolean;
     };
     /**
      * Whether to generate ORM client

package/esm/types/config.js

@@ -60,6 +60,7 @@ export const DEFAULT_CONFIG = {
     },
     codegen: {
         skipQueryField: true,
+        comments: true,
     },
     orm: false,
     reactQuery: false,

package/esm/types/schema.d.ts

@@ -7,6 +7,8 @@
  */
 export interface CleanTable {
     name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
     fields: CleanField[];
     relations: CleanRelations;
     /** PostGraphile inflection rules for this table */
@@ -103,6 +105,8 @@ export interface ForeignKeyConstraint extends ConstraintInfo {
  */
 export interface CleanField {
     name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
     type: CleanFieldType;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "4.5.3",
+  "version": "4.6.0",
   "description": "GraphQL SDK generator for Constructive databases with React Query hooks",
   "keywords": [
     "graphql",
@@ -58,12 +58,12 @@
     "@babel/types": "^7.28.6",
     "@constructive-io/graphql-types": "^3.1.1",
     "@inquirerer/utils": "^3.2.3",
-    "@pgpmjs/core": "^6.3.1",
+    "@pgpmjs/core": "^6.3.2",
     "ajv": "^8.17.1",
     "deepmerge": "^4.3.1",
     "find-and-require-package-json": "^0.9.0",
     "gql-ast": "^3.1.0",
-    "graphile-schema": "^1.2.3",
+    "graphile-schema": "^1.2.4",
     "graphql": "^16.9.0",
     "inflekt": "^0.3.1",
     "inquirerer": "^4.4.0",
@@ -72,8 +72,8 @@
     "oxfmt": "^0.26.0",
     "pg-cache": "^3.1.0",
     "pg-env": "^1.5.0",
-    "pgsql-client": "^3.2.2",
-    "pgsql-seed": "^2.2.2",
+    "pgsql-client": "^3.2.3",
+    "pgsql-seed": "^2.2.3",
     "undici": "^7.19.0"
   },
   "peerDependencies": {
@@ -100,5 +100,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "0deec313ff9af77b02cb749be9ef34e236e8cab8"
+  "gitHead": "1b17d61b375abaa04310abe05c2a3ca5881ac650"
 }

package/types/config.d.ts

@@ -279,6 +279,12 @@ export interface GraphQLSDKConfigTarget {
     codegen?: {
         /** Skip 'query' field on mutation payloads (default: true) */
         skipQueryField?: boolean;
+        /**
+         * Include PostgreSQL COMMENT descriptions as JSDoc comments in generated code.
+         * PostGraphile smart comments and boilerplate descriptions are automatically stripped.
+         * @default true
+         */
+        comments?: boolean;
     };
     /**
      * Whether to generate ORM client

package/types/config.js

@@ -69,6 +69,7 @@ exports.DEFAULT_CONFIG = {
     },
     codegen: {
         skipQueryField: true,
+        comments: true,
     },
     orm: false,
     reactQuery: false,

package/types/schema.d.ts

@@ -7,6 +7,8 @@
  */
 export interface CleanTable {
     name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
     fields: CleanField[];
     relations: CleanRelations;
     /** PostGraphile inflection rules for this table */
@@ -103,6 +105,8 @@ export interface ForeignKeyConstraint extends ConstraintInfo {
  */
 export interface CleanField {
     name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
     type: CleanFieldType;
 }
 /**