@constructive-io/graphql-codegen 2.23.2 → 2.24.0

package/esm/cli/codegen/index.js

@@ -1,3 +1,4 @@
+import { DEFAULT_QUERY_KEY_CONFIG } from '../../types/config';
 import { generateClientFile } from './client';
 import { generateTypesFile } from './types';
 import { generateSchemaTypesFile } from './schema-types-generator';
@@ -5,6 +6,9 @@ import { generateAllQueryHooks } from './queries';
 import { generateAllMutationHooks } from './mutations';
 import { generateAllCustomQueryHooks } from './custom-queries';
 import { generateAllCustomMutationHooks } from './custom-mutations';
+import { generateQueryKeysFile } from './query-keys';
+import { generateMutationKeysFile } from './mutation-keys';
+import { generateInvalidationFile } from './invalidation';
 import { generateQueriesBarrel, generateMutationsBarrel, generateMainBarrel, generateCustomQueriesBarrel, generateCustomMutationsBarrel, } from './barrel';
 import { getTableNames } from './utils';
 // ============================================================================
@@ -26,6 +30,10 @@ export function generate(options) {
     const maxDepth = config.codegen.maxFieldDepth;
     const skipQueryField = config.codegen.skipQueryField;
     const reactQueryEnabled = config.reactQuery.enabled;
+    // Query key configuration (use defaults if not provided)
+    const queryKeyConfig = config.queryKeys ?? DEFAULT_QUERY_KEY_CONFIG;
+    const useCentralizedKeys = queryKeyConfig.generateScopedKeys;
+    const hasRelationships = Object.keys(queryKeyConfig.relationships).length > 0;
     // 1. Generate client.ts
     files.push({
         path: 'client.ts',
@@ -59,8 +67,53 @@ export function generate(options) {
             enumsFromSchemaTypes: generatedEnumNames,
         }),
     });
+    // 3b. Generate centralized query keys (query-keys.ts)
+    let hasQueryKeys = false;
+    if (useCentralizedKeys) {
+        const queryKeysResult = generateQueryKeysFile({
+            tables,
+            customQueries: customOperations?.queries ?? [],
+            config: queryKeyConfig,
+        });
+        files.push({
+            path: queryKeysResult.fileName,
+            content: queryKeysResult.content,
+        });
+        hasQueryKeys = true;
+    }
+    // 3c. Generate centralized mutation keys (mutation-keys.ts)
+    let hasMutationKeys = false;
+    if (useCentralizedKeys && queryKeyConfig.generateMutationKeys) {
+        const mutationKeysResult = generateMutationKeysFile({
+            tables,
+            customMutations: customOperations?.mutations ?? [],
+            config: queryKeyConfig,
+        });
+        files.push({
+            path: mutationKeysResult.fileName,
+            content: mutationKeysResult.content,
+        });
+        hasMutationKeys = true;
+    }
+    // 3d. Generate cache invalidation helpers (invalidation.ts)
+    let hasInvalidation = false;
+    if (useCentralizedKeys && queryKeyConfig.generateCascadeHelpers) {
+        const invalidationResult = generateInvalidationFile({
+            tables,
+            config: queryKeyConfig,
+        });
+        files.push({
+            path: invalidationResult.fileName,
+            content: invalidationResult.content,
+        });
+        hasInvalidation = true;
+    }
     // 4. Generate table-based query hooks (queries/*.ts)
-    const queryHooks = generateAllQueryHooks(tables, { reactQueryEnabled });
+    const queryHooks = generateAllQueryHooks(tables, {
+        reactQueryEnabled,
+        useCentralizedKeys,
+        hasRelationships,
+    });
     for (const hook of queryHooks) {
         files.push({
             path: `queries/${hook.fileName}`,
@@ -77,6 +130,7 @@ export function generate(options) {
             skipQueryField,
             reactQueryEnabled,
             tableTypeNames,
+            useCentralizedKeys,
         });
         for (const hook of customQueryHooks) {
             files.push({
@@ -96,6 +150,8 @@ export function generate(options) {
     const mutationHooks = generateAllMutationHooks(tables, {
         reactQueryEnabled,
         enumsFromSchemaTypes: generatedEnumNames,
+        useCentralizedKeys,
+        hasRelationships,
     });
     for (const hook of mutationHooks) {
         files.push({
@@ -113,6 +169,7 @@ export function generate(options) {
             skipQueryField,
             reactQueryEnabled,
             tableTypeNames,
+            useCentralizedKeys,
         });
         for (const hook of customMutationHooks) {
             files.push({
@@ -135,7 +192,13 @@ export function generate(options) {
     // 9. Generate main index.ts barrel (with schema-types if present)
     files.push({
         path: 'index.ts',
-        content: generateMainBarrel(tables, { hasSchemaTypes, hasMutations }),
+        content: generateMainBarrel(tables, {
+            hasSchemaTypes,
+            hasMutations,
+            hasQueryKeys,
+            hasMutationKeys,
+            hasInvalidation,
+        }),
     });
     return {
         files,
@@ -159,3 +222,6 @@ export { generateAllMutationHooks, generateCreateMutationHook, generateUpdateMut
 export { generateAllCustomQueryHooks, generateCustomQueryHook, } from './custom-queries';
 export { generateAllCustomMutationHooks, generateCustomMutationHook, } from './custom-mutations';
 export { generateQueriesBarrel, generateMutationsBarrel, generateMainBarrel, generateCustomQueriesBarrel, generateCustomMutationsBarrel, } from './barrel';
+export { generateQueryKeysFile } from './query-keys';
+export { generateMutationKeysFile } from './mutation-keys';
+export { generateInvalidationFile } from './invalidation';

package/esm/cli/codegen/invalidation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cache invalidation helpers generator
+ *
+ * Generates type-safe cache invalidation utilities with cascade support
+ * for parent-child entity relationships.
+ */
+import type { CleanTable } from '../../types/schema';
+import type { ResolvedQueryKeyConfig } from '../../types/config';
+export interface InvalidationGeneratorOptions {
+    tables: CleanTable[];
+    config: ResolvedQueryKeyConfig;
+}
+export interface GeneratedInvalidationFile {
+    fileName: string;
+    content: string;
+}
+/**
+ * Generate the complete invalidation.ts file
+ */
+export declare function generateInvalidationFile(options: InvalidationGeneratorOptions): GeneratedInvalidationFile;

package/esm/cli/codegen/invalidation.js

@@ -0,0 +1,291 @@
+import { getTableNames, getGeneratedFileHeader, ucFirst, lcFirst } from './utils';
+import * as t from '@babel/types';
+import { generateCode, addJSDocComment, asConst, typedParam, addLineComment, } from './babel-ast';
+/**
+ * Build a map of parent -> children for cascade invalidation
+ */
+function buildChildrenMap(relationships) {
+    const childrenMap = new Map();
+    for (const [child, rel] of Object.entries(relationships)) {
+        const parent = rel.parent.toLowerCase();
+        if (!childrenMap.has(parent)) {
+            childrenMap.set(parent, []);
+        }
+        childrenMap.get(parent).push(child);
+    }
+    return childrenMap;
+}
+/**
+ * Get all descendants (children, grandchildren, etc.) of an entity
+ */
+function getAllDescendants(entity, childrenMap) {
+    const descendants = [];
+    const queue = [entity.toLowerCase()];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const children = childrenMap.get(current) ?? [];
+        for (const child of children) {
+            descendants.push(child);
+            queue.push(child);
+        }
+    }
+    return descendants;
+}
+/**
+ * Build the invalidate object property for a single entity
+ */
+function buildEntityInvalidateProperty(table, relationships, childrenMap, allTables) {
+    const { typeName, singularName } = getTableNames(table);
+    const entityKey = typeName.toLowerCase();
+    const keysName = `${lcFirst(typeName)}Keys`;
+    const descendants = getAllDescendants(entityKey, childrenMap);
+    const hasDescendants = descendants.length > 0;
+    const relationship = relationships[entityKey];
+    const hasParent = !!relationship;
+    const innerProperties = [];
+    // Helper to create QueryClient type reference
+    const queryClientTypeRef = () => t.tsTypeReference(t.identifier('QueryClient'));
+    const stringOrNumberType = () => t.tsUnionType([t.tsStringKeyword(), t.tsNumberKeyword()]);
+    // Helper to create queryClient.invalidateQueries({ queryKey: ... })
+    const invalidateCall = (queryKeyExpr) => t.callExpression(t.memberExpression(t.identifier('queryClient'), t.identifier('invalidateQueries')), [t.objectExpression([t.objectProperty(t.identifier('queryKey'), queryKeyExpr)])]);
+    // all property
+    const allArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef())], invalidateCall(t.memberExpression(t.identifier(keysName), t.identifier('all'))));
+    const allProp = t.objectProperty(t.identifier('all'), allArrowFn);
+    addJSDocComment(allProp, [`Invalidate all ${singularName} queries`]);
+    innerProperties.push(allProp);
+    // lists property
+    let listsProp;
+    if (hasParent) {
+        const scopeTypeName = `${typeName}Scope`;
+        const scopeParam = typedParam('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const listsArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), scopeParam], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('lists')), [t.identifier('scope')])));
+        listsProp = t.objectProperty(t.identifier('lists'), listsArrowFn);
+    }
+    else {
+        const listsArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef())], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('lists')), [])));
+        listsProp = t.objectProperty(t.identifier('lists'), listsArrowFn);
+    }
+    addJSDocComment(listsProp, [`Invalidate ${singularName} list queries`]);
+    innerProperties.push(listsProp);
+    // detail property
+    let detailProp;
+    if (hasParent) {
+        const scopeTypeName = `${typeName}Scope`;
+        const scopeParam = typedParam('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const detailArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), typedParam('id', stringOrNumberType()), scopeParam], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id'), t.identifier('scope')])));
+        detailProp = t.objectProperty(t.identifier('detail'), detailArrowFn);
+    }
+    else {
+        const detailArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), typedParam('id', stringOrNumberType())], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id')])));
+        detailProp = t.objectProperty(t.identifier('detail'), detailArrowFn);
+    }
+    addJSDocComment(detailProp, [`Invalidate a specific ${singularName}`]);
+    innerProperties.push(detailProp);
+    // withChildren property (cascade)
+    if (hasDescendants) {
+        const cascadeStatements = [];
+        // Comment: Invalidate this entity
+        const selfDetailStmt = t.expressionStatement(invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id')])));
+        addLineComment(selfDetailStmt, `Invalidate this ${singularName}`);
+        cascadeStatements.push(selfDetailStmt);
+        cascadeStatements.push(t.expressionStatement(invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('lists')), []))));
+        // Comment: Cascade to child entities
+        let firstCascade = true;
+        for (const descendant of descendants) {
+            const descendantTable = allTables.find((tbl) => getTableNames(tbl).typeName.toLowerCase() === descendant);
+            if (descendantTable) {
+                const { typeName: descTypeName } = getTableNames(descendantTable);
+                const descRel = relationships[descendant];
+                if (descRel) {
+                    let fkField = null;
+                    if (descRel.parent.toLowerCase() === entityKey) {
+                        fkField = descRel.foreignKey;
+                    }
+                    else if (descRel.ancestors?.includes(typeName.toLowerCase())) {
+                        fkField = `${lcFirst(typeName)}Id`;
+                    }
+                    const descKeysName = `${lcFirst(descTypeName)}Keys`;
+                    let cascadeStmt;
+                    if (fkField) {
+                        cascadeStmt = t.expressionStatement(invalidateCall(t.callExpression(t.memberExpression(t.identifier(descKeysName), t.identifier(`by${ucFirst(typeName)}`)), [t.identifier('id')])));
+                    }
+                    else {
+                        cascadeStmt = t.expressionStatement(invalidateCall(t.memberExpression(t.identifier(descKeysName), t.identifier('all'))));
+                    }
+                    if (firstCascade) {
+                        addLineComment(cascadeStmt, 'Cascade to child entities');
+                        firstCascade = false;
+                    }
+                    cascadeStatements.push(cascadeStmt);
+                }
+            }
+        }
+        const withChildrenArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), typedParam('id', stringOrNumberType())], t.blockStatement(cascadeStatements));
+        const withChildrenProp = t.objectProperty(t.identifier('withChildren'), withChildrenArrowFn);
+        addJSDocComment(withChildrenProp, [
+            `Invalidate ${singularName} and all child entities`,
+            `Cascades to: ${descendants.join(', ')}`,
+        ]);
+        innerProperties.push(withChildrenProp);
+    }
+    const entityProp = t.objectProperty(t.identifier(singularName), t.objectExpression(innerProperties));
+    addJSDocComment(entityProp, [`Invalidate ${singularName} queries`]);
+    return entityProp;
+}
+/**
+ * Build the remove object property for a single entity
+ */
+function buildEntityRemoveProperty(table, relationships) {
+    const { typeName, singularName } = getTableNames(table);
+    const keysName = `${lcFirst(typeName)}Keys`;
+    const relationship = relationships[typeName.toLowerCase()];
+    // Helper types
+    const queryClientTypeRef = () => t.tsTypeReference(t.identifier('QueryClient'));
+    const stringOrNumberType = () => t.tsUnionType([t.tsStringKeyword(), t.tsNumberKeyword()]);
+    // Helper to create queryClient.removeQueries({ queryKey: ... })
+    const removeCall = (queryKeyExpr) => t.callExpression(t.memberExpression(t.identifier('queryClient'), t.identifier('removeQueries')), [t.objectExpression([t.objectProperty(t.identifier('queryKey'), queryKeyExpr)])]);
+    let removeProp;
+    if (relationship) {
+        const scopeTypeName = `${typeName}Scope`;
+        const scopeParam = typedParam('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const removeArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), typedParam('id', stringOrNumberType()), scopeParam], t.blockStatement([
+            t.expressionStatement(removeCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id'), t.identifier('scope')])))
+        ]));
+        removeProp = t.objectProperty(t.identifier(singularName), removeArrowFn);
+    }
+    else {
+        const removeArrowFn = t.arrowFunctionExpression([typedParam('queryClient', queryClientTypeRef()), typedParam('id', stringOrNumberType())], t.blockStatement([
+            t.expressionStatement(removeCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id')])))
+        ]));
+        removeProp = t.objectProperty(t.identifier(singularName), removeArrowFn);
+    }
+    addJSDocComment(removeProp, [`Remove ${singularName} from cache`]);
+    return removeProp;
+}
+/**
+ * Generate the complete invalidation.ts file
+ */
+export function generateInvalidationFile(options) {
+    const { tables, config } = options;
+    const { relationships, generateCascadeHelpers } = config;
+    const childrenMap = buildChildrenMap(relationships);
+    const statements = [];
+    // Import QueryClient type
+    const queryClientImport = t.importDeclaration([t.importSpecifier(t.identifier('QueryClient'), t.identifier('QueryClient'))], t.stringLiteral('@tanstack/react-query'));
+    queryClientImport.importKind = 'type';
+    statements.push(queryClientImport);
+    // Import query keys
+    const keyImports = [];
+    for (const table of tables) {
+        const { typeName } = getTableNames(table);
+        keyImports.push(`${lcFirst(typeName)}Keys`);
+    }
+    statements.push(t.importDeclaration(keyImports.map(name => t.importSpecifier(t.identifier(name), t.identifier(name))), t.stringLiteral('./query-keys')));
+    // Import scope types if needed
+    const scopeTypes = [];
+    for (const table of tables) {
+        const { typeName } = getTableNames(table);
+        if (relationships[typeName.toLowerCase()]) {
+            scopeTypes.push(`${typeName}Scope`);
+        }
+    }
+    if (scopeTypes.length > 0) {
+        const scopeImport = t.importDeclaration(scopeTypes.map(name => t.importSpecifier(t.identifier(name), t.identifier(name))), t.stringLiteral('./query-keys'));
+        scopeImport.importKind = 'type';
+        statements.push(scopeImport);
+    }
+    // Generate invalidate object
+    const invalidateProperties = [];
+    for (const table of tables) {
+        invalidateProperties.push(buildEntityInvalidateProperty(table, relationships, childrenMap, tables));
+    }
+    const invalidateDecl = t.exportNamedDeclaration(t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('invalidate'), asConst(t.objectExpression(invalidateProperties)))
+    ]));
+    // Build JSDoc for invalidate
+    const invalidateDocLines = [
+        'Type-safe query invalidation helpers',
+        '',
+        '@example',
+        '```ts',
+        '// Invalidate all user queries',
+        'invalidate.user.all(queryClient);',
+        '',
+        '// Invalidate user lists',
+        'invalidate.user.lists(queryClient);',
+        '',
+        '// Invalidate specific user',
+        'invalidate.user.detail(queryClient, userId);',
+    ];
+    if (generateCascadeHelpers && Object.keys(relationships).length > 0) {
+        invalidateDocLines.push('');
+        invalidateDocLines.push('// Cascade invalidate (entity + all children)');
+        invalidateDocLines.push('invalidate.database.withChildren(queryClient, databaseId);');
+    }
+    invalidateDocLines.push('```');
+    addJSDocComment(invalidateDecl, invalidateDocLines);
+    statements.push(invalidateDecl);
+    // Generate remove object
+    const removeProperties = [];
+    for (const table of tables) {
+        removeProperties.push(buildEntityRemoveProperty(table, relationships));
+    }
+    const removeDecl = t.exportNamedDeclaration(t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('remove'), asConst(t.objectExpression(removeProperties)))
+    ]));
+    addJSDocComment(removeDecl, [
+        'Remove queries from cache (for delete operations)',
+        '',
+        'Use these when an entity is deleted to remove it from cache',
+        'instead of just invalidating (which would trigger a refetch).',
+    ]);
+    statements.push(removeDecl);
+    // Generate code from AST
+    const code = generateCode(statements);
+    // Build final content with header and section comments
+    const header = getGeneratedFileHeader('Cache invalidation helpers');
+    const description = `// ============================================================================
+// Type-safe cache invalidation utilities
+//
+// Features:
+// - Simple invalidation helpers per entity
+// - Cascade invalidation for parent-child relationships
+// - Remove helpers for delete operations
+// ============================================================================`;
+    let content = `${header}
+
+${description}
+
+`;
+    // Insert section comments into the generated code
+    const codeLines = code.split('\n');
+    let addedInvalidationSection = false;
+    let addedRemoveSection = false;
+    for (let i = 0; i < codeLines.length; i++) {
+        const line = codeLines[i];
+        // Detect invalidation section (after imports)
+        if (!addedInvalidationSection && line.includes('* Type-safe query invalidation helpers')) {
+            content += `// ============================================================================
+// Invalidation Helpers
+// ============================================================================
+
+`;
+            addedInvalidationSection = true;
+        }
+        // Detect remove section
+        if (!addedRemoveSection && line.includes('* Remove queries from cache')) {
+            content += `
+// ============================================================================
+// Remove Helpers (for delete operations)
+// ============================================================================
+
+`;
+            addedRemoveSection = true;
+        }
+        content += line + '\n';
+    }
+    return {
+        fileName: 'invalidation.ts',
+        content,
+    };
+}

package/esm/cli/codegen/mutation-keys.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mutation key factory generator
+ *
+ * Generates centralized mutation keys for tracking in-flight mutations.
+ * Useful for:
+ * - Optimistic updates with rollback
+ * - Mutation deduplication
+ * - Tracking mutation state with useIsMutating
+ */
+import type { CleanTable, CleanOperation } from '../../types/schema';
+import type { ResolvedQueryKeyConfig } from '../../types/config';
+export interface MutationKeyGeneratorOptions {
+    tables: CleanTable[];
+    customMutations: CleanOperation[];
+    config: ResolvedQueryKeyConfig;
+}
+export interface GeneratedMutationKeysFile {
+    fileName: string;
+    content: string;
+}
+/**
+ * Generate the complete mutation-keys.ts file
+ */
+export declare function generateMutationKeysFile(options: MutationKeyGeneratorOptions): GeneratedMutationKeysFile;

package/esm/cli/codegen/mutation-keys.js

@@ -0,0 +1,211 @@
+import { getTableNames, getGeneratedFileHeader, lcFirst } from './utils';
+import * as t from '@babel/types';
+import { generateCode, addJSDocComment, asConst, constArray, typedParam, } from './babel-ast';
+/**
+ * Generate mutation keys declaration for a single table entity
+ */
+function generateEntityMutationKeysDeclaration(table, relationships) {
+    const { typeName, singularName } = getTableNames(table);
+    const entityKey = typeName.toLowerCase();
+    const keysName = `${lcFirst(typeName)}MutationKeys`;
+    const relationship = relationships[entityKey];
+    const properties = [];
+    // all property
+    const allProp = t.objectProperty(t.identifier('all'), constArray([t.stringLiteral('mutation'), t.stringLiteral(entityKey)]));
+    addJSDocComment(allProp, [`All ${singularName} mutation keys`]);
+    properties.push(allProp);
+    // create property
+    let createProp;
+    if (relationship) {
+        const fkParam = t.identifier(relationship.foreignKey);
+        fkParam.optional = true;
+        fkParam.typeAnnotation = t.tsTypeAnnotation(t.tsStringKeyword());
+        const arrowFn = t.arrowFunctionExpression([fkParam], t.conditionalExpression(t.identifier(relationship.foreignKey), constArray([
+            t.stringLiteral('mutation'),
+            t.stringLiteral(entityKey),
+            t.stringLiteral('create'),
+            t.objectExpression([
+                t.objectProperty(t.identifier(relationship.foreignKey), t.identifier(relationship.foreignKey), false, true)
+            ]),
+        ]), constArray([
+            t.stringLiteral('mutation'),
+            t.stringLiteral(entityKey),
+            t.stringLiteral('create'),
+        ])));
+        createProp = t.objectProperty(t.identifier('create'), arrowFn);
+    }
+    else {
+        const arrowFn = t.arrowFunctionExpression([], constArray([
+            t.stringLiteral('mutation'),
+            t.stringLiteral(entityKey),
+            t.stringLiteral('create'),
+        ]));
+        createProp = t.objectProperty(t.identifier('create'), arrowFn);
+    }
+    addJSDocComment(createProp, [`Create ${singularName} mutation key`]);
+    properties.push(createProp);
+    // update property
+    const updateArrowFn = t.arrowFunctionExpression([typedParam('id', t.tsUnionType([t.tsStringKeyword(), t.tsNumberKeyword()]))], constArray([
+        t.stringLiteral('mutation'),
+        t.stringLiteral(entityKey),
+        t.stringLiteral('update'),
+        t.identifier('id'),
+    ]));
+    const updateProp = t.objectProperty(t.identifier('update'), updateArrowFn);
+    addJSDocComment(updateProp, [`Update ${singularName} mutation key`]);
+    properties.push(updateProp);
+    // delete property
+    const deleteArrowFn = t.arrowFunctionExpression([typedParam('id', t.tsUnionType([t.tsStringKeyword(), t.tsNumberKeyword()]))], constArray([
+        t.stringLiteral('mutation'),
+        t.stringLiteral(entityKey),
+        t.stringLiteral('delete'),
+        t.identifier('id'),
+    ]));
+    const deleteProp = t.objectProperty(t.identifier('delete'), deleteArrowFn);
+    addJSDocComment(deleteProp, [`Delete ${singularName} mutation key`]);
+    properties.push(deleteProp);
+    return t.exportNamedDeclaration(t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier(keysName), asConst(t.objectExpression(properties)))
+    ]));
+}
+/**
+ * Generate custom mutation keys declaration
+ */
+function generateCustomMutationKeysDeclaration(operations) {
+    if (operations.length === 0)
+        return null;
+    const properties = [];
+    for (const op of operations) {
+        const hasArgs = op.args.length > 0;
+        let prop;
+        if (hasArgs) {
+            const identifierParam = t.identifier('identifier');
+            identifierParam.optional = true;
+            identifierParam.typeAnnotation = t.tsTypeAnnotation(t.tsStringKeyword());
+            const arrowFn = t.arrowFunctionExpression([identifierParam], t.conditionalExpression(t.identifier('identifier'), constArray([
+                t.stringLiteral('mutation'),
+                t.stringLiteral(op.name),
+                t.identifier('identifier'),
+            ]), constArray([t.stringLiteral('mutation'), t.stringLiteral(op.name)])));
+            prop = t.objectProperty(t.identifier(op.name), arrowFn);
+        }
+        else {
+            const arrowFn = t.arrowFunctionExpression([], constArray([t.stringLiteral('mutation'), t.stringLiteral(op.name)]));
+            prop = t.objectProperty(t.identifier(op.name), arrowFn);
+        }
+        addJSDocComment(prop, [`Mutation key for ${op.name}`]);
+        properties.push(prop);
+    }
+    return t.exportNamedDeclaration(t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('customMutationKeys'), asConst(t.objectExpression(properties)))
+    ]));
+}
+/**
+ * Generate the unified mutation keys store declaration
+ */
+function generateUnifiedMutationStoreDeclaration(tables, hasCustomMutations) {
+    const properties = [];
+    for (const table of tables) {
+        const { typeName } = getTableNames(table);
+        const keysName = `${lcFirst(typeName)}MutationKeys`;
+        properties.push(t.objectProperty(t.identifier(lcFirst(typeName)), t.identifier(keysName)));
+    }
+    if (hasCustomMutations) {
+        properties.push(t.objectProperty(t.identifier('custom'), t.identifier('customMutationKeys')));
+    }
+    const decl = t.exportNamedDeclaration(t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('mutationKeys'), asConst(t.objectExpression(properties)))
+    ]));
+    addJSDocComment(decl, [
+        'Unified mutation key store',
+        '',
+        'Use this for tracking in-flight mutations with useIsMutating.',
+        '',
+        '@example',
+        '```ts',
+        "import { useIsMutating } from '@tanstack/react-query';",
+        "import { mutationKeys } from './generated';",
+        '',
+        '// Check if any user mutations are in progress',
+        'const isMutatingUser = useIsMutating({ mutationKey: mutationKeys.user.all });',
+        '',
+        '// Check if a specific user is being updated',
+        'const isUpdating = useIsMutating({ mutationKey: mutationKeys.user.update(userId) });',
+        '```',
+    ]);
+    return decl;
+}
+/**
+ * Generate the complete mutation-keys.ts file
+ */
+export function generateMutationKeysFile(options) {
+    const { tables, customMutations, config } = options;
+    const { relationships } = config;
+    const statements = [];
+    // Generate entity mutation keys
+    for (const table of tables) {
+        statements.push(generateEntityMutationKeysDeclaration(table, relationships));
+    }
+    // Generate custom mutation keys
+    const mutationOperations = customMutations.filter((op) => op.kind === 'mutation');
+    const customKeysDecl = generateCustomMutationKeysDeclaration(mutationOperations);
+    if (customKeysDecl) {
+        statements.push(customKeysDecl);
+    }
+    // Generate unified store
+    statements.push(generateUnifiedMutationStoreDeclaration(tables, mutationOperations.length > 0));
+    // Generate code from AST
+    const code = generateCode(statements);
+    // Build final content with header and section comments
+    const header = getGeneratedFileHeader('Centralized mutation key factory');
+    const description = `// ============================================================================
+// Mutation keys for tracking in-flight mutations
+//
+// Benefits:
+// - Track mutation state with useIsMutating
+// - Implement optimistic updates with proper rollback
+// - Deduplicate identical mutations
+// - Coordinate related mutations
+// ============================================================================`;
+    let content = `${header}
+
+${description}
+
+// ============================================================================
+// Entity Mutation Keys
+// ============================================================================
+
+`;
+    // Insert section comments into the generated code
+    const codeLines = code.split('\n');
+    let addedCustomSection = false;
+    let addedUnifiedSection = false;
+    for (let i = 0; i < codeLines.length; i++) {
+        const line = codeLines[i];
+        // Detect custom mutation keys section
+        if (!addedCustomSection && line.startsWith('export const customMutationKeys')) {
+            content += `
+// ============================================================================
+// Custom Mutation Keys
+// ============================================================================
+
+`;
+            addedCustomSection = true;
+        }
+        // Detect unified store section
+        if (!addedUnifiedSection && line.includes('* Unified mutation key store')) {
+            content += `
+// ============================================================================
+// Unified Mutation Key Store
+// ============================================================================
+
+`;
+            addedUnifiedSection = true;
+        }
+        content += line + '\n';
+    }
+    return {
+        fileName: 'mutation-keys.ts',
+        content,
+    };
+}