@constructive-io/graphql-codegen 2.23.3 → 2.24.1

package/README.md

@@ -837,12 +837,12 @@ import { useCreateCarMutation, useCarsQuery } from './generated/hooks';
 
 function CreateCarWithInvalidation() {
   const queryClient = useQueryClient();
-  
+
   const createCar = useCreateCarMutation({
     onSuccess: () => {
       // Invalidate all car queries to refetch
       queryClient.invalidateQueries({ queryKey: ['cars'] });
-      
+
       // Or invalidate specific queries
       queryClient.invalidateQueries({ queryKey: ['cars', { first: 10 }] });
     },
@@ -852,6 +852,151 @@ function CreateCarWithInvalidation() {
 }
 ```
 
+### Centralized Query Keys
+
+The codegen generates a centralized query key factory following the [lukemorales query-key-factory](https://tanstack.com/query/docs/framework/react/community/lukemorales-query-key-factory) pattern. This provides type-safe cache management with autocomplete support.
+
+#### Generated Files
+
+| File | Purpose |
+|------|---------|
+| `query-keys.ts` | Query key factories for all entities |
+| `mutation-keys.ts` | Mutation key factories for tracking in-flight mutations |
+| `invalidation.ts` | Type-safe cache invalidation helpers |
+
+#### Using Query Keys
+
+```tsx
+import { userKeys, invalidate } from './generated/hooks';
+import { useQueryClient } from '@tanstack/react-query';
+
+// Query key structure
+userKeys.all                    // ['user']
+userKeys.lists()                // ['user', 'list']
+userKeys.list({ first: 10 })    // ['user', 'list', { first: 10 }]
+userKeys.details()              // ['user', 'detail']
+userKeys.detail('user-123')     // ['user', 'detail', 'user-123']
+
+// Granular cache invalidation
+const queryClient = useQueryClient();
+
+// Invalidate ALL user queries
+queryClient.invalidateQueries({ queryKey: userKeys.all });
+
+// Invalidate only list queries
+queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+
+// Invalidate a specific user
+queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) });
+```
+
+#### Invalidation Helpers
+
+Type-safe invalidation utilities:
+
+```tsx
+import { invalidate, remove } from './generated/hooks';
+
+// Invalidate queries (triggers refetch)
+invalidate.user.all(queryClient);
+invalidate.user.lists(queryClient);
+invalidate.user.detail(queryClient, userId);
+
+// Remove from cache (for delete operations)
+remove.user(queryClient, userId);
+```
+
+#### Mutation Key Tracking
+
+Track in-flight mutations with `useIsMutating`:
+
+```tsx
+import { useIsMutating } from '@tanstack/react-query';
+import { userMutationKeys } from './generated/hooks';
+
+function UserList() {
+  // Check if any user mutations are in progress
+  const isMutating = useIsMutating({ mutationKey: userMutationKeys.all });
+
+  // Check if a specific user is being deleted
+  const isDeleting = useIsMutating({
+    mutationKey: userMutationKeys.delete(userId)
+  });
+
+  return (
+    <div>
+      {isMutating > 0 && <Spinner />}
+      <button disabled={isDeleting > 0}>Delete</button>
+    </div>
+  );
+}
+```
+
+#### Optimistic Updates with Query Keys
+
+```tsx
+import { useCreateUserMutation, userKeys } from './generated/hooks';
+
+const createUser = useCreateUserMutation({
+  onMutate: async (newUser) => {
+    // Cancel outgoing refetches
+    await queryClient.cancelQueries({ queryKey: userKeys.lists() });
+
+    // Snapshot previous value
+    const previous = queryClient.getQueryData(userKeys.list());
+
+    // Optimistically update cache
+    queryClient.setQueryData(userKeys.list(), (old) => ({
+      ...old,
+      users: {
+        ...old.users,
+        nodes: [...old.users.nodes, { id: 'temp', ...newUser.input.user }]
+      },
+    }));
+
+    return { previous };
+  },
+  onError: (err, variables, context) => {
+    // Rollback on error
+    queryClient.setQueryData(userKeys.list(), context.previous);
+  },
+  onSettled: () => {
+    // Refetch after mutation
+    queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+  },
+});
+```
+
+#### Configuration
+
+Query key generation is enabled by default. Configure in your config file:
+
+```typescript
+// graphql-sdk.config.ts
+export default defineConfig({
+  endpoint: 'https://api.example.com/graphql',
+
+  queryKeys: {
+    // Generate scope-aware keys (default: true)
+    generateScopedKeys: true,
+
+    // Generate mutation keys (default: true)
+    generateMutationKeys: true,
+
+    // Generate invalidation helpers (default: true)
+    generateCascadeHelpers: true,
+
+    // Define entity relationships for cascade invalidation
+    relationships: {
+      table: { parent: 'database', foreignKey: 'databaseId' },
+      field: { parent: 'table', foreignKey: 'tableId' },
+    },
+  },
+});
+```
+
+For detailed documentation on query key factory design and implementation, see [docs/QUERY-KEY-FACTORY.md](./docs/QUERY-KEY-FACTORY.md).
+
 ### Prefetching
 
 ```tsx

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

@@ -0,0 +1,53 @@
+/**
+ * Babel AST utilities for code generation
+ *
+ * Provides minimal helper functions for building TypeScript AST nodes.
+ * Use raw t.* calls for most operations - only helpers that provide
+ * real value beyond simple wrapping are included here.
+ */
+import generate from '@babel/generator';
+import * as t from '@babel/types';
+export { t, generate };
+/**
+ * Generate code from an array of statements
+ */
+export declare function generateCode(statements: t.Statement[]): string;
+/**
+ * Create a block comment
+ */
+export declare const commentBlock: (value: string) => t.CommentBlock;
+/**
+ * Create a line comment
+ */
+export declare const commentLine: (value: string) => t.CommentLine;
+/**
+ * Add a leading JSDoc comment to a node
+ */
+export declare function addJSDocComment<T extends t.Node>(node: T, lines: string[]): T;
+/**
+ * Add a leading single-line comment to a node
+ */
+export declare function addLineComment<T extends t.Node>(node: T, text: string): T;
+/**
+ * Create an 'as const' assertion - common pattern worth abstracting
+ */
+export declare function asConst(expression: t.Expression): t.TSAsExpression;
+/**
+ * Create an array expression with 'as const' - very common pattern
+ */
+export declare function constArray(elements: (t.Expression | t.SpreadElement)[]): t.TSAsExpression;
+/**
+ * Create a typed parameter - saves boilerplate for type annotations
+ */
+export declare function typedParam(name: string, typeAnnotation: t.TSType, optional?: boolean): t.Identifier;
+/**
+ * Create keyof typeof expression - complex nested type operators
+ */
+export declare function keyofTypeof(name: string): t.TSTypeOperator;
+/**
+ * Create a call expression with TypeScript type parameters
+ *
+ * This is used to generate typed function calls like:
+ * execute<ResultType, VariablesType>(document, variables)
+ */
+export declare function createTypedCallExpression(callee: t.Expression, args: (t.Expression | t.SpreadElement)[], typeParams: t.TSType[]): t.CallExpression;

package/cli/codegen/babel-ast.js

@@ -0,0 +1,160 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commentLine = exports.commentBlock = exports.generate = exports.t = void 0;
+exports.generateCode = generateCode;
+exports.addJSDocComment = addJSDocComment;
+exports.addLineComment = addLineComment;
+exports.asConst = asConst;
+exports.constArray = constArray;
+exports.typedParam = typedParam;
+exports.keyofTypeof = keyofTypeof;
+exports.createTypedCallExpression = createTypedCallExpression;
+/**
+ * Babel AST utilities for code generation
+ *
+ * Provides minimal helper functions for building TypeScript AST nodes.
+ * Use raw t.* calls for most operations - only helpers that provide
+ * real value beyond simple wrapping are included here.
+ */
+const generator_1 = __importDefault(require("@babel/generator"));
+exports.generate = generator_1.default;
+const t = __importStar(require("@babel/types"));
+exports.t = t;
+/**
+ * Generate code from an array of statements
+ */
+function generateCode(statements) {
+    const program = t.program(statements);
+    // @ts-ignore - Babel types mismatch
+    return (0, generator_1.default)(program).code;
+}
+/**
+ * Create a block comment
+ */
+const commentBlock = (value) => {
+    return {
+        type: 'CommentBlock',
+        value,
+        start: null,
+        end: null,
+        loc: null,
+    };
+};
+exports.commentBlock = commentBlock;
+/**
+ * Create a line comment
+ */
+const commentLine = (value) => {
+    return {
+        type: 'CommentLine',
+        value,
+        start: null,
+        end: null,
+        loc: null,
+    };
+};
+exports.commentLine = commentLine;
+/**
+ * Add a leading JSDoc comment to a node
+ */
+function addJSDocComment(node, lines) {
+    const commentText = lines.length === 1
+        ? `* ${lines[0]} `
+        : `*\n${lines.map(line => ` * ${line}`).join('\n')}\n `;
+    if (!node.leadingComments) {
+        node.leadingComments = [];
+    }
+    node.leadingComments.push((0, exports.commentBlock)(commentText));
+    return node;
+}
+/**
+ * Add a leading single-line comment to a node
+ */
+function addLineComment(node, text) {
+    if (!node.leadingComments) {
+        node.leadingComments = [];
+    }
+    node.leadingComments.push((0, exports.commentLine)(` ${text}`));
+    return node;
+}
+/**
+ * Create an 'as const' assertion - common pattern worth abstracting
+ */
+function asConst(expression) {
+    return t.tsAsExpression(expression, t.tsTypeReference(t.identifier('const')));
+}
+/**
+ * Create an array expression with 'as const' - very common pattern
+ */
+function constArray(elements) {
+    return asConst(t.arrayExpression(elements));
+}
+/**
+ * Create a typed parameter - saves boilerplate for type annotations
+ */
+function typedParam(name, typeAnnotation, optional = false) {
+    const param = t.identifier(name);
+    param.typeAnnotation = t.tsTypeAnnotation(typeAnnotation);
+    param.optional = optional;
+    return param;
+}
+/**
+ * Create keyof typeof expression - complex nested type operators
+ */
+function keyofTypeof(name) {
+    const typeofOp = t.tsTypeOperator(t.tsTypeReference(t.identifier(name)));
+    typeofOp.operator = 'typeof';
+    const keyofOp = t.tsTypeOperator(typeofOp);
+    keyofOp.operator = 'keyof';
+    return keyofOp;
+}
+/**
+ * Create a call expression with TypeScript type parameters
+ *
+ * This is used to generate typed function calls like:
+ * execute<ResultType, VariablesType>(document, variables)
+ */
+function createTypedCallExpression(callee, args, typeParams) {
+    const call = t.callExpression(callee, args);
+    if (typeParams.length > 0) {
+        // @ts-ignore - Babel types support typeParameters on CallExpression for TS
+        call.typeParameters = t.tsTypeParameterInstantiation(typeParams);
+    }
+    return call;
+}

package/cli/codegen/barrel.d.ts

@@ -1,8 +1,7 @@
 /**
  * Barrel file generators - creates index.ts files for exports
  *
- * Using simple string generation for barrel files since they're straightforward
- * and ts-morph has issues with insertText + addStatements combination.
+ * Using Babel AST for generating barrel (index.ts) files with re-exports.
  */
 import type { CleanTable } from '../../types/schema';
 /**
@@ -22,6 +21,12 @@ export declare function generateMutationsBarrel(tables: CleanTable[]): string;
 export interface MainBarrelOptions {
     hasSchemaTypes?: boolean;
     hasMutations?: boolean;
+    /** Whether query-keys.ts was generated */
+    hasQueryKeys?: boolean;
+    /** Whether mutation-keys.ts was generated */
+    hasMutationKeys?: boolean;
+    /** Whether invalidation.ts was generated */
+    hasInvalidation?: boolean;
 }
 export declare function generateMainBarrel(tables: CleanTable[], options?: MainBarrelOptions | boolean): string;
 /**