@gqlkit-ts/cli 0.3.0 → 0.4.0

package/src/schema-generator/generate-schema.ts

@@ -6,6 +6,7 @@ import {
   validateSchemaTypenames,
   validateTypenames,
 } from "../auto-type-generator/index.js";
+import type { ImportExtension } from "../config/types.js";
 import type { ExtractResolversResult } from "../resolver-extractor/index.js";
 import type { DirectiveDefinitionInfo } from "../shared/directive-definition-extractor.js";
 import type { CollectedScalarType } from "../type-extractor/collector/scalar-collector.js";
@@ -33,6 +34,7 @@ export interface GenerateSchemaInput {
   readonly enablePruning: boolean | null;
   readonly sourceRoot: string | null;
   readonly knownTypeNames: ReadonlySet<string> | null;
+  readonly importExtension: ImportExtension;
 }
 
 export interface GenerateSchemaResult {
@@ -58,6 +60,7 @@ export function generateSchema(
     enablePruning,
     sourceRoot,
     knownTypeNames,
+    importExtension,
   } = input;
 
   const autoTypeResult = generateAutoTypes({
@@ -216,20 +219,17 @@ export function generateSchema(
     ...typenameResolveTypesResult.generatedObjectTypes,
   ];
 
-  const integratedResult = integrate(
-    updatedTypesForIntegration,
-    autoTypeResult.updatedResolversResult,
+  const integratedResult = integrate({
+    typesResult: updatedTypesForIntegration,
+    resolversResult: autoTypeResult.updatedResolversResult,
     customScalarNames,
-    customScalars,
+    collectedScalars: customScalars,
     directiveDefinitions,
-    allAutoGeneratedTypes,
-    typenameResolveTypesResult.autoResolveTypes,
-  );
+    autoGeneratedTypes: allAutoGeneratedTypes,
+    typenameAutoResolveTypes: typenameResolveTypesResult.autoResolveTypes,
+  });
 
-  let documentNode = buildDocumentNode(
-    integratedResult,
-    sourceRoot !== null ? { sourceRoot } : undefined,
-  );
+  let documentNode = buildDocumentNode(integratedResult, { sourceRoot });
   let prunedTypes: ReadonlyArray<string> | null = null;
 
   if (enablePruning) {
@@ -241,10 +241,7 @@ export function generateSchema(
     prunedTypes = pruneResult.removedTypes;
   }
 
-  const typeDefsCode = emitTypeDefsCode(
-    integratedResult,
-    sourceRoot !== null ? { sourceRoot } : undefined,
-  );
+  const typeDefsCode = emitTypeDefsCode(integratedResult, { sourceRoot });
   const sdlContent = emitSdlContent(documentNode);
 
   const resolverInfo = collectResolverInfo(integratedResult);
@@ -254,6 +251,7 @@ export function generateSchema(
     customScalars: customScalars ?? [],
     numericEnums: integratedResult.numericEnums,
     stringEnumMappings: integratedResult.stringEnumMappings,
+    importExtension,
   });
 
   return {

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

@@ -136,23 +136,12 @@ 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>;
-  /** @deprecated Use autoGeneratedUnions instead */
-  readonly autoGeneratedUnionNames: ReadonlyArray<string>;
-  /** Auto-generated Union types that need __resolveType with field pattern info */
   readonly autoGeneratedUnions: ReadonlyArray<AutoGeneratedUnionInfo>;
-  /** Union/Interface types that have typename-based auto resolveType */
   readonly typenameAutoResolveTypes: ReadonlyArray<TypenameAutoResolveTypeInfo>;
-  /** Numeric enum information for resolver generation */
   readonly numericEnums: ReadonlyArray<NumericEnumInfo>;
-  /** String enum mappings for resolver generation */
   readonly stringEnumMappings: ReadonlyArray<StringEnumMappingInfo>;
   readonly hasQuery: boolean;
   readonly hasMutation: boolean;
@@ -160,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 {
@@ -267,15 +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,
-  typenameAutoResolveTypes?: ReadonlyArray<TypenameAutoResolveTypeInfo>,
-): 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) ?? [],
   );
@@ -299,7 +310,6 @@ export function integrate(
 
   const baseTypes: BaseType[] = [];
   const inputTypes: InputType[] = [];
-  const autoGeneratedUnionNames: string[] = [];
   const autoGeneratedUnions: AutoGeneratedUnionInfo[] = [];
 
   for (const autoType of autoGeneratedTypes ?? []) {
@@ -307,14 +317,7 @@ export function integrate(
       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,
@@ -362,7 +365,6 @@ export function integrate(
         sourceFile: autoType.sourceLocation.file,
         directives: null,
       });
-      autoGeneratedUnionNames.push(autoType.name);
       autoGeneratedUnions.push({
         name: autoType.name,
         fieldPattern: autoType.resolveTypeFieldPattern ?? {
@@ -373,14 +375,7 @@ export function integrate(
     } else if (autoType.kind === "OneOfInputObject") {
       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: true,
@@ -388,14 +383,7 @@ export function integrate(
     } 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,
@@ -411,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",
@@ -443,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,
@@ -466,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,
@@ -736,17 +700,12 @@ export function integrate(
     baseTypes,
     inputTypes,
     typeExtensions,
-    customScalarNames:
-      customScalarNames && customScalarNames.length > 0
-        ? customScalarNames
-        : null,
     customScalars,
     directiveDefinitions:
       directiveDefinitions && directiveDefinitions.length > 0
         ? directiveDefinitions
         : null,
     abstractTypeResolvers: resolversResult.abstractTypeResolvers,
-    autoGeneratedUnionNames,
     autoGeneratedUnions,
     typenameAutoResolveTypes: typenameAutoResolveTypes ?? [],
     numericEnums,

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/string-utils.ts

@@ -0,0 +1,7 @@
+export function toScreamingSnakeCase(value: string): string {
+  return value
+    .replace(/[-\s]+/g, "_")
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toUpperCase();
+}

package/src/type-extractor/converter/field-eligibility.ts

@@ -24,45 +24,29 @@ function isReservedName(name: string): boolean {
   return name.startsWith("__");
 }
 
-/**
- * Check if a field name is eligible to be included as a GraphQL object field.
- */
-export function isEligibleAsObjectField(fieldName: string): EligibilityResult {
-  if (isReservedName(fieldName)) {
-    return {
-      eligible: false,
-      skipReason: {
-        code: "RESERVED_NAME",
-        message: `Field '${fieldName}' starts with '__' which is reserved for GraphQL introspection`,
-      },
-    };
-  }
+export type FieldEligibilityKind = "object" | "input";
 
-  if (!isValidGraphQLName(fieldName)) {
-    return {
-      eligible: false,
-      skipReason: {
-        code: "INVALID_NAME",
-        message: `Field '${fieldName}' is not a valid GraphQL identifier (must match /^[_A-Za-z][_0-9A-Za-z]*$/)`,
-      },
-    };
-  }
-
-  return { eligible: true, skipReason: null };
+export interface IsEligibleFieldParams {
+  readonly fieldName: string;
+  readonly kind: FieldEligibilityKind;
 }
 
 /**
- * Check if a field name is eligible to be included as a GraphQL input object field.
+ * Check if a field name is eligible to be included as a GraphQL field.
+ * Uses the kind parameter to determine the error message prefix.
  */
-export function isEligibleAsInputObjectField(
-  fieldName: string,
+export function isEligibleField(
+  params: IsEligibleFieldParams,
 ): EligibilityResult {
+  const { fieldName, kind } = params;
+  const prefix = kind === "input" ? "Input field" : "Field";
+
   if (isReservedName(fieldName)) {
     return {
       eligible: false,
       skipReason: {
         code: "RESERVED_NAME",
-        message: `Input field '${fieldName}' starts with '__' which is reserved for GraphQL introspection`,
+        message: `${prefix} '${fieldName}' starts with '__' which is reserved for GraphQL introspection`,
       },
     };
   }
@@ -72,7 +56,7 @@ export function isEligibleAsInputObjectField(
       eligible: false,
       skipReason: {
         code: "INVALID_NAME",
-        message: `Input field '${fieldName}' is not a valid GraphQL identifier (must match /^[_A-Za-z][_0-9A-Za-z]*$/)`,
+        message: `${prefix} '${fieldName}' is not a valid GraphQL identifier (must match /^[_A-Za-z][_0-9A-Za-z]*$/)`,
       },
     };
   }

package/src/type-extractor/converter/graphql-converter.ts

@@ -7,6 +7,7 @@ import {
   detectEnumPrefix,
   stripEnumPrefix,
 } from "../../shared/enum-prefix-detector.js";
+import { toScreamingSnakeCase } from "../../shared/string-utils.js";
 import { convertTsTypeToGraphQLType } from "../../shared/type-converter.js";
 import type {
   Diagnostic,
@@ -19,11 +20,7 @@ import type {
   InlineObjectProperty,
   SourceLocation,
 } from "../types/index.js";
-import {
-  isEligibleAsEnumValue,
-  isEligibleAsInputObjectField,
-  isEligibleAsObjectField,
-} from "./field-eligibility.js";
+import { isEligibleAsEnumValue, isEligibleField } from "./field-eligibility.js";
 
 export interface ConversionResult {
   readonly types: ReadonlyArray<GraphQLTypeInfo>;
@@ -41,14 +38,6 @@ function isInputTypeName(name: string): boolean {
   return name.endsWith("Input");
 }
 
-function toScreamingSnakeCase(value: string): string {
-  return value
-    .replace(/[-\s]+/g, "_")
-    .replace(/([a-z])([A-Z])/g, "$1_$2")
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
-    .toUpperCase();
-}
-
 interface ConvertEnumMembersParams {
   readonly members: ReadonlyArray<EnumMemberInfo>;
   readonly enumName: string;
@@ -163,9 +152,10 @@ function convertFields(
   const diagnostics: Diagnostic[] = [];
 
   for (const field of extracted.fields) {
-    const eligibility = isInput
-      ? isEligibleAsInputObjectField(field.name)
-      : isEligibleAsObjectField(field.name);
+    const eligibility = isEligibleField({
+      fieldName: field.name,
+      kind: isInput ? "input" : "object",
+    });
 
     if (!eligibility.eligible) {
       diagnostics.push({

package/src/type-extractor/extractor/field-type-resolver.ts

@@ -1,4 +1,8 @@
 import ts from "typescript";
+import {
+  detectBrandedType,
+  detectUniformBrandedType,
+} from "../../shared/branded-type-detector.js";
 import { isInternalTypeSymbol } from "../../shared/constants.js";
 import { extractInlineObjectProperties as extractInlineObjectPropertiesShared } from "../../shared/inline-object-extractor.js";
 import { isInlineObjectType } from "../../shared/inline-object-utils.js";
@@ -175,6 +179,20 @@ function resolveFieldTypeInternal(
       });
     }
 
+    // Check if all non-null types are branded primitives with the same base type
+    // This handles cases like: boolean & { __nominal: true }
+    // which expands to: (true & { __nominal: true }) | (false & { __nominal: true })
+    const uniformBrandedResult = detectUniformBrandedType(nonNullTypes);
+    if (
+      uniformBrandedResult.isBranded &&
+      uniformBrandedResult.baseType !== null
+    ) {
+      return createPrimitiveType({
+        name: uniformBrandedResult.baseType,
+        nullable,
+      });
+    }
+
     if (nonNullTypes.length === 1) {
       const nonNullTypeNode =
         typeNode && ts.isUnionTypeNode(typeNode)
@@ -235,18 +253,45 @@ function resolveFieldTypeInternal(
     return createLiteralType(typeString);
   }
 
-  // Intersection types in field context are ALWAYS treated as inline objects
-  // GraphQL doesn't have intersection types, so we must expand them
+  // Intersection types in field context
+  // GraphQL doesn't have intersection types, so we must resolve them appropriately
   if (type.isIntersection()) {
-    // If the intersection has an alias that's in knownTypeNames, use it
+    // 1. If the intersection has an alias that's in knownTypeNames, use it as reference
     if (type.aliasSymbol) {
       const aliasName = type.aliasSymbol.getName();
       if (isKnownSchemaType(aliasName, type.aliasSymbol, ctx)) {
         return createReferenceType({ name: aliasName, nullable: false });
       }
+
+      // 2. Check if aliasSymbol has a globalTypeMapping (custom scalar)
+      const globalMapping = globalTypeMappings.find(
+        (m) => m.typeName === aliasName,
+      );
+      if (globalMapping) {
+        return createScalarType({
+          name: globalMapping.scalarName,
+          scalarInfo: {
+            scalarName: globalMapping.scalarName,
+            typeName: globalMapping.typeName,
+            baseType: undefined,
+            isCustom: true,
+            only: globalMapping.only,
+          },
+          nullable: false,
+        });
+      }
+    }
+
+    // 3. Check if this is a branded primitive type pattern
+    const brandedResult = detectBrandedType(type);
+    if (brandedResult.isBranded && brandedResult.baseType !== null) {
+      return createPrimitiveType({
+        name: brandedResult.baseType,
+        nullable: false,
+      });
     }
 
-    // Otherwise, treat as inline object
+    // 4. Otherwise, treat as inline object
     return tryExtractAsInlineObject(type, ctx);
   }
 

package/src/type-extractor/types/diagnostics.ts

@@ -41,6 +41,7 @@ export type DiagnosticCode =
   | "CONFIG_INVALID_HOOK_TYPE"
   | "CONFIG_INVALID_HOOK_COMMAND"
   | "CONFIG_INVALID_ONLY_VALUE"
+  | "CONFIG_INVALID_IMPORT_EXTENSION"
   | "CUSTOM_SCALAR_TYPE_NOT_FOUND"
   | "TSCONFIG_NOT_FOUND"
   | "TSCONFIG_PARSE_ERROR"