/**

* Codegen utilities - naming conventions, type mapping, and helpers

*/

import {

lcFirst,

pluralize,

toCamelCase,

toConstantCase,

toPascalCase,

ucFirst,

} from 'inflekt';

import type {

Field,

FieldType,

Table,

TypeRegistry,

} from '../../types/schema';

import { scalarToFilterType, scalarToTsType } from './scalars';

// Re-export string manipulation helpers from inflekt (single source of truth)

export { lcFirst, toCamelCase, toConstantCase, toPascalCase, ucFirst };

// ============================================================================

// Naming conventions for generated code

// ============================================================================

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 function getTableNames(table: Table): TableNames {

const typeName = table.name;

const singularName = table.inflection?.tableFieldName || lcFirst(typeName);

const pluralName =

table.query?.all ||

table.inflection?.allRows ||

lcFirst(pluralize(typeName));

const pluralTypeName = ucFirst(pluralName);

return {

typeName,

singularName,

pluralName,

pluralTypeName,

};

}

/**

* Generate hook function name for list query

* e.g., "useCarsQuery"

*/

export function getListQueryHookName(table: Table): string {

const { pluralName } = getTableNames(table);

return `use${ucFirst(pluralName)}Query`;

}

/**

* Generate hook function name for single item query

* e.g., "useCarQuery"

*/

export function getSingleQueryHookName(table: Table): string {

const { singularName } = getTableNames(table);

return `use${ucFirst(singularName)}Query`;

}

/**

* Generate hook function name for create mutation

* e.g., "useCreateCarMutation"

*/

export function getCreateMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useCreate${typeName}Mutation`;

}

/**

* Generate hook function name for update mutation

* e.g., "useUpdateCarMutation"

*/

export function getUpdateMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useUpdate${typeName}Mutation`;

}

/**

* Generate hook function name for delete mutation

* e.g., "useDeleteCarMutation"

*/

export function getDeleteMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useDelete${typeName}Mutation`;

}

/**

* Generate file name for list query hook

* e.g., "useCarsQuery.ts"

*/

export function getListQueryFileName(table: Table): string {

return `${getListQueryHookName(table)}.ts`;

}

/**

* Generate file name for single query hook

* e.g., "useCarQuery.ts"

*/

export function getSingleQueryFileName(table: Table): string {

return `${getSingleQueryHookName(table)}.ts`;

}

/**

* Generate file name for create mutation hook

*/

export function getCreateMutationFileName(table: Table): string {

return `${getCreateMutationHookName(table)}.ts`;

}

/**

* Generate file name for update mutation hook

*/

export function getUpdateMutationFileName(table: Table): string {

return `${getUpdateMutationHookName(table)}.ts`;

}

/**

* Generate file name for delete mutation hook

*/

export function getDeleteMutationFileName(table: Table): string {

return `${getDeleteMutationHookName(table)}.ts`;

}

/**

* Generate hook function name for subscription

* e.g., "useContactSubscription"

*/

export function getSubscriptionHookName(table: Table): string {

const { singularName } = getTableNames(table);

return `use${ucFirst(singularName)}Subscription`;

}

/**

* Generate file name for subscription hook

* e.g., "useContactSubscription.ts"

*/

export function getSubscriptionFileName(table: Table): string {

return `${getSubscriptionHookName(table)}.ts`;

}

/**

* Generate the GraphQL subscription field name

* e.g., "onContactChanged"

*/

export function getSubscriptionFieldName(table: Table): string {

const { singularName } = getTableNames(table);

return `on${ucFirst(singularName)}Changed`;

}

// ============================================================================

// GraphQL operation names

// ============================================================================

/**

* Get the GraphQL query name for fetching all rows

* Uses inflection from introspection, falls back to convention

*/

export function getAllRowsQueryName(table: Table): string {

return (

table.query?.all ||

table.inflection?.allRows ||

lcFirst(pluralize(table.name))

);

}

/**

* Get the GraphQL query name for fetching single row

*/

export function getSingleRowQueryName(table: Table): string {

return (

table.query?.one || table.inflection?.tableFieldName || lcFirst(table.name)

);

}

/**

* Get the GraphQL mutation name for creating

*/

export function getCreateMutationName(table: Table): string {

return table.query?.create || `create${table.name}`;

}

/**

* Get the GraphQL mutation name for updating

*/

export function getUpdateMutationName(table: Table): string {

return table.query?.update || `update${table.name}`;

}

/**

* Get the GraphQL mutation name for deleting

*/

export function getDeleteMutationName(table: Table): string {

return table.query?.delete || `delete${table.name}`;

}

// ============================================================================

// Bulk mutation naming helpers

// ============================================================================

export function getBulkCreateMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useBulkCreate${typeName}Mutation`;

}

export function getBulkUpsertMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useBulkUpsert${typeName}Mutation`;

}

export function getBulkUpdateMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useBulkUpdate${typeName}Mutation`;

}

export function getBulkDeleteMutationHookName(table: Table): string {

const { typeName } = getTableNames(table);

return `useBulkDelete${typeName}Mutation`;

}

export function getBulkCreateMutationFileName(table: Table): string {

return `${getBulkCreateMutationHookName(table)}.ts`;

}

export function getBulkUpsertMutationFileName(table: Table): string {

return `${getBulkUpsertMutationHookName(table)}.ts`;

}

export function getBulkUpdateMutationFileName(table: Table): string {

return `${getBulkUpdateMutationHookName(table)}.ts`;

}

export function getBulkDeleteMutationFileName(table: Table): string {

return `${getBulkDeleteMutationHookName(table)}.ts`;

}

// ============================================================================

// Type names

// ============================================================================

/**

* Get PostGraphile filter type name

* e.g., "CarFilter"

*/

export function getFilterTypeName(table: Table): string {

return table.inflection?.filterType || `${table.name}Filter`;

}

/**

* Get PostGraphile OrderBy enum type name

* e.g., "CarsOrderBy", "AddressesOrderBy"

*/

export function getOrderByTypeName(table: Table): string {

return table.inflection?.orderByType || `${pluralize(table.name)}OrderBy`;

}

/**

* Get PostGraphile Condition type name (simple equality filter)

* e.g., "CarCondition", "AddressCondition"

*/

export function getConditionTypeName(table: Table): string {

return table.inflection?.conditionType || `${table.name}Condition`;

}

/**

* Get PostGraphile create input type name

* e.g., "CreateCarInput"

*/

export function getCreateInputTypeName(table: Table): string {

return table.inflection?.createInputType || `Create${table.name}Input`;

}

/**

* Get PostGraphile patch type name for updates

* e.g., "CarPatch"

*/

export function getPatchTypeName(table: Table): string {

return table.inflection?.patchType || `${table.name}Patch`;

}

/**

* Get PostGraphile update input type name

* Derives from actual mutation name when available (handles composite PK naming

* like UpdatePostTagByPostIdAndTagIdInput), falls back to Update${Entity}Input.

*/

export function getUpdateInputTypeName(table: Table): string {

const mutationName = table.query?.update;

return mutationName ? ucFirst(mutationName) + 'Input' : `Update${table.name}Input`;

}

/**

* Get PostGraphile delete input type name

* Derives from actual mutation name when available (handles composite PK naming

* like DeletePostTagByPostIdAndTagIdInput), falls back to Delete${Entity}Input.

*/

export function getDeleteInputTypeName(table: Table): string {

const mutationName = table.query?.delete;

return mutationName ? ucFirst(mutationName) + 'Input' : `Delete${table.name}Input`;

}

// ============================================================================

// Extra input keys (partition keys for update/delete mutations)

// ============================================================================

export interface ExtraInputKey {

name: string;

gqlType: string;

tsType: string;

}

/**

* Discover extra required fields on a mutation input type beyond the standard

* ones (clientMutationId, PK fields, patch field). PostGraphile adds these for

* partitioned tables (e.g. databaseId as the partition key).

*/

export function getExtraInputKeys(

inputTypeName: string,

pkFieldNames: Set<string>,

patchFieldName: string | null,

typeRegistry?: TypeRegistry,

): ExtraInputKey[] {

if (!typeRegistry) return [];

const inputType = typeRegistry.get(inputTypeName);

if (!inputType || inputType.kind !== 'INPUT_OBJECT' || !inputType.inputFields) return [];

const skip = new Set<string>(['clientMutationId', ...(patchFieldName ? [patchFieldName] : [])]);

for (const pk of pkFieldNames) skip.add(pk);

const extras: ExtraInputKey[] = [];

for (const field of inputType.inputFields) {

if (skip.has(field.name)) continue;

if (field.type.kind !== 'NON_NULL') continue;

const innerName = field.type.ofType?.name;

if (!innerName) continue;

let tsType = 'string';

if (innerName === 'Int' || innerName === 'Float' || innerName === 'BigFloat') tsType = 'number';

else if (innerName === 'Boolean') tsType = 'boolean';

extras.push({ name: field.name, gqlType: innerName, tsType });

}

return extras;

}

// ============================================================================

// Type mapping: GraphQL → TypeScript

// ============================================================================

/**

* Convert GraphQL type to TypeScript type

*/

export function gqlTypeToTs(gqlType: string, isArray: boolean = false): string {

// 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 FieldType to TypeScript type string

*/

export function fieldTypeToTs(fieldType: FieldType): string {

return gqlTypeToTs(fieldType.gqlType, fieldType.isArray);

}

// ============================================================================

// Type mapping: GraphQL → Filter type

// ============================================================================

/**

* Get the PostGraphile filter type for a GraphQL scalar

* @param gqlType - The GraphQL type string (e.g., "String", "UUID")

* @param isArray - Whether this is an array type

*/

export function getScalarFilterType(

gqlType: string,

isArray = false,

): string | null {

const cleanType = gqlType.replace(/!/g, '');

return scalarToFilterType(cleanType, isArray);

}

// ============================================================================

// Field filtering utilities

// ============================================================================

/**

* Check if a field is a relation field (not a scalar)

*/

export function isRelationField(fieldName: string, table: Table): boolean {

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: Table): Field[] {

return table.fields.filter((f) => !isRelationField(f.name, table));

}

/**

* Resolve the inner input type from a CreateXInput.

* PostGraphile create inputs wrap the actual field definitions in an inner type

* (e.g. CreateUserInput -> { user: UserInput }) — this resolves that inner type

* and returns the set of field names it contains.

*/

export function resolveInnerInputType(

inputTypeName: string,

typeRegistry: TypeRegistry,

): { name: string; fields: Set<string> } | null {

const inputType = typeRegistry.get(inputTypeName);

if (!inputType?.inputFields) return null;

for (const inputField of inputType.inputFields) {

const innerTypeName = inputField.type.name

|| inputField.type.ofType?.name

|| inputField.type.ofType?.ofType?.name;

if (!innerTypeName) continue;

const innerType = typeRegistry.get(innerTypeName);

if (!innerType?.inputFields) continue;

const fields = new Set(innerType.inputFields.map((f) => f.name));

return { name: innerTypeName, fields };

}

return null;

}

/**

* Get the set of field names that actually exist in the create input type.

* Fields not in this set (e.g. computed fields like searchTsvRank, hashUuid)

* are plugin-added computed fields that don't correspond to real database columns.

* Returns null when no typeRegistry is provided (caller should treat as "no filtering").

*/

export function getWritableFieldNames(

table: Table,

typeRegistry?: TypeRegistry,

): Set<string> | null {

if (!typeRegistry) return null;

const createInputTypeName = getCreateInputTypeName(table);

const resolved = resolveInnerInputType(createInputTypeName, typeRegistry);

return resolved?.fields ?? null;

}

/**

* Get scalar fields that represent actual database columns (not computed/plugin-added).

* When a TypeRegistry is provided, filters out fields that don't exist in the

* create input type — these are computed fields added by plugins (e.g. search scores,

* hash UUIDs) that aren't real columns and shouldn't appear in default selections.

* Without a TypeRegistry, falls back to all scalar fields.

*/

export function getSelectableScalarFields(

table: Table,

typeRegistry?: TypeRegistry,

): Field[] {

const writableFields = getWritableFieldNames(table, typeRegistry);

return getScalarFields(table).filter(

(f) => writableFields === null || writableFields.has(f.name),

);

}

/**

* Primary key field information

*/

export interface PrimaryKeyField {

/** Field name */

name: string;

/** GraphQL type (e.g., "UUID", "Int", "String") */

gqlType: string;

/** TypeScript type (e.g., "string", "number") */

tsType: string;

}

/**

* Get primary key field information from table constraints

* Returns array to support composite primary keys

*/

export function getPrimaryKeyInfo(table: Table): PrimaryKeyField[] {

const pk = table.constraints?.primaryKey?.[0];

if (!pk || pk.fields.length === 0) {

// Fallback: try to find 'id' field in table fields

const idField = table.fields.find((f) => f.name.toLowerCase() === 'id');

if (idField) {

return [

{

name: idField.name,

gqlType: idField.type.gqlType,

tsType: fieldTypeToTs(idField.type),

},

];

}

// Last resort: assume 'id' of type string (UUID)

return [{ name: 'id', gqlType: 'UUID', tsType: 'string' }];

}

return pk.fields.map((f) => ({

name: f.name,

gqlType: f.type.gqlType,

tsType: fieldTypeToTs(f.type),

}));

}

/**

* Get primary key field names (convenience wrapper)

*/

export function getPrimaryKeyFields(table: Table): string[] {

return getPrimaryKeyInfo(table).map((pk) => pk.name);

}

/**

* Check if table has a valid single-field primary key

* Used to determine if a single query hook can be generated

* Tables with composite keys return false (handled as custom queries)

*/

export function hasValidPrimaryKey(table: Table): boolean {

// Check for explicit primary key constraint with single field

const pk = table.constraints?.primaryKey?.[0];

if (pk && pk.fields.length === 1) {

return true;

}

// Check for 'id' field as fallback

const idField = table.fields.find((f) => f.name.toLowerCase() === 'id');

if (idField) {

return true;

}

return false;

}

// ============================================================================

// Query key generation

// ============================================================================

/**

* Generate query key prefix for a table

* e.g., "cars" for list queries, "car" for detail queries

*/

export function getQueryKeyPrefix(table: Table): string {

return lcFirst(table.name);

}

// ============================================================================

// Smart Comment Utilities

// ============================================================================

/**

* PostGraphile smart comment tags that should be stripped from descriptions.

* Smart comments start with `@` and control PostGraphile behavior

* (e.g., `@omit`, `@name`, `@foreignKey`, etc.)

*

* A PostgreSQL COMMENT may contain both human-readable text and smart comments:

* COMMENT ON TABLE users IS 'User accounts for the application\n@omit delete';

*

* PostGraphile's introspection already separates these: the GraphQL `description`

* field contains only the human-readable part. So in most cases, the description

* we receive from introspection is already clean.

*

* However, as a safety measure, this utility strips any remaining `@`-prefixed

* lines that may have leaked through.

*/

/**

* PostGraphile auto-generated boilerplate descriptions that add no value.

* These are generic descriptions PostGraphile puts on every mutation input,

* clientMutationId field, etc. We filter them out to keep generated code clean.

*/

const POSTGRAPHILE_BOILERPLATE: string[] = [

'The exclusive input argument for this mutation.',

'An arbitrary string value with no semantic meaning.',

'The exact same `clientMutationId` that was provided in the mutation input,',

'The output of our',

'All input for the',

'A cursor for use in pagination.',

'An edge for our',

'Information to aid in pagination.',

'Reads and enables pagination through a set of',

'A list of edges which contains the',

'The count of *all* `',

'A list of `',

'Our root query field',

'Reads a single',

'The root query type',

'The root mutation type',

];

/**

* Check if a description is generic PostGraphile boilerplate that should be suppressed.

*/

function isBoilerplateDescription(description: string): boolean {

const trimmed = description.trim();

return POSTGRAPHILE_BOILERPLATE.some((bp) => trimmed.startsWith(bp));

}

/**

* Strip PostGraphile smart comments and boilerplate from a description string.

*

* Smart comments are lines starting with `@` (e.g., `@omit`, `@name newName`).

* Boilerplate descriptions are generic PostGraphile-generated text that repeats

* on every mutation input, clientMutationId field, etc.

*

* This returns only the meaningful human-readable portion of the comment,

* or undefined if the result is empty or boilerplate.

*

* @param description - Raw description from GraphQL introspection

* @returns Cleaned description, or undefined if empty/boilerplate

*/

export function stripSmartComments(

description: string | null | undefined,

enabled: boolean = true,

): string | undefined {

if (!enabled) return undefined;

if (!description) return undefined;

// Check if entire description is boilerplate

if (isBoilerplateDescription(description)) return undefined;

const lines = description.split('\n');

const cleanLines: string[] = [];

for (const line of lines) {

const trimmed = line.trim();

// Skip lines that start with @ (smart comment directives)

if (trimmed.startsWith('@')) continue;

cleanLines.push(line);

}

const result = cleanLines.join('\n').trim();

if (result.length === 0) return undefined;

// Re-check after stripping smart comments

if (isBoilerplateDescription(result)) return undefined;

return result;

}

// ============================================================================

// Code generation helpers

// ============================================================================

/**

* Generate a doc comment header for generated files

*/

export function getGeneratedFileHeader(description: string): string {

return `/**

* ${description}

* @generated by @constructive-io/graphql-codegen

* DO NOT EDIT - changes will be overwritten

*/`;

}

/**

* Indent a multi-line string

*/

export function indent(str: string, spaces: number = 2): string {

const pad = ' '.repeat(spaces);

return str

.split('\n')

.map((line) => (line.trim() ? pad + line : line))

.join('\n');

}