@constructive-io/graphql-codegen 2.19.0 → 2.20.1

package/esm/cli/codegen/ts-ast.js

@@ -0,0 +1,260 @@
+/**
+ * TypeScript AST builders using ts-morph
+ *
+ * Provides utilities for generating TypeScript code via AST manipulation
+ * instead of string concatenation.
+ */
+import { Project, StructureKind, VariableDeclarationKind, ScriptTarget, ModuleKind, } from 'ts-morph';
+// ============================================================================
+// Project management
+// ============================================================================
+/**
+ * Create a new ts-morph project for code generation
+ */
+export function createProject() {
+    return new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: {
+            declaration: true,
+            strict: true,
+            target: ScriptTarget.ESNext,
+            module: ModuleKind.ESNext,
+        },
+    });
+}
+/**
+ * Create a source file in the project
+ */
+export function createSourceFile(project, fileName) {
+    return project.createSourceFile(fileName, '', { overwrite: true });
+}
+/**
+ * Get formatted output from source file
+ */
+export function getFormattedOutput(sourceFile) {
+    sourceFile.formatText({
+        indentSize: 2,
+        convertTabsToSpaces: true,
+    });
+    return sourceFile.getFullText();
+}
+/**
+ * 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 function getMinimalFormattedOutput(sourceFile) {
+    let text = sourceFile.getFullText();
+    // Process each line to fix indentation
+    // ts-morph uses inconsistent indentation for type alias bodies
+    // We halve all indentation: 4->2, 6->3 (rounds to 2), 8->4, etc.
+    text = text.split('\n').map(line => {
+        // Match leading whitespace
+        const match = line.match(/^(\s*)/);
+        if (!match)
+            return line;
+        const spaces = match[1].length;
+        const content = line.slice(spaces);
+        // Skip empty lines
+        if (content === '')
+            return line;
+        // No indentation - keep as-is
+        if (spaces === 0)
+            return line;
+        // Halve the indentation (minimum 0)
+        const newSpaces = Math.floor(spaces / 2);
+        return ' '.repeat(newSpaces) + content;
+    }).join('\n');
+    // Ensure blank line after section comment blocks
+    text = text.replace(/(\/\/ =+\n\/\/ .+\n\/\/ =+)\n(export|\/\/)/g, '$1\n\n$2');
+    // Add blank line between consecutive export declarations (type aliases, interfaces)
+    // Pattern: "}\nexport" or ";\nexport" should become "}\n\nexport" or ";\n\nexport"
+    text = text.replace(/(\}|\;)\n(export )/g, '$1\n\n$2');
+    // Remove trailing extra blank lines at end of file
+    text = text.replace(/\n\n+$/, '\n');
+    return text;
+}
+// ============================================================================
+// Comment helpers
+// ============================================================================
+/**
+ * Create a file header comment
+ */
+export function createFileHeader(description) {
+    return [
+        '/**',
+        ` * ${description}`,
+        ' * @generated by @constructive-io/graphql-codegen',
+        ' * DO NOT EDIT - changes will be overwritten',
+        ' */',
+    ].join('\n');
+}
+/**
+ * Create JSDoc comment for a declaration
+ */
+export function createJsDoc(lines) {
+    if (lines.length === 1) {
+        return `/** ${lines[0]} */`;
+    }
+    return ['/**', ...lines.map((l) => ` * ${l}`), ' */'].join('\n');
+}
+/**
+ * Create import declaration structure
+ */
+export function createImport(spec) {
+    const namedImports = [];
+    if (spec.namedImports) {
+        namedImports.push(...spec.namedImports.map((name) => ({ name })));
+    }
+    if (spec.typeOnlyNamedImports) {
+        namedImports.push(...spec.typeOnlyNamedImports.map((name) => ({ name, isTypeOnly: true })));
+    }
+    return {
+        kind: StructureKind.ImportDeclaration,
+        moduleSpecifier: spec.moduleSpecifier,
+        defaultImport: spec.defaultImport,
+        namedImports: namedImports.length > 0 ? namedImports : undefined,
+    };
+}
+/**
+ * Create interface declaration structure
+ */
+export function createInterface(name, properties, options) {
+    return {
+        kind: StructureKind.Interface,
+        name,
+        isExported: options?.isExported ?? true,
+        extends: options?.extends,
+        docs: options?.docs ? [{ description: options.docs.join('\n') }] : undefined,
+        properties: properties.map((prop) => ({
+            kind: StructureKind.PropertySignature,
+            name: prop.name,
+            type: prop.type,
+            hasQuestionToken: prop.optional,
+            docs: prop.docs ? [{ description: prop.docs.join('\n') }] : undefined,
+        })),
+    };
+}
+/**
+ * Create filter interface with standard PostGraphile operators
+ */
+export function createFilterInterface(name, fieldFilters) {
+    const properties = [
+        ...fieldFilters.map((f) => ({
+            name: f.fieldName,
+            type: f.filterType,
+            optional: true,
+        })),
+        { name: 'and', type: `${name}[]`, optional: true, docs: ['Logical AND'] },
+        { name: 'or', type: `${name}[]`, optional: true, docs: ['Logical OR'] },
+        { name: 'not', type: name, optional: true, docs: ['Logical NOT'] },
+    ];
+    return createInterface(name, properties);
+}
+// ============================================================================
+// Type alias builders
+// ============================================================================
+/**
+ * Create type alias declaration structure
+ */
+export function createTypeAlias(name, type, options) {
+    return {
+        kind: StructureKind.TypeAlias,
+        name,
+        type,
+        isExported: options?.isExported ?? true,
+        docs: options?.docs ? [{ description: options.docs.join('\n') }] : undefined,
+    };
+}
+/**
+ * Create union type from string literals
+ */
+export function createUnionType(values) {
+    return values.map((v) => `'${v}'`).join(' | ');
+}
+// ============================================================================
+// Variable/constant builders
+// ============================================================================
+/**
+ * Create const variable statement structure
+ */
+export function createConst(name, initializer, options) {
+    return {
+        kind: StructureKind.VariableStatement,
+        declarationKind: VariableDeclarationKind.Const,
+        isExported: options?.isExported ?? true,
+        docs: options?.docs ? [{ description: options.docs.join('\n') }] : undefined,
+        declarations: [
+            {
+                name,
+                type: options?.type,
+                initializer,
+            },
+        ],
+    };
+}
+/**
+ * Create a template literal string (for GraphQL documents)
+ */
+export function createTemplateLiteral(content) {
+    return '`\n' + content + '\n`';
+}
+/**
+ * Create function declaration structure
+ */
+export function createFunction(name, parameters, returnType, body, options) {
+    return {
+        kind: StructureKind.Function,
+        name,
+        isExported: options?.isExported ?? true,
+        isAsync: options?.isAsync,
+        parameters: parameters.map((p) => ({
+            name: p.name,
+            type: p.type,
+            hasQuestionToken: p.optional,
+            initializer: p.initializer,
+        })),
+        returnType,
+        statements: body,
+    };
+}
+// ============================================================================
+// Export builders
+// ============================================================================
+/**
+ * Create re-export statement
+ */
+export function createReExport(names, moduleSpecifier, isTypeOnly = false) {
+    const typePrefix = isTypeOnly ? 'type ' : '';
+    return `export ${typePrefix}{ ${names.join(', ')} } from '${moduleSpecifier}';`;
+}
+/**
+ * Create barrel export statement
+ */
+export function createBarrelExport(moduleSpecifier) {
+    return `export * from '${moduleSpecifier}';`;
+}
+// ============================================================================
+// Section comment helpers
+// ============================================================================
+/**
+ * Create a section divider comment for generated code
+ */
+export function createSectionComment(title) {
+    return [
+        '// ============================================================================',
+        `// ${title}`,
+        '// ============================================================================',
+    ].join('\n');
+}
+/**
+ * Add a section comment to source file with proper spacing
+ */
+export function addSectionComment(sourceFile, title) {
+    sourceFile.addStatements(`\n${createSectionComment(title)}\n\n`);
+}

package/esm/cli/codegen/type-resolver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Type Resolver - Convert GraphQL types to TypeScript
+ *
+ * Utilities for converting CleanTypeRef and other GraphQL types
+ * into TypeScript type strings and interface definitions.
+ */
+import type { CleanTypeRef, CleanArgument, CleanObjectField } from '../../types/schema';
+import type { InterfaceProperty } from './ts-ast';
+/**
+ * Convert a GraphQL scalar type to TypeScript type
+ */
+export declare function scalarToTsType(scalarName: string): string;
+/**
+ * Convert a CleanTypeRef to a TypeScript type string
+ * Handles nested LIST and NON_NULL wrappers
+ */
+export declare function typeRefToTsType(typeRef: CleanTypeRef): string;
+/**
+ * Convert a CleanTypeRef to a nullable TypeScript type string
+ * (for optional fields that can be null)
+ */
+export declare function typeRefToNullableTsType(typeRef: CleanTypeRef): string;
+/**
+ * Check if a type reference is required (wrapped in NON_NULL)
+ */
+export declare function isTypeRequired(typeRef: CleanTypeRef): boolean;
+/**
+ * Check if a type reference is a list
+ */
+export declare function isTypeList(typeRef: CleanTypeRef): boolean;
+/**
+ * Get the base type name from a type reference (unwrapping wrappers)
+ */
+export declare function getTypeBaseName(typeRef: CleanTypeRef): string | null;
+/**
+ * Get the base type kind (unwrapping LIST and NON_NULL)
+ */
+export declare function getBaseTypeKind(typeRef: CleanTypeRef): CleanTypeRef['kind'];
+/**
+ * Convert CleanArgument to InterfaceProperty for ts-morph
+ */
+export declare function argumentToInterfaceProperty(arg: CleanArgument): InterfaceProperty;
+/**
+ * Convert CleanObjectField to InterfaceProperty for ts-morph
+ */
+export declare function fieldToInterfaceProperty(field: CleanObjectField): InterfaceProperty;
+/**
+ * Convert an array of CleanArguments to InterfaceProperty array
+ */
+export declare function argumentsToInterfaceProperties(args: CleanArgument[]): InterfaceProperty[];
+/**
+ * Convert an array of CleanObjectFields to InterfaceProperty array
+ */
+export declare function fieldsToInterfaceProperties(fields: CleanObjectField[]): InterfaceProperty[];
+/**
+ * Check if a field should be skipped in selections
+ */
+export declare function shouldSkipField(fieldName: string, skipQueryField: boolean): boolean;
+/**
+ * Filter fields to only include selectable scalar and object fields
+ */
+export declare function getSelectableFields(fields: CleanObjectField[] | undefined, skipQueryField: boolean, maxDepth?: number, currentDepth?: number): CleanObjectField[];
+/**
+ * Convert operation name to PascalCase for type names
+ */
+export declare function operationNameToPascal(name: string): string;
+/**
+ * Generate variables type name for an operation
+ * e.g., "login" -> "LoginMutationVariables"
+ */
+export declare function getOperationVariablesTypeName(operationName: string, kind: 'query' | 'mutation'): string;
+/**
+ * Generate result type name for an operation
+ * e.g., "login" -> "LoginMutationResult"
+ */
+export declare function getOperationResultTypeName(operationName: string, kind: 'query' | 'mutation'): string;
+/**
+ * Generate hook name for an operation
+ * e.g., "login" -> "useLoginMutation", "currentUser" -> "useCurrentUserQuery"
+ */
+export declare function getOperationHookName(operationName: string, kind: 'query' | 'mutation'): string;
+/**
+ * Generate file name for an operation hook
+ * e.g., "login" -> "useLoginMutation.ts"
+ */
+export declare function getOperationFileName(operationName: string, kind: 'query' | 'mutation'): string;
+/**
+ * Generate query key factory name
+ * e.g., "currentUser" -> "currentUserQueryKey"
+ */
+export declare function getQueryKeyName(operationName: string): string;
+/**
+ * Generate GraphQL document constant name
+ * e.g., "login" -> "loginMutationDocument"
+ */
+export declare function getDocumentConstName(operationName: string, kind: 'query' | 'mutation'): string;

package/esm/cli/codegen/type-resolver.js

@@ -0,0 +1,224 @@
+import { scalarToTsType as resolveScalarToTs } from './scalars';
+// ============================================================================
+// GraphQL to TypeScript Type Mapping
+// ============================================================================
+/**
+ * Convert a GraphQL scalar type to TypeScript type
+ */
+export function scalarToTsType(scalarName) {
+    return resolveScalarToTs(scalarName, { unknownScalar: 'unknown' });
+}
+// ============================================================================
+// CleanTypeRef to TypeScript
+// ============================================================================
+/**
+ * Convert a CleanTypeRef to a TypeScript type string
+ * Handles nested LIST and NON_NULL wrappers
+ */
+export function typeRefToTsType(typeRef) {
+    switch (typeRef.kind) {
+        case 'NON_NULL':
+            // Non-null wrapper - unwrap and return the inner type
+            if (typeRef.ofType) {
+                return typeRefToTsType(typeRef.ofType);
+            }
+            return 'unknown';
+        case 'LIST':
+            // List wrapper - wrap inner type in array
+            if (typeRef.ofType) {
+                const innerType = typeRefToTsType(typeRef.ofType);
+                return `${innerType}[]`;
+            }
+            return 'unknown[]';
+        case 'SCALAR':
+            // Scalar type - map to TS type
+            return scalarToTsType(typeRef.name ?? 'unknown');
+        case 'ENUM':
+            // Enum type - use the GraphQL enum name
+            return typeRef.name ?? 'string';
+        case 'OBJECT':
+        case 'INPUT_OBJECT':
+            // Object types - use the GraphQL type name
+            return typeRef.name ?? 'unknown';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Convert a CleanTypeRef to a nullable TypeScript type string
+ * (for optional fields that can be null)
+ */
+export function typeRefToNullableTsType(typeRef) {
+    const baseType = typeRefToTsType(typeRef);
+    // If the outer type is NON_NULL, it's required
+    if (typeRef.kind === 'NON_NULL') {
+        return baseType;
+    }
+    // Otherwise, it can be null
+    return `${baseType} | null`;
+}
+/**
+ * Check if a type reference is required (wrapped in NON_NULL)
+ */
+export function isTypeRequired(typeRef) {
+    return typeRef.kind === 'NON_NULL';
+}
+/**
+ * Check if a type reference is a list
+ */
+export function isTypeList(typeRef) {
+    if (typeRef.kind === 'LIST')
+        return true;
+    if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {
+        return typeRef.ofType.kind === 'LIST';
+    }
+    return false;
+}
+/**
+ * Get the base type name from a type reference (unwrapping wrappers)
+ */
+export function getTypeBaseName(typeRef) {
+    if (typeRef.name)
+        return typeRef.name;
+    if (typeRef.ofType)
+        return getTypeBaseName(typeRef.ofType);
+    return null;
+}
+/**
+ * Get the base type kind (unwrapping LIST and NON_NULL)
+ */
+export function getBaseTypeKind(typeRef) {
+    if (typeRef.kind === 'LIST' || typeRef.kind === 'NON_NULL') {
+        if (typeRef.ofType) {
+            return getBaseTypeKind(typeRef.ofType);
+        }
+    }
+    return typeRef.kind;
+}
+// ============================================================================
+// Interface Property Generation
+// ============================================================================
+/**
+ * Convert CleanArgument to InterfaceProperty for ts-morph
+ */
+export function argumentToInterfaceProperty(arg) {
+    return {
+        name: arg.name,
+        type: typeRefToTsType(arg.type),
+        optional: !isTypeRequired(arg.type),
+        docs: arg.description ? [arg.description] : undefined,
+    };
+}
+/**
+ * Convert CleanObjectField to InterfaceProperty for ts-morph
+ */
+export function fieldToInterfaceProperty(field) {
+    return {
+        name: field.name,
+        type: typeRefToNullableTsType(field.type),
+        optional: false, // Fields are always present, just potentially null
+        docs: field.description ? [field.description] : undefined,
+    };
+}
+/**
+ * Convert an array of CleanArguments to InterfaceProperty array
+ */
+export function argumentsToInterfaceProperties(args) {
+    return args.map(argumentToInterfaceProperty);
+}
+/**
+ * Convert an array of CleanObjectFields to InterfaceProperty array
+ */
+export function fieldsToInterfaceProperties(fields) {
+    return fields.map(fieldToInterfaceProperty);
+}
+// ============================================================================
+// Type Filtering
+// ============================================================================
+/**
+ * Check if a field should be skipped in selections
+ */
+export function shouldSkipField(fieldName, skipQueryField) {
+    if (skipQueryField && fieldName === 'query')
+        return true;
+    if (fieldName === 'nodeId')
+        return true;
+    if (fieldName === '__typename')
+        return true;
+    return false;
+}
+/**
+ * Filter fields to only include selectable scalar and object fields
+ */
+export function getSelectableFields(fields, skipQueryField, maxDepth = 2, currentDepth = 0) {
+    if (!fields || currentDepth >= maxDepth)
+        return [];
+    return fields.filter((field) => {
+        // Skip internal fields
+        if (shouldSkipField(field.name, skipQueryField))
+            return false;
+        // Get base type kind
+        const baseKind = getBaseTypeKind(field.type);
+        // Include scalars and enums
+        if (baseKind === 'SCALAR' || baseKind === 'ENUM')
+            return true;
+        // Include objects up to max depth
+        if (baseKind === 'OBJECT' && currentDepth < maxDepth - 1)
+            return true;
+        return false;
+    });
+}
+// ============================================================================
+// Type Name Utilities
+// ============================================================================
+/**
+ * Convert operation name to PascalCase for type names
+ */
+export function operationNameToPascal(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+/**
+ * Generate variables type name for an operation
+ * e.g., "login" -> "LoginMutationVariables"
+ */
+export function getOperationVariablesTypeName(operationName, kind) {
+    const pascal = operationNameToPascal(operationName);
+    return `${pascal}${kind === 'query' ? 'Query' : 'Mutation'}Variables`;
+}
+/**
+ * Generate result type name for an operation
+ * e.g., "login" -> "LoginMutationResult"
+ */
+export function getOperationResultTypeName(operationName, kind) {
+    const pascal = operationNameToPascal(operationName);
+    return `${pascal}${kind === 'query' ? 'Query' : 'Mutation'}Result`;
+}
+/**
+ * Generate hook name for an operation
+ * e.g., "login" -> "useLoginMutation", "currentUser" -> "useCurrentUserQuery"
+ */
+export function getOperationHookName(operationName, kind) {
+    const pascal = operationNameToPascal(operationName);
+    return `use${pascal}${kind === 'query' ? 'Query' : 'Mutation'}`;
+}
+/**
+ * Generate file name for an operation hook
+ * e.g., "login" -> "useLoginMutation.ts"
+ */
+export function getOperationFileName(operationName, kind) {
+    return `${getOperationHookName(operationName, kind)}.ts`;
+}
+/**
+ * Generate query key factory name
+ * e.g., "currentUser" -> "currentUserQueryKey"
+ */
+export function getQueryKeyName(operationName) {
+    return `${operationName}QueryKey`;
+}
+/**
+ * Generate GraphQL document constant name
+ * e.g., "login" -> "loginMutationDocument"
+ */
+export function getDocumentConstName(operationName, kind) {
+    return `${operationName}${kind === 'query' ? 'Query' : 'Mutation'}Document`;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Types generator - generates types.ts with entity interfaces using AST
+ */
+import type { CleanTable } from '../../types/schema';
+/**
+ * Generate types.ts content with all entity interfaces and base filter types
+ */
+export declare function generateTypesFile(tables: CleanTable[]): string;
+/**
+ * Generate a minimal entity type (just id and display fields)
+ */
+export declare function generateMinimalEntityType(table: CleanTable): string;

package/esm/cli/codegen/types.js

@@ -0,0 +1,65 @@
+import { createProject, createSourceFile, getFormattedOutput, createFileHeader, createInterface, } from './ts-ast';
+import { getScalarFields, fieldTypeToTs } from './utils';
+import { generateBaseFilterTypes } from './filters';
+/**
+ * Generate types.ts content with all entity interfaces and base filter types
+ */
+export function generateTypesFile(tables) {
+    const project = createProject();
+    const sourceFile = createSourceFile(project, 'types.ts');
+    // Add file header
+    sourceFile.insertText(0, createFileHeader('Entity types and filter types') + '\n\n');
+    // Add section comment
+    sourceFile.addStatements('// ============================================================================');
+    sourceFile.addStatements('// Entity types');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Generate entity interfaces
+    for (const table of tables) {
+        const scalarFields = getScalarFields(table);
+        const properties = scalarFields.map((field) => ({
+            name: field.name,
+            type: `${fieldTypeToTs(field.type)} | null`,
+        }));
+        sourceFile.addInterface(createInterface(table.name, properties));
+    }
+    // Add section comment for filters
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Filter types (shared)');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Add base filter types (using string concat for complex types - acceptable for static definitions)
+    const filterTypesContent = generateBaseFilterTypes();
+    // Extract just the interfaces part (skip the header)
+    const filterInterfaces = filterTypesContent
+        .split('\n')
+        .slice(6) // Skip header lines
+        .join('\n');
+    sourceFile.addStatements(filterInterfaces);
+    return getFormattedOutput(sourceFile);
+}
+/**
+ * Generate a minimal entity type (just id and display fields)
+ */
+export function generateMinimalEntityType(table) {
+    const project = createProject();
+    const sourceFile = createSourceFile(project, 'minimal.ts');
+    const scalarFields = getScalarFields(table);
+    // Find id and likely display fields
+    const displayFields = scalarFields.filter((f) => {
+        const name = f.name.toLowerCase();
+        return (name === 'id' ||
+            name === 'name' ||
+            name === 'title' ||
+            name === 'label' ||
+            name === 'email' ||
+            name.endsWith('name') ||
+            name.endsWith('title'));
+    });
+    // If no display fields found, take first 5 scalar fields
+    const fieldsToUse = displayFields.length > 0 ? displayFields : scalarFields.slice(0, 5);
+    const properties = fieldsToUse.map((field) => ({
+        name: field.name,
+        type: `${fieldTypeToTs(field.type)} | null`,
+    }));
+    sourceFile.addInterface(createInterface(`${table.name}Minimal`, properties));
+    return getFormattedOutput(sourceFile);
+}