@constructive-io/graphql-codegen 3.0.4 → 3.1.1

package/core/codegen/templates/client.node.ts

@@ -0,0 +1,350 @@
+/**
+ * GraphQL client configuration and execution (Node.js with undici)
+ *
+ * This is the RUNTIME code that gets copied to generated output.
+ * Uses undici fetch with dispatcher support for localhost DNS resolution.
+ *
+ * NOTE: This file is read at codegen time and written to output.
+ * Any changes here will affect all generated clients.
+ */
+
+import dns from 'node:dns';
+import { Agent, fetch, type RequestInit } from 'undici';
+
+// ============================================================================
+// Localhost DNS Resolution
+// ============================================================================
+
+/**
+ * Check if a hostname is localhost or a localhost subdomain
+ */
+function isLocalhostHostname(hostname: string): boolean {
+  return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+
+/**
+ * Create an undici Agent that resolves *.localhost to 127.0.0.1
+ * This fixes DNS resolution issues on macOS where subdomains like api.localhost
+ * don't resolve automatically (unlike browsers which handle *.localhost).
+ */
+function createLocalhostAgent(): Agent {
+  return new Agent({
+    connect: {
+      lookup(hostname, opts, cb) {
+        if (isLocalhostHostname(hostname)) {
+          // When opts.all is true, callback expects an array of {address, family} objects
+          // When opts.all is false/undefined, callback expects (err, address, family)
+          if (opts.all) {
+            cb(null, [{ address: '127.0.0.1', family: 4 }]);
+          } else {
+            cb(null, '127.0.0.1', 4);
+          }
+          return;
+        }
+        dns.lookup(hostname, opts, cb);
+      },
+    },
+  });
+}
+
+let localhostAgent: Agent | null = null;
+
+function getLocalhostAgent(): Agent {
+  if (!localhostAgent) {
+    localhostAgent = createLocalhostAgent();
+  }
+  return localhostAgent;
+}
+
+/**
+ * Get fetch options with localhost agent if needed
+ */
+function getFetchOptions(
+  endpoint: string,
+  baseOptions: RequestInit
+): RequestInit {
+  const url = new URL(endpoint);
+  if (isLocalhostHostname(url.hostname)) {
+    const options: RequestInit = {
+      ...baseOptions,
+      dispatcher: getLocalhostAgent(),
+    };
+    // Set Host header for localhost subdomains to preserve routing
+    if (url.hostname !== 'localhost') {
+      options.headers = {
+        ...(baseOptions.headers as Record<string, string>),
+        Host: url.hostname,
+      };
+    }
+    return options;
+  }
+  return baseOptions;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface GraphQLClientConfig {
+  /** GraphQL endpoint URL */
+  endpoint: string;
+  /** Default headers to include in all requests */
+  headers?: Record<string, string>;
+}
+
+let globalConfig: GraphQLClientConfig | null = null;
+
+/**
+ * Configure the GraphQL client
+ *
+ * @example
+ * ```ts
+ * import { configure } from './generated';
+ *
+ * configure({
+ *   endpoint: 'https://api.example.com/graphql',
+ *   headers: {
+ *     Authorization: 'Bearer <token>',
+ *   },
+ * });
+ * ```
+ */
+export function configure(config: GraphQLClientConfig): void {
+  globalConfig = config;
+}
+
+/**
+ * Get the current configuration
+ * @throws Error if not configured
+ */
+export function getConfig(): GraphQLClientConfig {
+  if (!globalConfig) {
+    throw new Error(
+      'GraphQL client not configured. Call configure() before making requests.'
+    );
+  }
+  return globalConfig;
+}
+
+/**
+ * Set a single header value
+ * Useful for updating Authorization after login
+ *
+ * @example
+ * ```ts
+ * setHeader('Authorization', 'Bearer <new-token>');
+ * ```
+ */
+export function setHeader(key: string, value: string): void {
+  const config = getConfig();
+  globalConfig = {
+    ...config,
+    headers: { ...config.headers, [key]: value },
+  };
+}
+
+/**
+ * Merge multiple headers into the current configuration
+ *
+ * @example
+ * ```ts
+ * setHeaders({ Authorization: 'Bearer <token>', 'X-Custom': 'value' });
+ * ```
+ */
+export function setHeaders(headers: Record<string, string>): void {
+  const config = getConfig();
+  globalConfig = {
+    ...config,
+    headers: { ...config.headers, ...headers },
+  };
+}
+
+// ============================================================================
+// Error handling
+// ============================================================================
+
+export interface GraphQLError {
+  message: string;
+  locations?: Array<{ line: number; column: number }>;
+  path?: Array<string | number>;
+  extensions?: Record<string, unknown>;
+}
+
+export class GraphQLClientError extends Error {
+  constructor(
+    message: string,
+    public errors: GraphQLError[],
+    public response?: Response
+  ) {
+    super(message);
+    this.name = 'GraphQLClientError';
+  }
+}
+
+// ============================================================================
+// Execution
+// ============================================================================
+
+export interface ExecuteOptions {
+  /** Override headers for this request */
+  headers?: Record<string, string>;
+  /** AbortSignal for request cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Execute a GraphQL operation
+ *
+ * @example
+ * ```ts
+ * const result = await execute<CarsQueryResult, CarsQueryVariables>(
+ *   carsQueryDocument,
+ *   { first: 10 }
+ * );
+ * ```
+ */
+export async function execute<
+  TData = unknown,
+  TVariables = Record<string, unknown>,
+>(
+  document: string,
+  variables?: TVariables,
+  options?: ExecuteOptions
+): Promise<TData> {
+  const config = getConfig();
+
+  const baseOptions: RequestInit = {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...config.headers,
+      ...options?.headers,
+    },
+    body: JSON.stringify({
+      query: document,
+      variables,
+    }),
+    signal: options?.signal,
+  };
+
+  const fetchOptions = getFetchOptions(config.endpoint, baseOptions);
+  const response = await fetch(config.endpoint, fetchOptions);
+
+  const json = (await response.json()) as {
+    data?: TData;
+    errors?: GraphQLError[];
+  };
+
+  if (json.errors && json.errors.length > 0) {
+    throw new GraphQLClientError(
+      json.errors[0].message || 'GraphQL request failed',
+      json.errors,
+      response as unknown as Response
+    );
+  }
+
+  return json.data as TData;
+}
+
+/**
+ * Execute a GraphQL operation with full response (data + errors)
+ * Useful when you want to handle partial data with errors
+ */
+export async function executeWithErrors<
+  TData = unknown,
+  TVariables = Record<string, unknown>,
+>(
+  document: string,
+  variables?: TVariables,
+  options?: ExecuteOptions
+): Promise<{ data: TData | null; errors: GraphQLError[] | null }> {
+  const config = getConfig();
+
+  const baseOptions: RequestInit = {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...config.headers,
+      ...options?.headers,
+    },
+    body: JSON.stringify({
+      query: document,
+      variables,
+    }),
+    signal: options?.signal,
+  };
+
+  const fetchOptions = getFetchOptions(config.endpoint, baseOptions);
+  const response = await fetch(config.endpoint, fetchOptions);
+
+  const json = (await response.json()) as {
+    data?: TData;
+    errors?: GraphQLError[];
+  };
+
+  return {
+    data: json.data ?? null,
+    errors: json.errors ?? null,
+  };
+}
+
+// ============================================================================
+// QueryClient Factory
+// ============================================================================
+
+/**
+ * Default QueryClient configuration optimized for GraphQL
+ *
+ * These defaults provide a good balance between freshness and performance:
+ * - staleTime: 1 minute - data considered fresh, won't refetch
+ * - gcTime: 5 minutes - unused data kept in cache
+ * - refetchOnWindowFocus: false - don't refetch when tab becomes active
+ * - retry: 1 - retry failed requests once
+ */
+export const defaultQueryClientOptions = {
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60, // 1 minute
+      gcTime: 1000 * 60 * 5, // 5 minutes
+      refetchOnWindowFocus: false,
+      retry: 1,
+    },
+  },
+};
+
+/**
+ * QueryClient options type for createQueryClient
+ */
+export interface CreateQueryClientOptions {
+  defaultOptions?: {
+    queries?: {
+      staleTime?: number;
+      gcTime?: number;
+      refetchOnWindowFocus?: boolean;
+      retry?: number | boolean;
+      retryDelay?: number | ((attemptIndex: number) => number);
+    };
+    mutations?: {
+      retry?: number | boolean;
+      retryDelay?: number | ((attemptIndex: number) => number);
+    };
+  };
+}
+
+// Note: createQueryClient is available when using with @tanstack/react-query
+// Import QueryClient from '@tanstack/react-query' and use these options:
+//
+// import { QueryClient } from '@tanstack/react-query';
+// const queryClient = new QueryClient(defaultQueryClientOptions);
+//
+// Or merge with your own options:
+// const queryClient = new QueryClient({
+//   ...defaultQueryClientOptions,
+//   defaultOptions: {
+//     ...defaultQueryClientOptions.defaultOptions,
+//     queries: {
+//       ...defaultQueryClientOptions.defaultOptions.queries,
+//       staleTime: 30000, // Override specific options
+//     },
+//   },
+// });

package/core/codegen/templates/orm-client.ts

@@ -0,0 +1,158 @@
+/**
+ * ORM Client - Runtime GraphQL executor
+ *
+ * This is the RUNTIME code that gets copied to generated output.
+ * Provides the core ORM client functionality for executing GraphQL operations.
+ *
+ * NOTE: This file is read at codegen time and written to output.
+ * Any changes here will affect all generated ORM clients.
+ */
+
+import type {
+  GraphQLAdapter,
+  GraphQLError,
+  QueryResult,
+} from '@constructive-io/graphql-types';
+
+export type {
+  GraphQLAdapter,
+  GraphQLError,
+  QueryResult,
+} from '@constructive-io/graphql-types';
+
+/**
+ * Default adapter that uses fetch for HTTP requests.
+ * This is used when no custom adapter is provided.
+ */
+export class FetchAdapter implements GraphQLAdapter {
+  private headers: Record<string, string>;
+
+  constructor(
+    private endpoint: string,
+    headers?: Record<string, string>
+  ) {
+    this.headers = headers ?? {};
+  }
+
+  async execute<T>(
+    document: string,
+    variables?: Record<string, unknown>
+  ): Promise<QueryResult<T>> {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...this.headers,
+      },
+      body: JSON.stringify({
+        query: document,
+        variables: variables ?? {},
+      }),
+    });
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        data: null,
+        errors: [{ message: `HTTP ${response.status}: ${response.statusText}` }],
+      };
+    }
+
+    const json = (await response.json()) as {
+      data?: T;
+      errors?: GraphQLError[];
+    };
+
+    if (json.errors && json.errors.length > 0) {
+      return {
+        ok: false,
+        data: null,
+        errors: json.errors,
+      };
+    }
+
+    return {
+      ok: true,
+      data: json.data as T,
+      errors: undefined,
+    };
+  }
+
+  setHeaders(headers: Record<string, string>): void {
+    this.headers = { ...this.headers, ...headers };
+  }
+
+  getEndpoint(): string {
+    return this.endpoint;
+  }
+}
+
+/**
+ * Configuration for creating an ORM client.
+ * Either provide endpoint (and optional headers) for HTTP requests,
+ * or provide a custom adapter for alternative execution strategies.
+ */
+export interface OrmClientConfig {
+  /** GraphQL endpoint URL (required if adapter not provided) */
+  endpoint?: string;
+  /** Default headers for HTTP requests (only used with endpoint) */
+  headers?: Record<string, string>;
+  /** Custom adapter for GraphQL execution (overrides endpoint/headers) */
+  adapter?: GraphQLAdapter;
+}
+
+/**
+ * Error thrown when GraphQL request fails
+ */
+export class GraphQLRequestError extends Error {
+  constructor(
+    public readonly errors: GraphQLError[],
+    public readonly data: unknown = null
+  ) {
+    const messages = errors.map((e) => e.message).join('; ');
+    super(`GraphQL Error: ${messages}`);
+    this.name = 'GraphQLRequestError';
+  }
+}
+
+export class OrmClient {
+  private adapter: GraphQLAdapter;
+
+  constructor(config: OrmClientConfig) {
+    if (config.adapter) {
+      this.adapter = config.adapter;
+    } else if (config.endpoint) {
+      this.adapter = new FetchAdapter(config.endpoint, config.headers);
+    } else {
+      throw new Error(
+        'OrmClientConfig requires either an endpoint or a custom adapter'
+      );
+    }
+  }
+
+  async execute<T>(
+    document: string,
+    variables?: Record<string, unknown>
+  ): Promise<QueryResult<T>> {
+    return this.adapter.execute<T>(document, variables);
+  }
+
+  /**
+   * Set headers for requests.
+   * Only works if the adapter supports headers.
+   */
+  setHeaders(headers: Record<string, string>): void {
+    if (this.adapter.setHeaders) {
+      this.adapter.setHeaders(headers);
+    }
+  }
+
+  /**
+   * Get the endpoint URL.
+   * Returns empty string if the adapter doesn't have an endpoint.
+   */
+  getEndpoint(): string {
+    return this.adapter.getEndpoint?.() ?? '';
+  }
+}

package/core/codegen/templates/select-types.ts

@@ -0,0 +1,116 @@
+/**
+ * Type utilities for select inference
+ *
+ * This is the RUNTIME code that gets copied to generated output.
+ * Provides type utilities for ORM select operations.
+ *
+ * NOTE: This file is read at codegen time and written to output.
+ * Any changes here will affect all generated ORM clients.
+ */
+
+export interface ConnectionResult<T> {
+  nodes: T[];
+  totalCount: number;
+  pageInfo: PageInfo;
+}
+
+export interface PageInfo {
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  startCursor?: string | null;
+  endCursor?: string | null;
+}
+
+export interface FindManyArgs<TSelect, TWhere, TOrderBy> {
+  select?: TSelect;
+  where?: TWhere;
+  orderBy?: TOrderBy[];
+  first?: number;
+  last?: number;
+  after?: string;
+  before?: string;
+  offset?: number;
+}
+
+export interface FindFirstArgs<TSelect, TWhere> {
+  select?: TSelect;
+  where?: TWhere;
+}
+
+export interface CreateArgs<TSelect, TData> {
+  data: TData;
+  select?: TSelect;
+}
+
+export interface UpdateArgs<TSelect, TWhere, TData> {
+  where: TWhere;
+  data: TData;
+  select?: TSelect;
+}
+
+export interface DeleteArgs<TWhere> {
+  where: TWhere;
+}
+
+/**
+ * Recursively validates select objects, rejecting unknown keys.
+ *
+ * This type ensures that users can only select fields that actually exist
+ * in the GraphQL schema. It returns `never` if any excess keys are found
+ * at any nesting level, causing a TypeScript compile error.
+ *
+ * Why this is needed:
+ * TypeScript's excess property checking has a quirk where it only catches
+ * invalid fields when they are the ONLY fields. When mixed with valid fields
+ * (e.g., `{ id: true, invalidField: true }`), the structural typing allows
+ * the excess property through. This type explicitly checks for and rejects
+ * such cases.
+ *
+ * @example
+ * // This will cause a type error because 'invalid' doesn't exist:
+ * type Result = DeepExact<{ id: true, invalid: true }, { id?: boolean }>;
+ * // Result = never (causes assignment error)
+ *
+ * @example
+ * // This works because all fields are valid:
+ * type Result = DeepExact<{ id: true }, { id?: boolean; name?: boolean }>;
+ * // Result = { id: true }
+ */
+export type DeepExact<T, Shape> = T extends Shape
+  ? Exclude<keyof T, keyof Shape> extends never
+    ? {
+        [K in keyof T]: K extends keyof Shape
+          ? T[K] extends { select: infer NS }
+            ? Shape[K] extends { select?: infer ShapeNS }
+              ? { select: DeepExact<NS, NonNullable<ShapeNS>> }
+              : T[K]
+            : T[K]
+          : never;
+      }
+    : never
+  : never;
+
+/**
+ * Infer result type from select configuration
+ */
+export type InferSelectResult<TEntity, TSelect> = TSelect extends undefined
+  ? TEntity
+  : {
+      [K in keyof TSelect as TSelect[K] extends false | undefined
+        ? never
+        : K]: TSelect[K] extends true
+        ? K extends keyof TEntity
+          ? TEntity[K]
+          : never
+        : TSelect[K] extends { select: infer NestedSelect }
+          ? K extends keyof TEntity
+            ? NonNullable<TEntity[K]> extends ConnectionResult<infer NodeType>
+              ? ConnectionResult<InferSelectResult<NodeType, NestedSelect>>
+              :
+                  | InferSelectResult<NonNullable<TEntity[K]>, NestedSelect>
+                  | (null extends TEntity[K] ? null : never)
+            : never
+          : K extends keyof TEntity
+            ? TEntity[K]
+            : never;
+    };

package/core/introspect/fetch-schema.js

@@ -26,7 +26,14 @@ function createLocalhostAgent() {
         connect: {
             lookup(hostname, opts, cb) {
                 if (isLocalhostHostname(hostname)) {
-                    cb(null, '127.0.0.1', 4);
+                    // When opts.all is true, callback expects an array of {address, family} objects
+                    // When opts.all is false/undefined, callback expects (err, address, family)
+                    if (opts.all) {
+                        cb(null, [{ address: '127.0.0.1', family: 4 }]);
+                    }
+                    else {
+                        cb(null, '127.0.0.1', 4);
+                    }
                     return;
                 }
                 node_dns_1.default.lookup(hostname, opts, cb);
@@ -65,7 +72,7 @@ async function fetchSchema(options) {
     // Create abort controller for timeout
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
-    // Build fetch options
+    // Build fetch options using undici's RequestInit type
     const fetchOptions = {
         method: 'POST',
         headers: requestHeaders,
@@ -80,7 +87,7 @@ async function fetchSchema(options) {
         fetchOptions.dispatcher = getLocalhostAgent();
     }
     try {
-        const response = await fetch(endpoint, fetchOptions);
+        const response = await (0, undici_1.fetch)(endpoint, fetchOptions);
         clearTimeout(timeoutId);
         if (!response.ok) {
             return {

package/esm/cli/index.js

@@ -30,6 +30,8 @@ Generator Options:
   -o, --output <dir>            Output directory
   -t, --target <name>           Target name (for multi-target configs)
   -a, --authorization <token>   Authorization header value
+  --browser-compatible          Generate browser-compatible code (default: true)
+                                Set to false for Node.js with localhost DNS fix
   --dry-run                     Preview without writing files
   -v, --verbose                 Show detailed output
 
@@ -102,6 +104,7 @@ export const commands = async (argv, prompter, _options) => {
         authorization: answers.authorization,
         reactQuery: answers.reactQuery,
         orm: answers.orm,
+        browserCompatible: answers.browserCompatible,
         dryRun: answers.dryRun,
         verbose: answers.verbose,
     });
@@ -122,7 +125,7 @@ export const options = {
             v: 'verbose',
         },
         boolean: [
-            'help', 'version', 'verbose', 'dry-run', 'react-query', 'orm', 'keep-db',
+            'help', 'version', 'verbose', 'dry-run', 'react-query', 'orm', 'keep-db', 'browser-compatible',
         ],
         string: [
             'config', 'endpoint', 'schema-file', 'output', 'target', 'authorization',

package/esm/cli/shared.d.ts

@@ -21,6 +21,7 @@ export interface CodegenAnswers {
     apiNames?: string[];
     reactQuery?: boolean;
     orm?: boolean;
+    browserCompatible?: boolean;
     authorization?: string;
     dryRun?: boolean;
     verbose?: boolean;

package/esm/cli/shared.js

@@ -60,6 +60,14 @@ export const codegenQuestions = [
         default: false,
         useDefault: true,
     },
+    {
+        name: 'browserCompatible',
+        message: 'Generate browser-compatible code?',
+        type: 'confirm',
+        required: false,
+        default: true,
+        useDefault: true,
+    },
     {
         name: 'authorization',
         message: 'Authorization header value',