@constructive-io/graphql-codegen 2.19.0 → 2.20.0

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

@@ -0,0 +1,163 @@
+/**
+ * Codegen utilities - naming conventions, type mapping, and helpers
+ */
+import type { CleanTable, CleanField, CleanFieldType } from '../../types/schema';
+/** Lowercase first character */
+export declare function lcFirst(str: string): string;
+/** Uppercase first character */
+export declare function ucFirst(str: string): string;
+/** Convert to camelCase */
+export declare function toCamelCase(str: string): string;
+/** Convert to PascalCase */
+export declare function toPascalCase(str: string): string;
+/** Convert to SCREAMING_SNAKE_CASE */
+export declare function toScreamingSnake(str: string): string;
+export interface TableNames {
+    /** PascalCase singular (e.g., "Car") */
+    typeName: string;
+    /** camelCase singular (e.g., "car") */
+    singularName: string;
+    /** camelCase plural (e.g., "cars") */
+    pluralName: string;
+    /** PascalCase plural (e.g., "Cars") */
+    pluralTypeName: string;
+}
+/**
+ * Derive all naming variants from a table
+ */
+export declare function getTableNames(table: CleanTable): TableNames;
+/**
+ * Generate hook function name for list query
+ * e.g., "useCarsQuery"
+ */
+export declare function getListQueryHookName(table: CleanTable): string;
+/**
+ * Generate hook function name for single item query
+ * e.g., "useCarQuery"
+ */
+export declare function getSingleQueryHookName(table: CleanTable): string;
+/**
+ * Generate hook function name for create mutation
+ * e.g., "useCreateCarMutation"
+ */
+export declare function getCreateMutationHookName(table: CleanTable): string;
+/**
+ * Generate hook function name for update mutation
+ * e.g., "useUpdateCarMutation"
+ */
+export declare function getUpdateMutationHookName(table: CleanTable): string;
+/**
+ * Generate hook function name for delete mutation
+ * e.g., "useDeleteCarMutation"
+ */
+export declare function getDeleteMutationHookName(table: CleanTable): string;
+/**
+ * Generate file name for list query hook
+ * e.g., "useCarsQuery.ts"
+ */
+export declare function getListQueryFileName(table: CleanTable): string;
+/**
+ * Generate file name for single query hook
+ * e.g., "useCarQuery.ts"
+ */
+export declare function getSingleQueryFileName(table: CleanTable): string;
+/**
+ * Generate file name for create mutation hook
+ */
+export declare function getCreateMutationFileName(table: CleanTable): string;
+/**
+ * Generate file name for update mutation hook
+ */
+export declare function getUpdateMutationFileName(table: CleanTable): string;
+/**
+ * Generate file name for delete mutation hook
+ */
+export declare function getDeleteMutationFileName(table: CleanTable): string;
+/**
+ * Get the GraphQL query name for fetching all rows
+ * Uses inflection from _meta, falls back to convention
+ */
+export declare function getAllRowsQueryName(table: CleanTable): string;
+/**
+ * Get the GraphQL query name for fetching single row
+ */
+export declare function getSingleRowQueryName(table: CleanTable): string;
+/**
+ * Get the GraphQL mutation name for creating
+ */
+export declare function getCreateMutationName(table: CleanTable): string;
+/**
+ * Get the GraphQL mutation name for updating
+ */
+export declare function getUpdateMutationName(table: CleanTable): string;
+/**
+ * Get the GraphQL mutation name for deleting
+ */
+export declare function getDeleteMutationName(table: CleanTable): string;
+/**
+ * Get PostGraphile filter type name
+ * e.g., "CarFilter"
+ */
+export declare function getFilterTypeName(table: CleanTable): string;
+/**
+ * Get PostGraphile OrderBy enum type name
+ * e.g., "CarsOrderBy"
+ */
+export declare function getOrderByTypeName(table: CleanTable): string;
+/**
+ * Get PostGraphile create input type name
+ * e.g., "CreateCarInput"
+ */
+export declare function getCreateInputTypeName(table: CleanTable): string;
+/**
+ * Get PostGraphile patch type name for updates
+ * e.g., "CarPatch"
+ */
+export declare function getPatchTypeName(table: CleanTable): string;
+/**
+ * Get PostGraphile update input type name
+ * e.g., "UpdateCarInput"
+ */
+export declare function getUpdateInputTypeName(table: CleanTable): string;
+/**
+ * Get PostGraphile delete input type name
+ * e.g., "DeleteCarInput"
+ */
+export declare function getDeleteInputTypeName(table: CleanTable): string;
+/**
+ * Convert GraphQL type to TypeScript type
+ */
+export declare function gqlTypeToTs(gqlType: string, isArray?: boolean): string;
+/**
+ * Convert CleanFieldType to TypeScript type string
+ */
+export declare function fieldTypeToTs(fieldType: CleanFieldType): string;
+/**
+ * Get the PostGraphile filter type for a GraphQL scalar
+ */
+export declare function getScalarFilterType(gqlType: string): string | null;
+/**
+ * Check if a field is a relation field (not a scalar)
+ */
+export declare function isRelationField(fieldName: string, table: CleanTable): boolean;
+/**
+ * Get only scalar fields (non-relation fields)
+ */
+export declare function getScalarFields(table: CleanTable): CleanField[];
+/**
+ * Get primary key field names
+ */
+export declare function getPrimaryKeyFields(table: CleanTable): string[];
+/**
+ * Generate query key prefix for a table
+ * e.g., "cars" for list queries, "car" for detail queries
+ */
+export declare function getQueryKeyPrefix(table: CleanTable): string;
+/**
+ * Generate a doc comment header for generated files
+ */
+export declare function getGeneratedFileHeader(description: string): string;
+/**
+ * Indent a multi-line string
+ */
+export declare function indent(str: string, spaces?: number): string;

package/esm/cli/codegen/utils.js

@@ -0,0 +1,288 @@
+import { scalarToTsType, scalarToFilterType } from './scalars';
+// ============================================================================
+// String manipulation
+// ============================================================================
+/** Lowercase first character */
+export function lcFirst(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+/** Uppercase first character */
+export function ucFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/** Convert to camelCase */
+export function toCamelCase(str) {
+    return str
+        .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
+        .replace(/^(.)/, (_, char) => char.toLowerCase());
+}
+/** Convert to PascalCase */
+export function toPascalCase(str) {
+    return str
+        .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
+        .replace(/^(.)/, (_, char) => char.toUpperCase());
+}
+/** Convert to SCREAMING_SNAKE_CASE */
+export function toScreamingSnake(str) {
+    return str
+        .replace(/([A-Z])/g, '_$1')
+        .replace(/[-\s]/g, '_')
+        .toUpperCase()
+        .replace(/^_/, '');
+}
+/**
+ * Derive all naming variants from a table
+ */
+export function getTableNames(table) {
+    const typeName = table.name;
+    const singularName = table.inflection?.tableFieldName || lcFirst(typeName);
+    const pluralName = table.query?.all || table.inflection?.allRows || singularName + 's';
+    const pluralTypeName = ucFirst(pluralName);
+    return {
+        typeName,
+        singularName,
+        pluralName,
+        pluralTypeName,
+    };
+}
+/**
+ * Generate hook function name for list query
+ * e.g., "useCarsQuery"
+ */
+export function getListQueryHookName(table) {
+    const { pluralName } = getTableNames(table);
+    return `use${ucFirst(pluralName)}Query`;
+}
+/**
+ * Generate hook function name for single item query
+ * e.g., "useCarQuery"
+ */
+export function getSingleQueryHookName(table) {
+    const { singularName } = getTableNames(table);
+    return `use${ucFirst(singularName)}Query`;
+}
+/**
+ * Generate hook function name for create mutation
+ * e.g., "useCreateCarMutation"
+ */
+export function getCreateMutationHookName(table) {
+    const { typeName } = getTableNames(table);
+    return `useCreate${typeName}Mutation`;
+}
+/**
+ * Generate hook function name for update mutation
+ * e.g., "useUpdateCarMutation"
+ */
+export function getUpdateMutationHookName(table) {
+    const { typeName } = getTableNames(table);
+    return `useUpdate${typeName}Mutation`;
+}
+/**
+ * Generate hook function name for delete mutation
+ * e.g., "useDeleteCarMutation"
+ */
+export function getDeleteMutationHookName(table) {
+    const { typeName } = getTableNames(table);
+    return `useDelete${typeName}Mutation`;
+}
+/**
+ * Generate file name for list query hook
+ * e.g., "useCarsQuery.ts"
+ */
+export function getListQueryFileName(table) {
+    return `${getListQueryHookName(table)}.ts`;
+}
+/**
+ * Generate file name for single query hook
+ * e.g., "useCarQuery.ts"
+ */
+export function getSingleQueryFileName(table) {
+    return `${getSingleQueryHookName(table)}.ts`;
+}
+/**
+ * Generate file name for create mutation hook
+ */
+export function getCreateMutationFileName(table) {
+    return `${getCreateMutationHookName(table)}.ts`;
+}
+/**
+ * Generate file name for update mutation hook
+ */
+export function getUpdateMutationFileName(table) {
+    return `${getUpdateMutationHookName(table)}.ts`;
+}
+/**
+ * Generate file name for delete mutation hook
+ */
+export function getDeleteMutationFileName(table) {
+    return `${getDeleteMutationHookName(table)}.ts`;
+}
+// ============================================================================
+// GraphQL operation names
+// ============================================================================
+/**
+ * Get the GraphQL query name for fetching all rows
+ * Uses inflection from _meta, falls back to convention
+ */
+export function getAllRowsQueryName(table) {
+    return table.query?.all || table.inflection?.allRows || lcFirst(table.name) + 's';
+}
+/**
+ * Get the GraphQL query name for fetching single row
+ */
+export function getSingleRowQueryName(table) {
+    return table.query?.one || table.inflection?.tableFieldName || lcFirst(table.name);
+}
+/**
+ * Get the GraphQL mutation name for creating
+ */
+export function getCreateMutationName(table) {
+    return table.query?.create || `create${table.name}`;
+}
+/**
+ * Get the GraphQL mutation name for updating
+ */
+export function getUpdateMutationName(table) {
+    return table.query?.update || `update${table.name}`;
+}
+/**
+ * Get the GraphQL mutation name for deleting
+ */
+export function getDeleteMutationName(table) {
+    return table.query?.delete || `delete${table.name}`;
+}
+// ============================================================================
+// Type names
+// ============================================================================
+/**
+ * Get PostGraphile filter type name
+ * e.g., "CarFilter"
+ */
+export function getFilterTypeName(table) {
+    return table.inflection?.filterType || `${table.name}Filter`;
+}
+/**
+ * Get PostGraphile OrderBy enum type name
+ * e.g., "CarsOrderBy"
+ */
+export function getOrderByTypeName(table) {
+    return table.inflection?.orderByType || `${table.name}sOrderBy`;
+}
+/**
+ * Get PostGraphile create input type name
+ * e.g., "CreateCarInput"
+ */
+export function getCreateInputTypeName(table) {
+    return table.inflection?.createInputType || `Create${table.name}Input`;
+}
+/**
+ * Get PostGraphile patch type name for updates
+ * e.g., "CarPatch"
+ */
+export function getPatchTypeName(table) {
+    return table.inflection?.patchType || `${table.name}Patch`;
+}
+/**
+ * Get PostGraphile update input type name
+ * e.g., "UpdateCarInput"
+ */
+export function getUpdateInputTypeName(table) {
+    return `Update${table.name}Input`;
+}
+/**
+ * Get PostGraphile delete input type name
+ * e.g., "DeleteCarInput"
+ */
+export function getDeleteInputTypeName(table) {
+    return `Delete${table.name}Input`;
+}
+// ============================================================================
+// Type mapping: GraphQL → TypeScript
+// ============================================================================
+/**
+ * Convert GraphQL type to TypeScript type
+ */
+export function gqlTypeToTs(gqlType, isArray = false) {
+    // Remove non-null markers
+    const cleanType = gqlType.replace(/!/g, '');
+    // Look up in map, fallback to the type name itself (custom type)
+    const tsType = scalarToTsType(cleanType, { unknownScalar: 'name' });
+    return isArray ? `${tsType}[]` : tsType;
+}
+/**
+ * Convert CleanFieldType to TypeScript type string
+ */
+export function fieldTypeToTs(fieldType) {
+    return gqlTypeToTs(fieldType.gqlType, fieldType.isArray);
+}
+// ============================================================================
+// Type mapping: GraphQL → Filter type
+// ============================================================================
+/**
+ * Get the PostGraphile filter type for a GraphQL scalar
+ */
+export function getScalarFilterType(gqlType) {
+    const cleanType = gqlType.replace(/!/g, '');
+    return scalarToFilterType(cleanType);
+}
+// ============================================================================
+// Field filtering utilities
+// ============================================================================
+/**
+ * Check if a field is a relation field (not a scalar)
+ */
+export function isRelationField(fieldName, table) {
+    const { belongsTo, hasOne, hasMany, manyToMany } = table.relations;
+    return (belongsTo.some((r) => r.fieldName === fieldName) ||
+        hasOne.some((r) => r.fieldName === fieldName) ||
+        hasMany.some((r) => r.fieldName === fieldName) ||
+        manyToMany.some((r) => r.fieldName === fieldName));
+}
+/**
+ * Get only scalar fields (non-relation fields)
+ */
+export function getScalarFields(table) {
+    return table.fields.filter((f) => !isRelationField(f.name, table));
+}
+/**
+ * Get primary key field names
+ */
+export function getPrimaryKeyFields(table) {
+    const pk = table.constraints?.primaryKey?.[0];
+    if (!pk)
+        return ['id']; // Default assumption
+    return pk.fields.map((f) => f.name);
+}
+// ============================================================================
+// Query key generation
+// ============================================================================
+/**
+ * Generate query key prefix for a table
+ * e.g., "cars" for list queries, "car" for detail queries
+ */
+export function getQueryKeyPrefix(table) {
+    return lcFirst(table.name);
+}
+// ============================================================================
+// Code generation helpers
+// ============================================================================
+/**
+ * Generate a doc comment header for generated files
+ */
+export function getGeneratedFileHeader(description) {
+    return `/**
+ * ${description}
+ * @generated by @constructive-io/graphql-codegen
+ * DO NOT EDIT - changes will be overwritten
+ */`;
+}
+/**
+ * Indent a multi-line string
+ */
+export function indent(str, spaces = 2) {
+    const pad = ' '.repeat(spaces);
+    return str
+        .split('\n')
+        .map((line) => (line.trim() ? pad + line : line))
+        .join('\n');
+}

package/esm/cli/commands/generate-orm.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Generate ORM command - generates Prisma-like ORM client
+ *
+ * This command:
+ * 1. Fetches _meta query for table-based CRUD operations
+ * 2. Fetches __schema introspection for custom operations
+ * 3. Generates a Prisma-like ORM client with fluent API
+ */
+export interface GenerateOrmOptions {
+    /** Path to config file */
+    config?: string;
+    /** GraphQL endpoint URL (overrides config) */
+    endpoint?: string;
+    /** Output directory (overrides config) */
+    output?: string;
+    /** Authorization header */
+    authorization?: string;
+    /** Verbose output */
+    verbose?: boolean;
+    /** Dry run - don't write files */
+    dryRun?: boolean;
+    /** Skip custom operations (only generate table CRUD) */
+    skipCustomOperations?: boolean;
+}
+export interface GenerateOrmResult {
+    success: boolean;
+    message: string;
+    tables?: string[];
+    customQueries?: string[];
+    customMutations?: string[];
+    filesWritten?: string[];
+    errors?: string[];
+}
+/**
+ * Execute the generate-orm command
+ */
+export declare function generateOrmCommand(options?: GenerateOrmOptions): Promise<GenerateOrmResult>;

package/esm/cli/commands/generate-orm.js

@@ -0,0 +1,192 @@
+/**
+ * Generate ORM command - generates Prisma-like ORM client
+ *
+ * This command:
+ * 1. Fetches _meta query for table-based CRUD operations
+ * 2. Fetches __schema introspection for custom operations
+ * 3. Generates a Prisma-like ORM client with fluent API
+ */
+import { resolveConfig } from '../../types/config';
+import { fetchMeta, validateEndpoint } from '../introspect/fetch-meta';
+import { fetchSchema } from '../introspect/fetch-schema';
+import { transformMetaToCleanTables, filterTables, } from '../introspect/transform';
+import { transformSchemaToOperations, filterOperations, getTableOperationNames, getCustomOperations, } from '../introspect/transform-schema';
+import { findConfigFile, loadConfigFile } from './init';
+import { writeGeneratedFiles } from './generate';
+import { generateOrm } from '../codegen/orm';
+/**
+ * Execute the generate-orm command
+ */
+export async function generateOrmCommand(options = {}) {
+    const log = options.verbose ? console.log : () => { };
+    // 1. Load config
+    log('Loading configuration...');
+    const configResult = await loadConfig(options);
+    if (!configResult.success) {
+        return {
+            success: false,
+            message: configResult.error,
+        };
+    }
+    const config = configResult.config;
+    // Use ORM output directory if specified, otherwise default
+    const outputDir = options.output || config.orm?.output || './generated/orm';
+    log(`  Endpoint: ${config.endpoint}`);
+    log(`  Output: ${outputDir}`);
+    // 2. Validate endpoint
+    const endpointValidation = validateEndpoint(config.endpoint);
+    if (!endpointValidation.valid) {
+        return {
+            success: false,
+            message: `Invalid endpoint: ${endpointValidation.error}`,
+        };
+    }
+    // Build authorization header if provided
+    const authHeader = options.authorization || config.headers['Authorization'];
+    // 3. Fetch _meta for table-based operations
+    log('Fetching schema metadata (_meta)...');
+    const metaResult = await fetchMeta({
+        endpoint: config.endpoint,
+        authorization: authHeader,
+        headers: config.headers,
+        timeout: 30000,
+    });
+    if (!metaResult.success) {
+        return {
+            success: false,
+            message: `Failed to fetch _meta: ${metaResult.error}`,
+        };
+    }
+    // 4. Transform to CleanTable[]
+    log('Transforming table schema...');
+    let tables = transformMetaToCleanTables(metaResult.data);
+    log(`  Found ${tables.length} tables`);
+    // 5. Filter tables
+    tables = filterTables(tables, config.tables.include, config.tables.exclude);
+    log(`  After filtering: ${tables.length} tables`);
+    if (tables.length === 0) {
+        return {
+            success: false,
+            message: 'No tables found after filtering. Check your include/exclude patterns.',
+        };
+    }
+    // Get table operation names for filtering custom operations
+    const tableOperationNames = getTableOperationNames(tables);
+    // 6. Fetch __schema for custom operations (unless skipped)
+    let customQueries = [];
+    let customMutations = [];
+    let customOperationsData;
+    if (!options.skipCustomOperations) {
+        log('Fetching schema introspection (__schema)...');
+        const schemaResult = await fetchSchema({
+            endpoint: config.endpoint,
+            authorization: authHeader,
+            headers: config.headers,
+            timeout: 30000,
+        });
+        if (schemaResult.success && schemaResult.data) {
+            log('Transforming custom operations...');
+            // Transform to CleanOperation[]
+            const { queries: allQueries, mutations: allMutations, typeRegistry } = transformSchemaToOperations(schemaResult.data);
+            log(`  Found ${allQueries.length} queries and ${allMutations.length} mutations total`);
+            // Filter by config include/exclude
+            const filteredQueries = filterOperations(allQueries, config.queries.include, config.queries.exclude);
+            const filteredMutations = filterOperations(allMutations, config.mutations.include, config.mutations.exclude);
+            log(`  After config filtering: ${filteredQueries.length} queries, ${filteredMutations.length} mutations`);
+            // Remove table operations (already handled by table generators)
+            const customQueriesOps = getCustomOperations(filteredQueries, tableOperationNames);
+            const customMutationsOps = getCustomOperations(filteredMutations, tableOperationNames);
+            log(`  Custom operations: ${customQueriesOps.length} queries, ${customMutationsOps.length} mutations`);
+            customQueries = customQueriesOps.map((q) => q.name);
+            customMutations = customMutationsOps.map((m) => m.name);
+            customOperationsData = {
+                queries: customQueriesOps,
+                mutations: customMutationsOps,
+                typeRegistry,
+            };
+        }
+        else {
+            log(`  Warning: Could not fetch __schema: ${schemaResult.error}`);
+            log('  Continuing with table-only generation...');
+        }
+    }
+    // 7. Generate ORM code
+    log('Generating ORM client...');
+    const { files: generatedFiles, stats } = generateOrm({
+        tables,
+        customOperations: customOperationsData,
+        config,
+    });
+    log(`  Generated ${stats.tables} table models`);
+    log(`  Generated ${stats.customQueries} custom query operations`);
+    log(`  Generated ${stats.customMutations} custom mutation operations`);
+    log(`  Total files: ${stats.totalFiles}`);
+    if (options.dryRun) {
+        return {
+            success: true,
+            message: `Dry run complete. Would generate ${generatedFiles.length} files for ${tables.length} tables and ${customQueries.length + customMutations.length} custom operations.`,
+            tables: tables.map((t) => t.name),
+            customQueries,
+            customMutations,
+            filesWritten: generatedFiles.map((f) => f.path),
+        };
+    }
+    // 8. Write files
+    log('Writing files...');
+    const writeResult = await writeGeneratedFiles(generatedFiles, outputDir, ['models', 'query', 'mutation']);
+    if (!writeResult.success) {
+        return {
+            success: false,
+            message: `Failed to write files: ${writeResult.errors?.join(', ')}`,
+            errors: writeResult.errors,
+        };
+    }
+    const totalOps = customQueries.length + customMutations.length;
+    const customOpsMsg = totalOps > 0 ? ` and ${totalOps} custom operations` : '';
+    return {
+        success: true,
+        message: `Generated ORM client for ${tables.length} tables${customOpsMsg}. Files written to ${outputDir}`,
+        tables: tables.map((t) => t.name),
+        customQueries,
+        customMutations,
+        filesWritten: writeResult.filesWritten,
+    };
+}
+async function loadConfig(options) {
+    // Find config file
+    let configPath = options.config;
+    if (!configPath) {
+        configPath = findConfigFile() ?? undefined;
+    }
+    let baseConfig = {};
+    if (configPath) {
+        const loadResult = await loadConfigFile(configPath);
+        if (!loadResult.success) {
+            return { success: false, error: loadResult.error };
+        }
+        baseConfig = loadResult.config;
+    }
+    // Override with CLI options
+    const mergedConfig = {
+        endpoint: options.endpoint || baseConfig.endpoint || '',
+        output: options.output || baseConfig.output,
+        headers: baseConfig.headers,
+        tables: baseConfig.tables,
+        queries: baseConfig.queries,
+        mutations: baseConfig.mutations,
+        excludeFields: baseConfig.excludeFields,
+        hooks: baseConfig.hooks,
+        postgraphile: baseConfig.postgraphile,
+        codegen: baseConfig.codegen,
+        orm: baseConfig.orm,
+    };
+    if (!mergedConfig.endpoint) {
+        return {
+            success: false,
+            error: 'No endpoint specified. Use --endpoint or create a config file with "graphql-codegen init".',
+        };
+    }
+    // Resolve with defaults
+    const config = resolveConfig(mergedConfig);
+    return { success: true, config };
+}