@gqlkit-ts/cli 0.2.0 → 0.4.0

package/src/schema-generator/integrator/result-integrator.ts

@@ -1,4 +1,9 @@
-import type { AutoGeneratedType } from "../../auto-type-generator/index.js";
+import type {
+  AutoGeneratedType,
+  ResolveTypeFieldPattern,
+} from "../../auto-type-generator/index.js";
+import type { TypenameAutoResolveTypeInfo } from "../../auto-type-generator/typename-resolve-type-generator.js";
+import { createFieldNameSet } from "../../auto-type-generator/typename-types.js";
 import type {
   AbstractResolverInfo,
   ExtractResolversResult,
@@ -121,21 +126,22 @@ export interface StringEnumMappingInfo {
   readonly members: ReadonlyArray<StringEnumMember>;
 }
 
+export interface AutoGeneratedUnionInfo {
+  readonly name: string;
+  readonly fieldPattern: ResolveTypeFieldPattern;
+  readonly hasAutoResolveType: boolean;
+}
+
 export interface IntegratedResult {
   readonly baseTypes: ReadonlyArray<BaseType>;
   readonly inputTypes: ReadonlyArray<InputType>;
   readonly typeExtensions: ReadonlyArray<TypeExtension>;
-  /** @deprecated Use customScalars instead */
-  readonly customScalarNames: ReadonlyArray<string> | null;
-  /** Custom scalars with description information */
   readonly customScalars: ReadonlyArray<CustomScalarInfo> | null;
-  /** Directive definitions extracted from type aliases */
   readonly directiveDefinitions: ReadonlyArray<DirectiveDefinitionInfo> | null;
-  /** Abstract type resolvers (resolveType and isTypeOf) */
   readonly abstractTypeResolvers: ReadonlyArray<AbstractResolverInfo>;
-  /** Numeric enum information for resolver generation */
+  readonly autoGeneratedUnions: ReadonlyArray<AutoGeneratedUnionInfo>;
+  readonly typenameAutoResolveTypes: ReadonlyArray<TypenameAutoResolveTypeInfo>;
   readonly numericEnums: ReadonlyArray<NumericEnumInfo>;
-  /** String enum mappings for resolver generation */
   readonly stringEnumMappings: ReadonlyArray<StringEnumMappingInfo>;
   readonly hasQuery: boolean;
   readonly hasMutation: boolean;
@@ -143,6 +149,17 @@ export interface IntegratedResult {
   readonly diagnostics: ReadonlyArray<Diagnostic>;
 }
 
+function toBaseField(field: BaseField): BaseField {
+  return {
+    name: field.name,
+    type: field.type,
+    description: field.description,
+    deprecated: field.deprecated,
+    directives: field.directives,
+    defaultValue: field.defaultValue,
+  };
+}
+
 function convertToExtensionField(
   field: GraphQLFieldDefinition,
 ): ExtensionField {
@@ -250,14 +267,26 @@ function getCompatibleLocations(
   }
 }
 
-export function integrate(
-  typesResult: ExtractTypesResult,
-  resolversResult: ExtractResolversResult,
-  customScalarNames: ReadonlyArray<string> | null,
-  collectedScalars?: ReadonlyArray<CollectedScalarType> | null,
-  directiveDefinitions?: ReadonlyArray<DirectiveDefinitionInfo> | null,
-  autoGeneratedTypes?: ReadonlyArray<AutoGeneratedType> | null,
-): IntegratedResult {
+export interface IntegrateParams {
+  readonly typesResult: ExtractTypesResult;
+  readonly resolversResult: ExtractResolversResult;
+  readonly customScalarNames: ReadonlyArray<string> | null;
+  readonly collectedScalars: ReadonlyArray<CollectedScalarType> | null;
+  readonly directiveDefinitions: ReadonlyArray<DirectiveDefinitionInfo> | null;
+  readonly autoGeneratedTypes: ReadonlyArray<AutoGeneratedType> | null;
+  readonly typenameAutoResolveTypes: ReadonlyArray<TypenameAutoResolveTypeInfo> | null;
+}
+
+export function integrate(params: IntegrateParams): IntegratedResult {
+  const {
+    typesResult,
+    resolversResult,
+    customScalarNames,
+    collectedScalars,
+    directiveDefinitions,
+    autoGeneratedTypes,
+    typenameAutoResolveTypes,
+  } = params;
   const directiveTypeAliasNames = new Set(
     directiveDefinitions?.map((d) => d.typeAliasName) ?? [],
   );
@@ -281,20 +310,14 @@ export function integrate(
 
   const baseTypes: BaseType[] = [];
   const inputTypes: InputType[] = [];
+  const autoGeneratedUnions: AutoGeneratedUnionInfo[] = [];
 
   for (const autoType of autoGeneratedTypes ?? []) {
     if (autoType.kind === "Object") {
       baseTypes.push({
         name: autoType.name,
         kind: "Object",
-        fields: autoType.fields!.map((f) => ({
-          name: f.name,
-          type: f.type,
-          description: f.description,
-          deprecated: f.deprecated,
-          directives: f.directives,
-          defaultValue: f.defaultValue,
-        })),
+        fields: autoType.fields!.map(toBaseField),
         unionMembers: null,
         enumValues: null,
         isNumericEnum: false,
@@ -327,17 +350,40 @@ export function integrate(
         sourceFile: autoType.sourceLocation.file,
         directives: null,
       });
+    } else if (autoType.kind === "Union") {
+      baseTypes.push({
+        name: autoType.name,
+        kind: "Union",
+        fields: null,
+        unionMembers: autoType.unionMembers ?? [],
+        enumValues: null,
+        isNumericEnum: false,
+        needsStringEnumMapping: false,
+        implementedInterfaces: null,
+        description: autoType.description,
+        deprecated: null,
+        sourceFile: autoType.sourceLocation.file,
+        directives: null,
+      });
+      autoGeneratedUnions.push({
+        name: autoType.name,
+        fieldPattern: autoType.resolveTypeFieldPattern ?? {
+          usedFieldNames: createFieldNameSet(["__typename"]),
+        },
+        hasAutoResolveType: autoType.resolveTypeFieldPattern !== null,
+      });
+    } else if (autoType.kind === "OneOfInputObject") {
+      inputTypes.push({
+        name: autoType.name,
+        fields: autoType.fields!.map(toBaseField),
+        sourceFile: autoType.sourceLocation.file,
+        description: autoType.description,
+        isOneOf: true,
+      });
     } else {
       inputTypes.push({
         name: autoType.name,
-        fields: autoType.fields!.map((f) => ({
-          name: f.name,
-          type: f.type,
-          description: f.description,
-          deprecated: f.deprecated,
-          directives: f.directives,
-          defaultValue: f.defaultValue,
-        })),
+        fields: autoType.fields!.map(toBaseField),
         sourceFile: autoType.sourceLocation.file,
         description: autoType.description,
         isOneOf: false,
@@ -353,15 +399,7 @@ export function integrate(
     if (type.kind === "InputObject" || type.kind === "OneOfInputObject") {
       inputTypes.push({
         name: type.name,
-        fields:
-          type.fields?.map((field) => ({
-            name: field.name,
-            type: field.type,
-            description: field.description,
-            deprecated: field.deprecated,
-            directives: field.directives,
-            defaultValue: field.defaultValue,
-          })) ?? [],
+        fields: type.fields?.map(toBaseField) ?? [],
         sourceFile: type.sourceFile,
         description: type.description,
         isOneOf: type.kind === "OneOfInputObject",
@@ -385,15 +423,7 @@ export function integrate(
       baseTypes.push({
         name: type.name,
         kind: type.kind,
-        fields:
-          type.fields?.map((field) => ({
-            name: field.name,
-            type: field.type,
-            description: field.description,
-            deprecated: field.deprecated,
-            directives: field.directives,
-            defaultValue: field.defaultValue,
-          })) ?? null,
+        fields: type.fields?.map(toBaseField) ?? null,
         unionMembers: null,
         enumValues: null,
         isNumericEnum: false,
@@ -408,15 +438,7 @@ export function integrate(
       baseTypes.push({
         name: type.name,
         kind: type.kind,
-        fields:
-          type.fields?.map((field) => ({
-            name: field.name,
-            type: field.type,
-            description: field.description,
-            deprecated: field.deprecated,
-            directives: field.directives,
-            defaultValue: field.defaultValue,
-          })) ?? null,
+        fields: type.fields?.map(toBaseField) ?? null,
         unionMembers: null,
         enumValues: null,
         isNumericEnum: false,
@@ -481,9 +503,17 @@ export function integrate(
     });
   }
 
+  const typenameAutoResolveTypeNames = new Set([
+    ...(typenameAutoResolveTypes?.map((t) => t.abstractTypeName) ?? []),
+    ...autoGeneratedUnions
+      .filter((u) => u.hasAutoResolveType)
+      .map((u) => u.name),
+  ]);
+
   const abstractResolverValidation = validateAbstractResolvers({
     abstractResolvers: resolversResult.abstractTypeResolvers,
     baseTypes,
+    typenameAutoResolveTypeNames,
   });
   diagnostics.push(...abstractResolverValidation.diagnostics);
 
@@ -670,16 +700,14 @@ export function integrate(
     baseTypes,
     inputTypes,
     typeExtensions,
-    customScalarNames:
-      customScalarNames && customScalarNames.length > 0
-        ? customScalarNames
-        : null,
     customScalars,
     directiveDefinitions:
       directiveDefinitions && directiveDefinitions.length > 0
         ? directiveDefinitions
         : null,
     abstractTypeResolvers: resolversResult.abstractTypeResolvers,
+    autoGeneratedUnions,
+    typenameAutoResolveTypes: typenameAutoResolveTypes ?? [],
     numericEnums,
     stringEnumMappings,
     hasQuery,

package/src/schema-generator/resolver-collector/resolver-collector.ts

@@ -1,3 +1,4 @@
+import type { AutoGeneratedResolveType } from "../../auto-type-generator/resolve-type-generator.js";
 import type { AbstractResolverInfo } from "../../resolver-extractor/extractor/define-api-extractor.js";
 import type {
   ExtensionField,
@@ -28,6 +29,7 @@ export interface ResolverInfo {
   readonly types: ReadonlyArray<TypeResolvers>;
   readonly sourceFiles: ReadonlyArray<string>;
   readonly abstractTypeResolvers: ReadonlyArray<AbstractTypeResolverInfo>;
+  readonly autoGeneratedResolveTypes: ReadonlyArray<AutoGeneratedResolveType>;
 }
 
 function getResolverValueName(typeName: string): string {
@@ -104,6 +106,37 @@ export function collectResolverInfo(
     sourceFilesSet.add(resolver.sourceFile);
   }
 
+  const manualResolveTypeNames = new Set<string>(
+    abstractTypeResolvers
+      .filter((r) => r.resolverKey === "__resolveType")
+      .map((r) => r.typeName),
+  );
+
+  const inlineUnionResolveTypes: AutoGeneratedResolveType[] =
+    integratedResult.autoGeneratedUnions
+      .filter(
+        (u) => u.hasAutoResolveType && !manualResolveTypeNames.has(u.name),
+      )
+      .map((u) => ({
+        unionTypeName: u.name,
+        fieldPattern: u.fieldPattern,
+      }));
+
+  const typenameResolveTypes: AutoGeneratedResolveType[] =
+    integratedResult.typenameAutoResolveTypes
+      .filter((t) => !manualResolveTypeNames.has(t.abstractTypeName))
+      .map((t) => ({
+        unionTypeName: t.abstractTypeName,
+        fieldPattern: {
+          usedFieldNames: t.resolveTypePattern.usedFieldNames,
+        },
+      }));
+
+  const autoGeneratedResolveTypes = [
+    ...inlineUnionResolveTypes,
+    ...typenameResolveTypes,
+  ].sort((a, b) => a.unionTypeName.localeCompare(b.unionTypeName));
+
   const types: TypeResolvers[] = [...typeMap.entries()]
     .map(([typeName, fields]) => ({
       typeName,
@@ -119,5 +152,6 @@ export function collectResolverInfo(
     types,
     sourceFiles,
     abstractTypeResolvers,
+    autoGeneratedResolveTypes,
   };
 }

package/src/shared/branded-type-detector.ts

@@ -0,0 +1,182 @@
+/**
+ * Branded type detector.
+ *
+ * This module provides functions to detect branded type patterns in TypeScript
+ * intersection types and extract the underlying primitive type.
+ *
+ * Branded types are intersection types combining a primitive with a marker object:
+ * - `string & { __brand: 'UserId' }`
+ * - `number & { readonly __brand: unique symbol }`
+ * - `boolean & { __nominal: true }`
+ */
+
+import ts from "typescript";
+
+/**
+ * Result of branded type detection.
+ */
+export interface BrandedTypeResult {
+  /** Whether the type is a branded primitive type */
+  readonly isBranded: boolean;
+  /** The base primitive type if branded, null otherwise */
+  readonly baseType: "string" | "number" | "boolean" | null;
+}
+
+/**
+ * Property names commonly used as brand markers.
+ * These indicate the type is a branded type, not an actual object.
+ */
+const BRAND_PROPERTY_NAMES: ReadonlySet<string> = new Set([
+  "__brand",
+  "_brand",
+  "brand",
+  "__nominal",
+  "_nominal",
+  "__tag",
+  "_tag",
+  "__type",
+]);
+
+/**
+ * Property names to exclude from brand detection.
+ * These are used by gqlkit for scalar metadata, not branding.
+ */
+const EXCLUDED_BRAND_PROPERTIES: ReadonlySet<string> = new Set([
+  " $gqlkitScalar",
+]);
+
+/**
+ * Detects if a type is a branded primitive type.
+ *
+ * A branded type is an intersection type where:
+ * 1. One member is a primitive type (string, number, or boolean)
+ * 2. Other members are pure brand markers (objects with only brand properties)
+ *
+ * @param type - The TypeScript type to analyze
+ * @returns Detection result with isBranded flag and baseType
+ */
+export function detectBrandedType(type: ts.Type): BrandedTypeResult {
+  const notBranded: BrandedTypeResult = { isBranded: false, baseType: null };
+
+  if (!type.isIntersection()) {
+    return notBranded;
+  }
+
+  let primitiveBase: "string" | "number" | "boolean" | null = null;
+  let hasNonBrandMember = false;
+
+  for (const member of type.types) {
+    const primitiveType = getPrimitiveType(member);
+    if (primitiveType !== null) {
+      if (primitiveBase !== null && primitiveBase !== primitiveType) {
+        // Multiple different primitive types - not a valid branded type
+        return notBranded;
+      }
+      primitiveBase = primitiveType;
+      continue;
+    }
+
+    // Check if this member is a pure brand marker
+    if (!isPureBrandMarker(member)) {
+      hasNonBrandMember = true;
+      break;
+    }
+  }
+
+  if (hasNonBrandMember || primitiveBase === null) {
+    return notBranded;
+  }
+
+  return { isBranded: true, baseType: primitiveBase };
+}
+
+/**
+ * Detects if all types in the array are branded with the same base type.
+ *
+ * This is useful for union types where branded boolean expands to:
+ * `(true & { __nominal: true }) | (false & { __nominal: true })`
+ *
+ * @param types - Array of TypeScript types to analyze
+ * @returns Common branded result if all types are branded with the same base, otherwise non-branded
+ */
+export function detectUniformBrandedType(
+  types: ReadonlyArray<ts.Type>,
+): BrandedTypeResult {
+  if (types.length === 0) {
+    return { isBranded: false, baseType: null };
+  }
+
+  const first = detectBrandedType(types[0]!);
+  if (!first.isBranded) {
+    return { isBranded: false, baseType: null };
+  }
+
+  for (let i = 1; i < types.length; i++) {
+    const result = detectBrandedType(types[i]!);
+    if (!result.isBranded || result.baseType !== first.baseType) {
+      return { isBranded: false, baseType: null };
+    }
+  }
+
+  return first;
+}
+
+/**
+ * Gets the primitive type from a TypeScript type.
+ *
+ * @returns "string", "number", "boolean", or null if not a primitive
+ */
+function getPrimitiveType(
+  type: ts.Type,
+): "string" | "number" | "boolean" | null {
+  if (type.flags & ts.TypeFlags.String) {
+    return "string";
+  }
+  if (type.flags & ts.TypeFlags.Number) {
+    return "number";
+  }
+  if (
+    type.flags & ts.TypeFlags.Boolean ||
+    type.flags & ts.TypeFlags.BooleanLiteral
+  ) {
+    return "boolean";
+  }
+  return null;
+}
+
+/**
+ * Checks if a type is a pure brand marker.
+ *
+ * A pure brand marker is an object type where all properties are
+ * brand-related (e.g., __brand, __nominal, __tag).
+ *
+ * @param type - The type to check
+ * @returns true if the type is a pure brand marker
+ */
+function isPureBrandMarker(type: ts.Type): boolean {
+  if (!(type.flags & ts.TypeFlags.Object)) {
+    return false;
+  }
+
+  const properties = type.getProperties();
+  if (properties.length === 0) {
+    // Empty object is not a brand marker
+    return false;
+  }
+
+  for (const prop of properties) {
+    const propName = prop.getName();
+
+    // Excluded properties (like gqlkit metadata) disqualify as brand marker
+    if (EXCLUDED_BRAND_PROPERTIES.has(propName)) {
+      return false;
+    }
+
+    // If any property is not a brand property, this is not a pure brand marker
+    if (!BRAND_PROPERTY_NAMES.has(propName)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/shared/enum-prefix-detector.ts

@@ -0,0 +1,99 @@
+/**
+ * Converts an enum name from any naming convention to UPPER_SNAKE_CASE.
+ *
+ * Supports PascalCase, camelCase, UPPER_SNAKE_CASE, and single word inputs.
+ *
+ * @example
+ * toUpperSnakeCase("UserStatus") // => "USER_STATUS"
+ * toUpperSnakeCase("userStatus") // => "USER_STATUS"
+ * toUpperSnakeCase("USER_STATUS") // => "USER_STATUS"
+ * toUpperSnakeCase("Status") // => "STATUS"
+ */
+export function toUpperSnakeCase(name: string): string {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toUpperCase();
+}
+
+/**
+ * Builds the prefix candidate string for enum prefix stripping.
+ *
+ * Converts the enum name to UPPER_SNAKE_CASE and appends "_" to create
+ * the prefix that will be checked against all enum values.
+ *
+ * @example
+ * buildEnumPrefixCandidate("UserStatus") // => "USER_STATUS_"
+ * buildEnumPrefixCandidate("userStatus") // => "USER_STATUS_"
+ * buildEnumPrefixCandidate("USER_STATUS") // => "USER_STATUS_"
+ * buildEnumPrefixCandidate("Status") // => "STATUS_"
+ */
+export function buildEnumPrefixCandidate(enumName: string): string {
+  return `${toUpperSnakeCase(enumName)}_`;
+}
+
+export interface DetectEnumPrefixParams {
+  readonly enumName: string;
+  readonly memberValues: ReadonlyArray<string>;
+}
+
+export interface DetectEnumPrefixResult {
+  readonly shouldStrip: boolean;
+  readonly prefix: string | null;
+}
+
+/**
+ * Detects whether an enum is a candidate for prefix stripping.
+ *
+ * Conditions for stripping:
+ * 1. All memberValues must start with `${toUpperSnakeCase(enumName)}_`
+ * 2. After removing the prefix, the remaining string must be non-empty
+ *
+ * @example
+ * detectEnumPrefix({
+ *   enumName: "UserStatus",
+ *   memberValues: ["USER_STATUS_ACTIVE", "USER_STATUS_INACTIVE"]
+ * })
+ * // => { shouldStrip: true, prefix: "USER_STATUS_" }
+ *
+ * detectEnumPrefix({
+ *   enumName: "UserStatus",
+ *   memberValues: ["ACTIVE", "INACTIVE"]
+ * })
+ * // => { shouldStrip: false, prefix: null }
+ */
+export function detectEnumPrefix(
+  params: DetectEnumPrefixParams,
+): DetectEnumPrefixResult {
+  const { enumName, memberValues } = params;
+
+  if (memberValues.length === 0) {
+    return { shouldStrip: false, prefix: null };
+  }
+
+  const prefixCandidate = buildEnumPrefixCandidate(enumName);
+
+  for (const value of memberValues) {
+    if (!value.startsWith(prefixCandidate)) {
+      return { shouldStrip: false, prefix: null };
+    }
+
+    const stripped = value.slice(prefixCandidate.length);
+    if (stripped === "") {
+      return { shouldStrip: false, prefix: null };
+    }
+  }
+
+  return { shouldStrip: true, prefix: prefixCandidate };
+}
+
+/**
+ * Removes the detected prefix from an enum value.
+ *
+ * @example
+ * stripEnumPrefix("USER_STATUS_ACTIVE", "USER_STATUS_")
+ * // => "ACTIVE"
+ */
+export function stripEnumPrefix(value: string, prefix: string): string {
+  return value.slice(prefix.length);
+}

package/src/shared/ignore-fields-detector.ts

@@ -0,0 +1,109 @@
+/**
+ * IgnoreFields metadata detector.
+ *
+ * This module provides functions to detect ignoreFields metadata embedded
+ * in TypeScript intersection types using the $gqlkitTypeMeta property.
+ */
+
+import ts from "typescript";
+import { METADATA_PROPERTIES } from "./constants.js";
+import { getActualMetadataType } from "./metadata-detector.js";
+
+const TYPE_META_PROPERTY = METADATA_PROPERTIES.TYPE_META;
+
+/**
+ * Parameters for detectIgnoreFieldsMetadata function.
+ */
+export interface DetectIgnoreFieldsParams {
+  readonly type: ts.Type;
+  readonly checker: ts.TypeChecker;
+}
+
+/**
+ * Extracts ignoreFields from a type's metadata.
+ * Returns null if the type doesn't have $gqlkitTypeMeta or ignoreFields is not specified.
+ */
+function extractIgnoreFieldsFromType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): ReadonlySet<string> | null {
+  const metaProp = type.getProperty(TYPE_META_PROPERTY);
+  if (!metaProp) {
+    return null;
+  }
+
+  const rawMetadataType = checker.getTypeOfSymbol(metaProp);
+  const metadataType = getActualMetadataType(rawMetadataType);
+  if (!metadataType) {
+    return null;
+  }
+
+  const ignoreFieldsProp = metadataType.getProperty("ignoreFields");
+  if (!ignoreFieldsProp) {
+    return null;
+  }
+
+  const rawIgnoreFieldsType = checker.getTypeOfSymbol(ignoreFieldsProp);
+  const ignoreFieldsType = getActualMetadataType(rawIgnoreFieldsType);
+  if (!ignoreFieldsType) {
+    return null;
+  }
+
+  return extractStringLiteralUnion(ignoreFieldsType);
+}
+
+/**
+ * Extracts string literals from a type (single literal or union of literals).
+ */
+function extractStringLiteralUnion(type: ts.Type): ReadonlySet<string> | null {
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    const value = (type as ts.StringLiteralType).value;
+    return new Set([value]);
+  }
+
+  if (type.isUnion()) {
+    const values = new Set<string>();
+    for (const member of type.types) {
+      if (member.flags & ts.TypeFlags.StringLiteral) {
+        values.add((member as ts.StringLiteralType).value);
+      }
+    }
+    if (values.size > 0) {
+      return values;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects ignoreFields metadata from a TypeScript type.
+ *
+ * This function analyzes TypeScript types to detect ignoreFields metadata
+ * from the $gqlkitTypeMeta property. It extracts string literal or string
+ * literal union types and returns them as a Set.
+ *
+ * @param params - The detection parameters containing type and checker
+ * @returns The ignoreFields set or null if not specified
+ */
+export function detectIgnoreFieldsMetadata(
+  params: DetectIgnoreFieldsParams,
+): ReadonlySet<string> | null {
+  const { type, checker } = params;
+
+  const result = extractIgnoreFieldsFromType(type, checker);
+  if (result) {
+    return result;
+  }
+
+  if (type.isIntersection()) {
+    for (const member of type.types) {
+      const memberResult = extractIgnoreFieldsFromType(member, checker);
+      if (memberResult) {
+        return memberResult;
+      }
+    }
+  }
+
+  return null;
+}