@constructive-io/graphql-codegen 2.23.3 → 2.24.1

package/cli/codegen/gql-ast.js

@@ -80,22 +80,39 @@ function buildListQueryAST(config) {
     const { table } = config;
     const queryName = (0, utils_1.getAllRowsQueryName)(table);
     const filterType = (0, utils_1.getFilterTypeName)(table);
+    const conditionType = (0, utils_1.getConditionTypeName)(table);
     const orderByType = (0, utils_1.getOrderByTypeName)(table);
     const scalarFields = (0, utils_1.getScalarFields)(table);
-    // Variable definitions
+    // Variable definitions - all pagination arguments from PostGraphile
     const variableDefinitions = [
         t.variableDefinition({
             variable: t.variable({ name: 'first' }),
             type: t.namedType({ type: 'Int' }),
         }),
+        t.variableDefinition({
+            variable: t.variable({ name: 'last' }),
+            type: t.namedType({ type: 'Int' }),
+        }),
         t.variableDefinition({
             variable: t.variable({ name: 'offset' }),
             type: t.namedType({ type: 'Int' }),
         }),
+        t.variableDefinition({
+            variable: t.variable({ name: 'before' }),
+            type: t.namedType({ type: 'Cursor' }),
+        }),
+        t.variableDefinition({
+            variable: t.variable({ name: 'after' }),
+            type: t.namedType({ type: 'Cursor' }),
+        }),
         t.variableDefinition({
             variable: t.variable({ name: 'filter' }),
             type: t.namedType({ type: filterType }),
         }),
+        t.variableDefinition({
+            variable: t.variable({ name: 'condition' }),
+            type: t.namedType({ type: conditionType }),
+        }),
         t.variableDefinition({
             variable: t.variable({ name: 'orderBy' }),
             type: t.listType({
@@ -106,8 +123,12 @@ function buildListQueryAST(config) {
     // Query arguments
     const args = [
         t.argument({ name: 'first', value: t.variable({ name: 'first' }) }),
+        t.argument({ name: 'last', value: t.variable({ name: 'last' }) }),
         t.argument({ name: 'offset', value: t.variable({ name: 'offset' }) }),
+        t.argument({ name: 'before', value: t.variable({ name: 'before' }) }),
+        t.argument({ name: 'after', value: t.variable({ name: 'after' }) }),
         t.argument({ name: 'filter', value: t.variable({ name: 'filter' }) }),
+        t.argument({ name: 'condition', value: t.variable({ name: 'condition' }) }),
         t.argument({ name: 'orderBy', value: t.variable({ name: 'orderBy' }) }),
     ];
     // Field selections

package/cli/codegen/index.d.ts

@@ -69,3 +69,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/cli/codegen/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateCustomMutationsBarrel = exports.generateCustomQueriesBarrel = exports.generateMainBarrel = exports.generateMutationsBarrel = exports.generateQueriesBarrel = exports.generateCustomMutationHook = exports.generateAllCustomMutationHooks = exports.generateCustomQueryHook = exports.generateAllCustomQueryHooks = exports.generateDeleteMutationHook = exports.generateUpdateMutationHook = exports.generateCreateMutationHook = exports.generateAllMutationHooks = exports.generateSingleQueryHook = exports.generateListQueryHook = exports.generateAllQueryHooks = exports.generateTypesFile = exports.generateClientFile = void 0;
+exports.generateInvalidationFile = exports.generateMutationKeysFile = exports.generateQueryKeysFile = exports.generateCustomMutationsBarrel = exports.generateCustomQueriesBarrel = exports.generateMainBarrel = exports.generateMutationsBarrel = exports.generateQueriesBarrel = exports.generateCustomMutationHook = exports.generateAllCustomMutationHooks = exports.generateCustomQueryHook = exports.generateAllCustomQueryHooks = exports.generateDeleteMutationHook = exports.generateUpdateMutationHook = exports.generateCreateMutationHook = exports.generateAllMutationHooks = exports.generateSingleQueryHook = exports.generateListQueryHook = exports.generateAllQueryHooks = exports.generateTypesFile = exports.generateClientFile = void 0;
 exports.generateAllFiles = generateAllFiles;
 exports.generate = generate;
+const config_1 = require("../../types/config");
 const client_1 = require("./client");
 const types_1 = require("./types");
 const schema_types_generator_1 = require("./schema-types-generator");
@@ -10,6 +11,9 @@ const queries_1 = require("./queries");
 const mutations_1 = require("./mutations");
 const custom_queries_1 = require("./custom-queries");
 const custom_mutations_1 = require("./custom-mutations");
+const query_keys_1 = require("./query-keys");
+const mutation_keys_1 = require("./mutation-keys");
+const invalidation_1 = require("./invalidation");
 const barrel_1 = require("./barrel");
 const utils_1 = require("./utils");
 // ============================================================================
@@ -31,6 +35,10 @@ 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 ?? config_1.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',
@@ -64,8 +72,53 @@ function generate(options) {
             enumsFromSchemaTypes: generatedEnumNames,
         }),
     });
+    // 3b. Generate centralized query keys (query-keys.ts)
+    let hasQueryKeys = false;
+    if (useCentralizedKeys) {
+        const queryKeysResult = (0, query_keys_1.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 = (0, mutation_keys_1.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 = (0, invalidation_1.generateInvalidationFile)({
+            tables,
+            config: queryKeyConfig,
+        });
+        files.push({
+            path: invalidationResult.fileName,
+            content: invalidationResult.content,
+        });
+        hasInvalidation = true;
+    }
     // 4. Generate table-based query hooks (queries/*.ts)
-    const queryHooks = (0, queries_1.generateAllQueryHooks)(tables, { reactQueryEnabled });
+    const queryHooks = (0, queries_1.generateAllQueryHooks)(tables, {
+        reactQueryEnabled,
+        useCentralizedKeys,
+        hasRelationships,
+    });
     for (const hook of queryHooks) {
         files.push({
             path: `queries/${hook.fileName}`,
@@ -82,6 +135,7 @@ function generate(options) {
             skipQueryField,
             reactQueryEnabled,
             tableTypeNames,
+            useCentralizedKeys,
         });
         for (const hook of customQueryHooks) {
             files.push({
@@ -101,6 +155,9 @@ function generate(options) {
     const mutationHooks = (0, mutations_1.generateAllMutationHooks)(tables, {
         reactQueryEnabled,
         enumsFromSchemaTypes: generatedEnumNames,
+        useCentralizedKeys,
+        hasRelationships,
+        tableTypeNames,
     });
     for (const hook of mutationHooks) {
         files.push({
@@ -118,6 +175,7 @@ function generate(options) {
             skipQueryField,
             reactQueryEnabled,
             tableTypeNames,
+            useCentralizedKeys,
         });
         for (const hook of customMutationHooks) {
             files.push({
@@ -140,7 +198,13 @@ function generate(options) {
     // 9. Generate main index.ts barrel (with schema-types if present)
     files.push({
         path: 'index.ts',
-        content: (0, barrel_1.generateMainBarrel)(tables, { hasSchemaTypes, hasMutations }),
+        content: (0, barrel_1.generateMainBarrel)(tables, {
+            hasSchemaTypes,
+            hasMutations,
+            hasQueryKeys,
+            hasMutationKeys,
+            hasInvalidation,
+        }),
     });
     return {
         files,
@@ -182,3 +246,9 @@ Object.defineProperty(exports, "generateMutationsBarrel", { enumerable: true, ge
 Object.defineProperty(exports, "generateMainBarrel", { enumerable: true, get: function () { return barrel_2.generateMainBarrel; } });
 Object.defineProperty(exports, "generateCustomQueriesBarrel", { enumerable: true, get: function () { return barrel_2.generateCustomQueriesBarrel; } });
 Object.defineProperty(exports, "generateCustomMutationsBarrel", { enumerable: true, get: function () { return barrel_2.generateCustomMutationsBarrel; } });
+var query_keys_2 = require("./query-keys");
+Object.defineProperty(exports, "generateQueryKeysFile", { enumerable: true, get: function () { return query_keys_2.generateQueryKeysFile; } });
+var mutation_keys_2 = require("./mutation-keys");
+Object.defineProperty(exports, "generateMutationKeysFile", { enumerable: true, get: function () { return mutation_keys_2.generateMutationKeysFile; } });
+var invalidation_2 = require("./invalidation");
+Object.defineProperty(exports, "generateInvalidationFile", { enumerable: true, get: function () { return invalidation_2.generateInvalidationFile; } });

package/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/cli/codegen/invalidation.js

@@ -0,0 +1,327 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateInvalidationFile = generateInvalidationFile;
+const utils_1 = require("./utils");
+const t = __importStar(require("@babel/types"));
+const babel_ast_1 = require("./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 } = (0, utils_1.getTableNames)(table);
+    const entityKey = typeName.toLowerCase();
+    const keysName = `${(0, utils_1.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([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef())], invalidateCall(t.memberExpression(t.identifier(keysName), t.identifier('all'))));
+    const allProp = t.objectProperty(t.identifier('all'), allArrowFn);
+    (0, babel_ast_1.addJSDocComment)(allProp, [`Invalidate all ${singularName} queries`]);
+    innerProperties.push(allProp);
+    // lists property
+    let listsProp;
+    if (hasParent) {
+        const scopeTypeName = `${typeName}Scope`;
+        const scopeParam = (0, babel_ast_1.typedParam)('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const listsArrowFn = t.arrowFunctionExpression([(0, babel_ast_1.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([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef())], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('lists')), [])));
+        listsProp = t.objectProperty(t.identifier('lists'), listsArrowFn);
+    }
+    (0, babel_ast_1.addJSDocComment)(listsProp, [`Invalidate ${singularName} list queries`]);
+    innerProperties.push(listsProp);
+    // detail property
+    let detailProp;
+    if (hasParent) {
+        const scopeTypeName = `${typeName}Scope`;
+        const scopeParam = (0, babel_ast_1.typedParam)('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const detailArrowFn = t.arrowFunctionExpression([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef()), (0, babel_ast_1.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([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef()), (0, babel_ast_1.typedParam)('id', stringOrNumberType())], invalidateCall(t.callExpression(t.memberExpression(t.identifier(keysName), t.identifier('detail')), [t.identifier('id')])));
+        detailProp = t.objectProperty(t.identifier('detail'), detailArrowFn);
+    }
+    (0, babel_ast_1.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')])));
+        (0, babel_ast_1.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) => (0, utils_1.getTableNames)(tbl).typeName.toLowerCase() === descendant);
+            if (descendantTable) {
+                const { typeName: descTypeName } = (0, utils_1.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 = `${(0, utils_1.lcFirst)(typeName)}Id`;
+                    }
+                    const descKeysName = `${(0, utils_1.lcFirst)(descTypeName)}Keys`;
+                    let cascadeStmt;
+                    if (fkField) {
+                        cascadeStmt = t.expressionStatement(invalidateCall(t.callExpression(t.memberExpression(t.identifier(descKeysName), t.identifier(`by${(0, utils_1.ucFirst)(typeName)}`)), [t.identifier('id')])));
+                    }
+                    else {
+                        cascadeStmt = t.expressionStatement(invalidateCall(t.memberExpression(t.identifier(descKeysName), t.identifier('all'))));
+                    }
+                    if (firstCascade) {
+                        (0, babel_ast_1.addLineComment)(cascadeStmt, 'Cascade to child entities');
+                        firstCascade = false;
+                    }
+                    cascadeStatements.push(cascadeStmt);
+                }
+            }
+        }
+        const withChildrenArrowFn = t.arrowFunctionExpression([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef()), (0, babel_ast_1.typedParam)('id', stringOrNumberType())], t.blockStatement(cascadeStatements));
+        const withChildrenProp = t.objectProperty(t.identifier('withChildren'), withChildrenArrowFn);
+        (0, babel_ast_1.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));
+    (0, babel_ast_1.addJSDocComment)(entityProp, [`Invalidate ${singularName} queries`]);
+    return entityProp;
+}
+/**
+ * Build the remove object property for a single entity
+ */
+function buildEntityRemoveProperty(table, relationships) {
+    const { typeName, singularName } = (0, utils_1.getTableNames)(table);
+    const keysName = `${(0, utils_1.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 = (0, babel_ast_1.typedParam)('scope', t.tsTypeReference(t.identifier(scopeTypeName)), true);
+        const removeArrowFn = t.arrowFunctionExpression([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef()), (0, babel_ast_1.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([(0, babel_ast_1.typedParam)('queryClient', queryClientTypeRef()), (0, babel_ast_1.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);
+    }
+    (0, babel_ast_1.addJSDocComment)(removeProp, [`Remove ${singularName} from cache`]);
+    return removeProp;
+}
+/**
+ * Generate the complete invalidation.ts file
+ */
+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 } = (0, utils_1.getTableNames)(table);
+        keyImports.push(`${(0, utils_1.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 } = (0, utils_1.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'), (0, babel_ast_1.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('```');
+    (0, babel_ast_1.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'), (0, babel_ast_1.asConst)(t.objectExpression(removeProperties)))
+    ]));
+    (0, babel_ast_1.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 = (0, babel_ast_1.generateCode)(statements);
+    // Build final content with header and section comments
+    const header = (0, utils_1.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/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;