@constructive-io/graphql-codegen 2.23.2 → 2.24.0

package/esm/types/config.d.ts

@@ -1,6 +1,61 @@
 /**
  * SDK Configuration types
  */
+/**
+ * Entity relationship definition for cascade invalidation
+ */
+export interface EntityRelationship {
+    /** Parent entity name (e.g., 'database' for a table) */
+    parent: string;
+    /** Foreign key field name that references the parent (e.g., 'databaseId') */
+    foreignKey: string;
+    /** Optional transitive ancestors for deep invalidation (e.g., ['database', 'organization']) */
+    ancestors?: string[];
+}
+/**
+ * Query key generation configuration
+ */
+export interface QueryKeyConfig {
+    /**
+     * Key structure style
+     * - 'flat': Simple ['entity', 'scope', data] structure
+     * - 'hierarchical': Nested factory pattern with scope support (lukemorales-style)
+     * @default 'hierarchical'
+     */
+    style?: 'flat' | 'hierarchical';
+    /**
+     * Define entity relationships for cascade invalidation and scoped keys
+     * Key: child entity name (lowercase), Value: relationship definition
+     *
+     * @example
+     * ```ts
+     * relationships: {
+     *   database: { parent: 'organization', foreignKey: 'organizationId' },
+     *   table: { parent: 'database', foreignKey: 'databaseId', ancestors: ['organization'] },
+     *   field: { parent: 'table', foreignKey: 'tableId', ancestors: ['database', 'organization'] },
+     * }
+     * ```
+     */
+    relationships?: Record<string, EntityRelationship>;
+    /**
+     * Generate scope-aware query keys for entities with relationships
+     * When true, keys include optional scope parameters for hierarchical invalidation
+     * @default true
+     */
+    generateScopedKeys?: boolean;
+    /**
+     * Generate cascade invalidation helpers
+     * Creates helpers that invalidate parent entities and all their children
+     * @default true
+     */
+    generateCascadeHelpers?: boolean;
+    /**
+     * Generate mutation keys for tracking in-flight mutations
+     * Useful for optimistic updates and mutation deduplication
+     * @default true
+     */
+    generateMutationKeys?: boolean;
+}
 /**
  * Main configuration for graphql-codegen
  */
@@ -113,6 +168,11 @@ export interface GraphQLSDKConfig {
          */
         enabled?: boolean;
     };
+    /**
+     * Query key generation configuration
+     * Controls how query keys are structured for cache management
+     */
+    queryKeys?: QueryKeyConfig;
     /**
      * Watch mode configuration (dev-only feature)
      * When enabled via CLI --watch flag, the CLI will poll the endpoint for schema changes
@@ -157,6 +217,16 @@ export interface ResolvedWatchConfig {
     touchFile: string | null;
     clearScreen: boolean;
 }
+/**
+ * Resolved query key configuration with defaults applied
+ */
+export interface ResolvedQueryKeyConfig {
+    style: 'flat' | 'hierarchical';
+    relationships: Record<string, EntityRelationship>;
+    generateScopedKeys: boolean;
+    generateCascadeHelpers: boolean;
+    generateMutationKeys: boolean;
+}
 /**
  * Resolved configuration with defaults applied
  */
@@ -203,12 +273,17 @@ export interface ResolvedConfig {
     reactQuery: {
         enabled: boolean;
     };
+    queryKeys: ResolvedQueryKeyConfig;
     watch: ResolvedWatchConfig;
 }
 /**
  * Default watch configuration values
  */
 export declare const DEFAULT_WATCH_CONFIG: ResolvedWatchConfig;
+/**
+ * Default query key configuration values
+ */
+export declare const DEFAULT_QUERY_KEY_CONFIG: ResolvedQueryKeyConfig;
 /**
  * Default configuration values
  */

package/esm/types/config.js

@@ -10,6 +10,16 @@ export const DEFAULT_WATCH_CONFIG = {
     touchFile: null,
     clearScreen: true,
 };
+/**
+ * Default query key configuration values
+ */
+export const DEFAULT_QUERY_KEY_CONFIG = {
+    style: 'hierarchical',
+    relationships: {},
+    generateScopedKeys: true,
+    generateCascadeHelpers: true,
+    generateMutationKeys: true,
+};
 /**
  * Default configuration values
  */
@@ -43,8 +53,9 @@ export const DEFAULT_CONFIG = {
     },
     orm: null, // ORM generation disabled by default
     reactQuery: {
-        enabled: false, // React Query hooks disabled by default
+        enabled: true, // React Query hooks enabled by default for generate command
     },
+    queryKeys: DEFAULT_QUERY_KEY_CONFIG,
     watch: DEFAULT_WATCH_CONFIG,
 };
 /**
@@ -103,6 +114,13 @@ export function resolveConfig(config) {
         reactQuery: {
             enabled: config.reactQuery?.enabled ?? DEFAULT_CONFIG.reactQuery.enabled,
         },
+        queryKeys: {
+            style: config.queryKeys?.style ?? DEFAULT_QUERY_KEY_CONFIG.style,
+            relationships: config.queryKeys?.relationships ?? DEFAULT_QUERY_KEY_CONFIG.relationships,
+            generateScopedKeys: config.queryKeys?.generateScopedKeys ?? DEFAULT_QUERY_KEY_CONFIG.generateScopedKeys,
+            generateCascadeHelpers: config.queryKeys?.generateCascadeHelpers ?? DEFAULT_QUERY_KEY_CONFIG.generateCascadeHelpers,
+            generateMutationKeys: config.queryKeys?.generateMutationKeys ?? DEFAULT_QUERY_KEY_CONFIG.generateMutationKeys,
+        },
         watch: {
             pollInterval: config.watch?.pollInterval ?? DEFAULT_WATCH_CONFIG.pollInterval,
             debounce: config.watch?.debounce ?? DEFAULT_WATCH_CONFIG.debounce,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "description": "CLI-based GraphQL SDK generator for PostGraphile endpoints with React Query hooks",
   "keywords": [
     "graphql",
@@ -49,14 +49,15 @@
     "example:orm": "tsx examples/orm-sdk.ts"
   },
   "dependencies": {
+    "@babel/generator": "^7.28.5",
+    "@babel/types": "^7.28.5",
     "ajv": "^8.17.1",
     "commander": "^12.1.0",
     "gql-ast": "^2.4.6",
     "graphql": "15.10.1",
     "inflekt": "^0.2.0",
     "jiti": "^2.6.1",
-    "prettier": "^3.7.4",
-    "ts-morph": "^27.0.2"
+    "prettier": "^3.7.4"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
@@ -72,6 +73,7 @@
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.90.16",
+    "@types/babel__generator": "^7.27.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.19.27",
     "@types/react": "^19.2.7",
@@ -81,5 +83,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "a56b001d06690989ca4c66c3bfd7d260c3649eea"
+  "gitHead": "36d48ae1cde080add7953f46a6738a31909cf050"
 }

package/types/config.d.ts

@@ -1,6 +1,61 @@
 /**
  * SDK Configuration types
  */
+/**
+ * Entity relationship definition for cascade invalidation
+ */
+export interface EntityRelationship {
+    /** Parent entity name (e.g., 'database' for a table) */
+    parent: string;
+    /** Foreign key field name that references the parent (e.g., 'databaseId') */
+    foreignKey: string;
+    /** Optional transitive ancestors for deep invalidation (e.g., ['database', 'organization']) */
+    ancestors?: string[];
+}
+/**
+ * Query key generation configuration
+ */
+export interface QueryKeyConfig {
+    /**
+     * Key structure style
+     * - 'flat': Simple ['entity', 'scope', data] structure
+     * - 'hierarchical': Nested factory pattern with scope support (lukemorales-style)
+     * @default 'hierarchical'
+     */
+    style?: 'flat' | 'hierarchical';
+    /**
+     * Define entity relationships for cascade invalidation and scoped keys
+     * Key: child entity name (lowercase), Value: relationship definition
+     *
+     * @example
+     * ```ts
+     * relationships: {
+     *   database: { parent: 'organization', foreignKey: 'organizationId' },
+     *   table: { parent: 'database', foreignKey: 'databaseId', ancestors: ['organization'] },
+     *   field: { parent: 'table', foreignKey: 'tableId', ancestors: ['database', 'organization'] },
+     * }
+     * ```
+     */
+    relationships?: Record<string, EntityRelationship>;
+    /**
+     * Generate scope-aware query keys for entities with relationships
+     * When true, keys include optional scope parameters for hierarchical invalidation
+     * @default true
+     */
+    generateScopedKeys?: boolean;
+    /**
+     * Generate cascade invalidation helpers
+     * Creates helpers that invalidate parent entities and all their children
+     * @default true
+     */
+    generateCascadeHelpers?: boolean;
+    /**
+     * Generate mutation keys for tracking in-flight mutations
+     * Useful for optimistic updates and mutation deduplication
+     * @default true
+     */
+    generateMutationKeys?: boolean;
+}
 /**
  * Main configuration for graphql-codegen
  */
@@ -113,6 +168,11 @@ export interface GraphQLSDKConfig {
          */
         enabled?: boolean;
     };
+    /**
+     * Query key generation configuration
+     * Controls how query keys are structured for cache management
+     */
+    queryKeys?: QueryKeyConfig;
     /**
      * Watch mode configuration (dev-only feature)
      * When enabled via CLI --watch flag, the CLI will poll the endpoint for schema changes
@@ -157,6 +217,16 @@ export interface ResolvedWatchConfig {
     touchFile: string | null;
     clearScreen: boolean;
 }
+/**
+ * Resolved query key configuration with defaults applied
+ */
+export interface ResolvedQueryKeyConfig {
+    style: 'flat' | 'hierarchical';
+    relationships: Record<string, EntityRelationship>;
+    generateScopedKeys: boolean;
+    generateCascadeHelpers: boolean;
+    generateMutationKeys: boolean;
+}
 /**
  * Resolved configuration with defaults applied
  */
@@ -203,12 +273,17 @@ export interface ResolvedConfig {
     reactQuery: {
         enabled: boolean;
     };
+    queryKeys: ResolvedQueryKeyConfig;
     watch: ResolvedWatchConfig;
 }
 /**
  * Default watch configuration values
  */
 export declare const DEFAULT_WATCH_CONFIG: ResolvedWatchConfig;
+/**
+ * Default query key configuration values
+ */
+export declare const DEFAULT_QUERY_KEY_CONFIG: ResolvedQueryKeyConfig;
 /**
  * Default configuration values
  */

package/types/config.js

@@ -3,7 +3,7 @@
  * SDK Configuration types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ORM_CONFIG = exports.DEFAULT_CONFIG = exports.DEFAULT_WATCH_CONFIG = void 0;
+exports.DEFAULT_ORM_CONFIG = exports.DEFAULT_CONFIG = exports.DEFAULT_QUERY_KEY_CONFIG = exports.DEFAULT_WATCH_CONFIG = void 0;
 exports.defineConfig = defineConfig;
 exports.resolveConfig = resolveConfig;
 /**
@@ -15,6 +15,16 @@ exports.DEFAULT_WATCH_CONFIG = {
     touchFile: null,
     clearScreen: true,
 };
+/**
+ * Default query key configuration values
+ */
+exports.DEFAULT_QUERY_KEY_CONFIG = {
+    style: 'hierarchical',
+    relationships: {},
+    generateScopedKeys: true,
+    generateCascadeHelpers: true,
+    generateMutationKeys: true,
+};
 /**
  * Default configuration values
  */
@@ -48,8 +58,9 @@ exports.DEFAULT_CONFIG = {
     },
     orm: null, // ORM generation disabled by default
     reactQuery: {
-        enabled: false, // React Query hooks disabled by default
+        enabled: true, // React Query hooks enabled by default for generate command
     },
+    queryKeys: exports.DEFAULT_QUERY_KEY_CONFIG,
     watch: exports.DEFAULT_WATCH_CONFIG,
 };
 /**
@@ -108,6 +119,13 @@ function resolveConfig(config) {
         reactQuery: {
             enabled: config.reactQuery?.enabled ?? exports.DEFAULT_CONFIG.reactQuery.enabled,
         },
+        queryKeys: {
+            style: config.queryKeys?.style ?? exports.DEFAULT_QUERY_KEY_CONFIG.style,
+            relationships: config.queryKeys?.relationships ?? exports.DEFAULT_QUERY_KEY_CONFIG.relationships,
+            generateScopedKeys: config.queryKeys?.generateScopedKeys ?? exports.DEFAULT_QUERY_KEY_CONFIG.generateScopedKeys,
+            generateCascadeHelpers: config.queryKeys?.generateCascadeHelpers ?? exports.DEFAULT_QUERY_KEY_CONFIG.generateCascadeHelpers,
+            generateMutationKeys: config.queryKeys?.generateMutationKeys ?? exports.DEFAULT_QUERY_KEY_CONFIG.generateMutationKeys,
+        },
         watch: {
             pollInterval: config.watch?.pollInterval ?? exports.DEFAULT_WATCH_CONFIG.pollInterval,
             debounce: config.watch?.debounce ?? exports.DEFAULT_WATCH_CONFIG.debounce,

package/cli/codegen/ts-ast.d.ts

@@ -1,124 +0,0 @@
-/**
- * TypeScript AST builders using ts-morph
- *
- * Provides utilities for generating TypeScript code via AST manipulation
- * instead of string concatenation.
- */
-import { Project, SourceFile, type InterfaceDeclarationStructure, type FunctionDeclarationStructure, type VariableStatementStructure, type ImportDeclarationStructure, type TypeAliasDeclarationStructure } from 'ts-morph';
-/**
- * Create a new ts-morph project for code generation
- */
-export declare function createProject(): Project;
-/**
- * Create a source file in the project
- */
-export declare function createSourceFile(project: Project, fileName: string): SourceFile;
-/**
- * Get formatted output from source file
- */
-export declare function getFormattedOutput(sourceFile: SourceFile): string;
-/**
- * Get output with minimal formatting (preserves intentional blank lines)
- * Post-processes to fix indentation and section comment spacing
- *
- * ts-morph generates type alias bodies with extra indentation:
- * - Properties get 6 spaces (we want 2)
- * - Closing brace gets 4 spaces (we want 0)
- *
- * For interfaces it uses 4 spaces which we convert to 2.
- */
-export declare function getMinimalFormattedOutput(sourceFile: SourceFile): string;
-/**
- * Create a file header comment
- */
-export declare function createFileHeader(description: string): string;
-/**
- * Create JSDoc comment for a declaration
- */
-export declare function createJsDoc(lines: string[]): string;
-export interface ImportSpec {
-    moduleSpecifier: string;
-    namedImports?: string[];
-    typeOnlyNamedImports?: string[];
-    defaultImport?: string;
-}
-/**
- * Create import declaration structure
- */
-export declare function createImport(spec: ImportSpec): ImportDeclarationStructure;
-export interface InterfaceProperty {
-    name: string;
-    type: string;
-    optional?: boolean;
-    docs?: string[];
-}
-/**
- * Create interface declaration structure
- */
-export declare function createInterface(name: string, properties: InterfaceProperty[], options?: {
-    docs?: string[];
-    isExported?: boolean;
-    extends?: string[];
-}): InterfaceDeclarationStructure;
-/**
- * Create filter interface with standard PostGraphile operators
- */
-export declare function createFilterInterface(name: string, fieldFilters: Array<{
-    fieldName: string;
-    filterType: string;
-}>, options?: {
-    isExported?: boolean;
-}): InterfaceDeclarationStructure;
-/**
- * Create type alias declaration structure
- */
-export declare function createTypeAlias(name: string, type: string, options?: {
-    docs?: string[];
-    isExported?: boolean;
-}): TypeAliasDeclarationStructure;
-/**
- * Create union type from string literals
- */
-export declare function createUnionType(values: string[]): string;
-/**
- * Create const variable statement structure
- */
-export declare function createConst(name: string, initializer: string, options?: {
-    docs?: string[];
-    isExported?: boolean;
-    type?: string;
-}): VariableStatementStructure;
-/**
- * Create a template literal string (for GraphQL documents)
- */
-export declare function createTemplateLiteral(content: string): string;
-export interface FunctionParameter {
-    name: string;
-    type: string;
-    optional?: boolean;
-    initializer?: string;
-}
-/**
- * Create function declaration structure
- */
-export declare function createFunction(name: string, parameters: FunctionParameter[], returnType: string, body: string, options?: {
-    docs?: string[];
-    isExported?: boolean;
-    isAsync?: boolean;
-}): FunctionDeclarationStructure;
-/**
- * Create re-export statement
- */
-export declare function createReExport(names: string[], moduleSpecifier: string, isTypeOnly?: boolean): string;
-/**
- * Create barrel export statement
- */
-export declare function createBarrelExport(moduleSpecifier: string): string;
-/**
- * Create a section divider comment for generated code
- */
-export declare function createSectionComment(title: string): string;
-/**
- * Add a section comment to source file with proper spacing
- */
-export declare function addSectionComment(sourceFile: SourceFile, title: string): void;