@gqlkit-ts/cli 0.6.0 → 0.7.1

package/src/auto-type-generator/naming-convention.ts

@@ -55,11 +55,36 @@ export interface ResolverPayloadContext {
   readonly fieldPath: ReadonlyArray<string>;
 }
 
+const IRREGULAR_SINGULAR_FIELD_NAMES = new Map([
+  ["aliases", "alias"],
+  ["analyses", "analysis"],
+  ["buses", "bus"],
+  ["children", "child"],
+  ["cookies", "cookie"],
+  ["crises", "crisis"],
+  ["diagnoses", "diagnosis"],
+  ["feet", "foot"],
+  ["geese", "goose"],
+  ["men", "man"],
+  ["mice", "mouse"],
+  ["movies", "movie"],
+  ["people", "person"],
+  ["selfies", "selfie"],
+  ["statuses", "status"],
+  ["teeth", "tooth"],
+  ["theses", "thesis"],
+  ["women", "woman"],
+  ["zombies", "zombie"],
+]);
+
+const NON_INFLECTING_FIELD_NAMES = new Set(["news", "series", "species"]);
+const AMBIGUOUS_PLURAL_FIELD_NAMES = new Set(["axes"]);
+
 /**
  * Convert a string to PascalCase.
  * Handles camelCase, snake_case, and kebab-case inputs.
  */
-function toPascalCase(str: string): string {
+export function toPascalCase(str: string): string {
   if (str.length === 0) return str;
 
   return str
@@ -76,6 +101,185 @@ function toPascalCase(str: string): string {
     .join("");
 }
 
+function isConsonant(char: string): boolean {
+  return /^[bcdfghjklmnpqrstvwxyz]$/i.test(char);
+}
+
+function isUppercaseLetter(char: string): boolean {
+  return char.toLowerCase() !== char && char.toUpperCase() === char;
+}
+
+function applyReplacementCase(params: {
+  readonly replacement: string;
+  readonly template: string;
+}): string {
+  const { replacement, template } = params;
+
+  if (template.toUpperCase() === template) {
+    return replacement.toUpperCase();
+  }
+
+  if (isUppercaseLetter(template.charAt(0))) {
+    return `${replacement.charAt(0).toUpperCase()}${replacement.slice(1)}`;
+  }
+
+  return replacement;
+}
+
+function singularizeIrregularFieldName(name: string): string | null {
+  const lowerName = name.toLowerCase();
+
+  for (const [plural, singular] of IRREGULAR_SINGULAR_FIELD_NAMES) {
+    if (!lowerName.endsWith(plural)) {
+      continue;
+    }
+
+    const suffixStart = name.length - plural.length;
+    if (suffixStart > 0) {
+      const previousChar = name.charAt(suffixStart - 1);
+      const suffixFirstChar = name.charAt(suffixStart);
+      const hasWordBoundary =
+        previousChar === "_" ||
+        previousChar === "-" ||
+        isUppercaseLetter(suffixFirstChar);
+
+      if (!hasWordBoundary) {
+        continue;
+      }
+    }
+
+    return `${name.slice(0, suffixStart)}${applyReplacementCase({
+      replacement: singular,
+      template: name.slice(suffixStart),
+    })}`;
+  }
+
+  return null;
+}
+
+/**
+ * Singularize a plural field name conservatively for array element type naming.
+ * Falls back to the original name when the plural form is ambiguous.
+ */
+export function singularizeFieldName(name: string): string {
+  const irregularSingular = singularizeIrregularFieldName(name);
+  if (irregularSingular) {
+    return irregularSingular;
+  }
+
+  const lowerName = name.toLowerCase();
+
+  if (name.length <= 3 || NON_INFLECTING_FIELD_NAMES.has(lowerName)) {
+    return name;
+  }
+
+  if (AMBIGUOUS_PLURAL_FIELD_NAMES.has(lowerName)) {
+    return name;
+  }
+
+  if (lowerName.endsWith("ies")) {
+    if (name.length <= 4) {
+      return name.slice(0, -1);
+    }
+
+    if (isConsonant(lowerName.at(-4) ?? "")) {
+      return `${name.slice(0, -3)}y`;
+    }
+  }
+
+  if (
+    lowerName.endsWith("sses") ||
+    lowerName.endsWith("shes") ||
+    lowerName.endsWith("ches") ||
+    lowerName.endsWith("xes") ||
+    lowerName.endsWith("zes")
+  ) {
+    return name.slice(0, -2);
+  }
+
+  if (
+    lowerName.endsWith("s") &&
+    !lowerName.endsWith("ss") &&
+    !lowerName.endsWith("is") &&
+    !lowerName.endsWith("us")
+  ) {
+    return name.slice(0, -1);
+  }
+
+  return name;
+}
+
+interface AppendFieldPathParams {
+  readonly parentPath: ReadonlyArray<string>;
+  readonly fieldName: string;
+  readonly singularize: boolean;
+  readonly siblingFieldNames: ReadonlySet<string> | null;
+}
+
+function hasSiblingFieldPathCollision(params: {
+  readonly fieldName: string;
+  readonly singularFieldName: string;
+  readonly siblingFieldNames: ReadonlySet<string> | null;
+}): boolean {
+  const { fieldName, singularFieldName, siblingFieldNames } = params;
+
+  if (!siblingFieldNames) {
+    return false;
+  }
+
+  for (const siblingFieldName of siblingFieldNames) {
+    if (siblingFieldName === fieldName) {
+      continue;
+    }
+
+    if (
+      siblingFieldName === singularFieldName ||
+      singularizeFieldName(siblingFieldName) === singularFieldName
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function resolveFieldPathSegment(params: {
+  readonly fieldName: string;
+  readonly singularize: boolean;
+  readonly siblingFieldNames: ReadonlySet<string> | null;
+}): string {
+  const { fieldName, singularize, siblingFieldNames } = params;
+
+  if (!singularize) {
+    return fieldName;
+  }
+
+  const singularFieldName = singularizeFieldName(fieldName);
+  if (
+    singularFieldName !== fieldName &&
+    hasSiblingFieldPathCollision({
+      fieldName,
+      singularFieldName,
+      siblingFieldNames,
+    })
+  ) {
+    return fieldName;
+  }
+
+  return singularFieldName;
+}
+
+/**
+ * Append a field name to an auto-type field path.
+ */
+export function appendFieldPath(params: AppendFieldPathParams): string[] {
+  const { parentPath, fieldName, singularize, siblingFieldNames } = params;
+  return [
+    ...parentPath,
+    resolveFieldPathSegment({ fieldName, singularize, siblingFieldNames }),
+  ];
+}
+
 /**
  * Remove Input suffix from type name if present.
  */

package/src/auto-type-generator/typename-extractor.ts

@@ -45,7 +45,11 @@ function extractTypenameFromFields(
   }
 
   const { tsType } = field;
-  if (tsType.nullable || tsType.kind !== "literal" || tsType.name === null) {
+  if (
+    tsType.nullable ||
+    tsType.kind !== "stringLiteral" ||
+    tsType.name === null
+  ) {
     return null;
   }
 
@@ -63,7 +67,11 @@ function extractTypenameFromInlineObjectProperties(
   const { property, fieldName } = found;
   const { propertyType: tsType } = property;
 
-  if (tsType.nullable || tsType.kind !== "literal" || tsType.name === null) {
+  if (
+    tsType.nullable ||
+    tsType.kind !== "stringLiteral" ||
+    tsType.name === null
+  ) {
     return null;
   }
 
@@ -206,12 +214,14 @@ function extractTypenames(
 export interface CollectTypenameExtractionsParams {
   readonly extractedTypes: ReadonlyArray<ExtractedTypeInfo>;
   readonly typeMap: ReadonlyMap<string, ExtractedTypeInfo>;
+  /** Union names that have discriminatorFields configured; these are excluded from typename extraction. */
+  readonly discriminatorFieldUnionNames: ReadonlySet<string>;
 }
 
 export function collectTypenameExtractions(
   params: CollectTypenameExtractionsParams,
 ): ReadonlyArray<TypenameExtractionResult> {
-  const { extractedTypes, typeMap } = params;
+  const { extractedTypes, typeMap, discriminatorFieldUnionNames } = params;
   const results: TypenameExtractionResult[] = [];
 
   for (const typeInfo of extractedTypes) {
@@ -219,6 +229,10 @@ export function collectTypenameExtractions(
       typeInfo.metadata.kind === "union" ||
       typeInfo.metadata.kind === "graphqlInterface"
     ) {
+      // Skip unions that have discriminatorFields configured; they use the discriminator pipeline instead
+      if (discriminatorFieldUnionNames.has(typeInfo.metadata.name)) {
+        continue;
+      }
       const result = extractTypenames({ abstractType: typeInfo, typeMap });
       if (result !== null) {
         results.push(result);

package/src/auto-type-generator/typename-resolve-type-generator.ts

@@ -1,12 +1,6 @@
-import type {
-  ExtractedTypeInfo,
-  InlineObjectMember,
-  InlineObjectProperty,
-} from "../type-extractor/types/index.js";
-import type {
-  AutoGeneratedField,
-  AutoGeneratedType,
-} from "./auto-type-generator.js";
+import type { ExtractedTypeInfo } from "../type-extractor/types/index.js";
+import type { AutoGeneratedType } from "./auto-type-generator.js";
+import { generateObjectTypeFromInlineObject } from "./inline-object-converter.js";
 import type { ResolveTypeFieldPattern } from "./resolve-type-generator.js";
 import {
   collectTypenameExtractions,
@@ -39,6 +33,8 @@ export interface CollectTypenameResolveTypesParams {
   readonly extractedTypes: ReadonlyArray<ExtractedTypeInfo>;
   readonly typeMap: ReadonlyMap<string, ExtractedTypeInfo>;
   readonly manualResolveTypeNames: ReadonlySet<string>;
+  /** Union names that have discriminatorFields configured; these are excluded from typename processing. */
+  readonly discriminatorFieldUnionNames: ReadonlySet<string>;
 }
 
 export interface CollectTypenameResolveTypesResult {
@@ -83,100 +79,8 @@ function determineResolveTypePattern(
   return { usedFieldNames, memberFieldMap };
 }
 
-function primitiveToGraphQLScalar(primitive: string): string {
-  switch (primitive) {
-    case "string":
-      return "String";
-    case "number":
-      return "Float";
-    case "boolean":
-      return "Boolean";
-    default:
-      return "String";
-  }
-}
-
-function convertInlineObjectPropertyToField(
-  property: InlineObjectProperty,
-): AutoGeneratedField | null {
-  if (
-    property.propertyName === "__typename" ||
-    property.propertyName === "$typeName"
-  ) {
-    return null;
-  }
-
-  const tsType = property.propertyType;
-  let typeName: string;
-  const nullable = tsType.nullable;
-  let list = false;
-  let listItemNullable: boolean | null = null;
-
-  if (tsType.kind === "array" && tsType.elementType) {
-    list = true;
-    listItemNullable = tsType.elementType.nullable;
-    const elementName = tsType.elementType.name ?? "String";
-    typeName =
-      tsType.elementType.kind === "primitive"
-        ? primitiveToGraphQLScalar(elementName)
-        : elementName;
-  } else if (tsType.kind === "reference" && tsType.name) {
-    typeName = tsType.name;
-  } else if (tsType.kind === "primitive" && tsType.name) {
-    typeName = primitiveToGraphQLScalar(tsType.name);
-  } else if (tsType.kind === "scalar" && tsType.scalarInfo) {
-    typeName = tsType.scalarInfo.scalarName;
-  } else {
-    typeName = "String";
-  }
-
-  return {
-    name: property.propertyName,
-    type: {
-      typeName,
-      nullable,
-      list,
-      listItemNullable,
-    },
-    description: property.description,
-    deprecated: property.deprecated,
-    directives: null,
-    defaultValue: null,
-  };
-}
-
-function generateObjectTypeFromInlineObject(
-  inlineObjectMember: InlineObjectMember,
-  typeName: string,
-  abstractTypeName: string,
-  sourceFile: string,
-): AutoGeneratedType {
-  const fields: AutoGeneratedField[] = [];
-
-  for (const property of inlineObjectMember.properties) {
-    const field = convertInlineObjectPropertyToField(property);
-    if (field !== null) {
-      fields.push(field);
-    }
-  }
-
-  return {
-    name: typeName,
-    kind: "Object",
-    fields,
-    enumValues: null,
-    unionMembers: null,
-    needsStringEnumMapping: false,
-    sourceLocation: { file: sourceFile, line: 1, column: 1 },
-    generatedFrom: {
-      parentTypeName: abstractTypeName,
-      fieldPath: [],
-      context: "typeField",
-    },
-    description: null,
-    resolveTypeFieldPattern: null,
-  };
-}
+/** Typename-related properties that should be excluded from generated object types. */
+const TYPENAME_PROPERTY_NAMES = new Set(["__typename", "$typeName"]);
 
 function collectGeneratedObjectTypes(
   extraction: TypenameExtractionResult,
@@ -209,12 +113,13 @@ function collectGeneratedObjectTypes(
 
     const typeName = member.typenameInfo.typeName;
 
-    const objectType = generateObjectTypeFromInlineObject(
+    const objectType = generateObjectTypeFromInlineObject({
       inlineObjectMember,
       typeName,
-      extraction.abstractTypeName,
-      extractedType.metadata.sourceFile,
-    );
+      abstractTypeName: extraction.abstractTypeName,
+      sourceFile: extractedType.metadata.sourceFile,
+      skipPropertyNames: TYPENAME_PROPERTY_NAMES,
+    });
 
     generatedObjectTypes.push(objectType);
     generatedInlineObjectTypes.push({
@@ -230,11 +135,17 @@ function collectGeneratedObjectTypes(
 export function collectTypenameResolveTypes(
   params: CollectTypenameResolveTypesParams,
 ): CollectTypenameResolveTypesResult {
-  const { extractedTypes, typeMap, manualResolveTypeNames } = params;
+  const {
+    extractedTypes,
+    typeMap,
+    manualResolveTypeNames,
+    discriminatorFieldUnionNames,
+  } = params;
 
   const extractions = collectTypenameExtractions({
     extractedTypes,
     typeMap,
+    discriminatorFieldUnionNames,
   });
 
   const autoResolveTypes: TypenameAutoResolveTypeInfo[] = [];

package/src/auto-type-generator/typename-types.ts

@@ -15,6 +15,13 @@
  */
 export const TYPENAME_FIELD_NAMES = ["__typename", "$typeName"] as const;
 
+/**
+ * Check if a field name is a typename discrimination field.
+ */
+export function isTypenameFieldName(name: string): boolean {
+  return (TYPENAME_FIELD_NAMES as readonly string[]).includes(name);
+}
+
 /**
  * The field name used for type discrimination.
  */

package/src/auto-type-generator/typename-validator.ts

@@ -74,7 +74,7 @@ function analyzeInlineObjectTypename(
   return {
     exists: true,
     fieldName,
-    isStringLiteral: tsType.kind === "literal" && tsType.name !== null,
+    isStringLiteral: tsType.kind === "stringLiteral" && tsType.name !== null,
     isNullable: tsType.nullable,
   };
 }
@@ -171,7 +171,8 @@ export function validateTypenames(
 
     const { typeName, fieldName } = member.typenameInfo;
     const memberTypeName =
-      member.memberTypeName ?? `member${member.memberIndex}`;
+      member.memberTypeName ??
+      `(anonymous member at index ${member.memberIndex})`;
 
     const existing = typenameValueToMembers.get(typeName) ?? [];
     existing.push({ memberTypeName, fieldName });
@@ -238,7 +239,7 @@ function extractTypenameFromObjectType(
   if (
     field.optional ||
     tsType.nullable ||
-    tsType.kind !== "literal" ||
+    tsType.kind !== "stringLiteral" ||
     tsType.name === null
   ) {
     return null;

package/src/commands/gen.ts

@@ -45,8 +45,14 @@ export async function runGenCommand(
     ? dirname(configResult.configPath)
     : options.cwd;
 
-  const { sourceDir, sourceIgnoreGlobs, output, scalars, tsconfigPath } =
-    configResult.config;
+  const {
+    sourceDir,
+    sourceIgnoreGlobs,
+    output,
+    scalars,
+    tsconfigPath,
+    discriminatorFields,
+  } = configResult.config;
 
   const config: GenerationConfig = {
     cwd: options.cwd,
@@ -56,6 +62,7 @@ export async function runGenCommand(
     configDir,
     customScalars: scalars,
     tsconfigPath,
+    discriminatorFields,
   };
 
   progressReporter.startPhase("Extracting types");

package/src/config/types.ts

@@ -100,6 +100,16 @@ export interface GqlkitConfig {
    * Hook configuration for lifecycle events.
    */
   readonly hooks?: HooksConfig;
+
+  /**
+   * Custom discriminator field mappings for union types.
+   * Maps GraphQL union type names to TypeScript discriminator field names.
+   * When specified, gqlkit generates __resolveType functions based on these fields
+   * instead of requiring $typeName or __typename.
+   */
+  readonly discriminatorFields?: Readonly<
+    Record<string, string | ReadonlyArray<string>>
+  >;
 }
 
 /**

package/src/config-loader/index.ts

@@ -3,6 +3,7 @@ export {
   type LoadConfigResult,
   loadConfig,
   type ResolvedConfig,
+  type ResolvedDiscriminatorFieldsMap,
   type ResolvedHooksConfig,
   type ResolvedOutputConfig,
   type ResolvedScalarMapping,

package/src/config-loader/loader.ts

@@ -42,6 +42,15 @@ export interface ResolvedHooksConfig {
   readonly afterAllFileWrite: ReadonlyArray<string>;
 }
 
+/**
+ * Normalized discriminator fields mapping.
+ * All values are normalized to arrays (single strings are wrapped in arrays).
+ */
+export type ResolvedDiscriminatorFieldsMap = ReadonlyMap<
+  string,
+  ReadonlyArray<string>
+>;
+
 export interface ResolvedConfig {
   readonly sourceDir: string;
   readonly sourceIgnoreGlobs: ReadonlyArray<string>;
@@ -49,6 +58,7 @@ export interface ResolvedConfig {
   readonly scalars: ReadonlyArray<ResolvedScalarMapping>;
   readonly tsconfigPath: string | null;
   readonly hooks: ResolvedHooksConfig;
+  readonly discriminatorFields: ResolvedDiscriminatorFieldsMap;
 }
 
 export interface LoadConfigResult {
@@ -82,6 +92,7 @@ const DEFAULT_RESOLVED_CONFIG: ResolvedConfig = {
   scalars: [],
   tsconfigPath: null,
   hooks: DEFAULT_HOOKS_CONFIG,
+  discriminatorFields: new Map(),
 };
 
 export async function loadConfig(

package/src/config-loader/validator.ts

@@ -6,6 +6,7 @@ import {
   DEFAULT_SOURCE_DIR,
   DEFAULT_TYPEDEFS_PATH,
   type ResolvedConfig,
+  type ResolvedDiscriminatorFieldsMap,
   type ResolvedHooksConfig,
   type ResolvedOutputConfig,
   type ResolvedScalarMapping,
@@ -584,6 +585,96 @@ function validateHooksConfig(
   return { resolved: undefined, diagnostics };
 }
 
+function validateDiscriminatorFieldsConfig(
+  value: unknown,
+  configPath: string,
+): {
+  resolved: ResolvedDiscriminatorFieldsMap | undefined;
+  diagnostics: Diagnostic[];
+} {
+  const diagnostics: Diagnostic[] = [];
+
+  if (value === undefined) {
+    return { resolved: new Map(), diagnostics: [] };
+  }
+
+  if (!isRecord(value)) {
+    diagnostics.push({
+      code: "CONFIG_INVALID_DISCRIMINATOR_FIELDS",
+      message: "discriminatorFields must be an object",
+      severity: "error",
+      location: { file: configPath, line: 1, column: 1 },
+    });
+    return { resolved: undefined, diagnostics };
+  }
+
+  const result = new Map<string, ReadonlyArray<string>>();
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") {
+      if (entry === "") {
+        diagnostics.push({
+          code: "CONFIG_EMPTY_DISCRIMINATOR_FIELDS",
+          message: `discriminatorFields["${key}"] cannot be an empty string`,
+          severity: "error",
+          location: { file: configPath, line: 1, column: 1 },
+        });
+        continue;
+      }
+      result.set(key, [entry]);
+    } else if (Array.isArray(entry)) {
+      if (entry.length === 0) {
+        diagnostics.push({
+          code: "CONFIG_EMPTY_DISCRIMINATOR_FIELDS",
+          message: `discriminatorFields["${key}"] cannot be an empty array`,
+          severity: "error",
+          location: { file: configPath, line: 1, column: 1 },
+        });
+        continue;
+      }
+      let hasError = false;
+      for (const item of entry) {
+        if (typeof item !== "string") {
+          diagnostics.push({
+            code: "CONFIG_INVALID_DISCRIMINATOR_ENTRY",
+            message: `discriminatorFields["${key}"] array must contain only strings`,
+            severity: "error",
+            location: { file: configPath, line: 1, column: 1 },
+          });
+          hasError = true;
+          break;
+        }
+        if (item === "") {
+          diagnostics.push({
+            code: "CONFIG_EMPTY_DISCRIMINATOR_FIELDS",
+            message: `discriminatorFields["${key}"] array contains an empty string`,
+            severity: "error",
+            location: { file: configPath, line: 1, column: 1 },
+          });
+          hasError = true;
+          break;
+        }
+      }
+      if (!hasError) {
+        result.set(key, entry as string[]);
+      }
+    } else {
+      diagnostics.push({
+        code: "CONFIG_INVALID_DISCRIMINATOR_ENTRY",
+        message: `discriminatorFields["${key}"] must be a string or array of strings`,
+        severity: "error",
+        location: { file: configPath, line: 1, column: 1 },
+      });
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    return { resolved: undefined, diagnostics };
+  }
+
+  return { resolved: result, diagnostics: [] };
+}
+
 export function validateConfig(
   options: ValidateConfigOptions,
 ): ValidateConfigResult {
@@ -621,6 +712,12 @@ export function validateConfig(
   const hooksResult = validateHooksConfig(config["hooks"], configPath);
   diagnostics.push(...hooksResult.diagnostics);
 
+  const discriminatorFieldsResult = validateDiscriminatorFieldsConfig(
+    config["discriminatorFields"],
+    configPath,
+  );
+  diagnostics.push(...discriminatorFieldsResult.diagnostics);
+
   if (config["scalars"] !== undefined && !Array.isArray(config["scalars"])) {
     diagnostics.push({
       code: "CONFIG_INVALID_TYPE",
@@ -685,7 +782,8 @@ export function validateConfig(
     !sourceDirResult.resolved ||
     !sourceIgnoreGlobsResult.resolved ||
     !outputResult.resolved ||
-    !hooksResult.resolved
+    !hooksResult.resolved ||
+    !discriminatorFieldsResult.resolved
   ) {
     return { valid: false, resolvedConfig: undefined, diagnostics };
   }
@@ -699,6 +797,7 @@ export function validateConfig(
       scalars: resolvedScalars,
       tsconfigPath: tsconfigPathResult.resolved,
       hooks: hooksResult.resolved,
+      discriminatorFields: discriminatorFieldsResult.resolved,
     },
     diagnostics: [],
   };