@constructive-io/graphql-codegen 3.0.3 → 3.1.0

package/esm/core/codegen/orm/client-generator.js

@@ -4,322 +4,61 @@ import { getTableNames, lcFirst, getGeneratedFileHeader } from '../utils';
 import * as fs from 'fs';
 import * as path from 'path';
 /**
- * Generate the main client.ts file (OrmClient class)
- * This is the runtime client that handles GraphQL execution
- */
-export function generateOrmClientFile() {
-    // This is runtime code that doesn't change based on schema
-    // We generate it as a static file
-    const content = `/**
- * ORM Client - Runtime GraphQL executor
- * @generated by @constructive-io/graphql-codegen
- * DO NOT EDIT - changes will be overwritten
- */
-
-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.
+ * Find a template file path.
+ * Templates are at ../templates/ relative to this file in both src/ and dist/.
  */
-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}\` }],
-      };
+function findTemplateFile(templateName) {
+    const templatePath = path.join(__dirname, '../templates', templateName);
+    if (fs.existsSync(templatePath)) {
+        return templatePath;
     }
-
-    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;
-  }
+    throw new Error(`Could not find template file: ${templateName}. ` +
+        `Searched in: ${templatePath}`);
 }
-
 /**
- * Configuration for creating an ORM client.
- * Either provide endpoint (and optional headers) for HTTP requests,
- * or provide a custom adapter for alternative execution strategies.
+ * Read a template file and replace the header with generated file header
  */
-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;
+function readTemplateFile(templateName, description) {
+    const templatePath = findTemplateFile(templateName);
+    let content = fs.readFileSync(templatePath, 'utf-8');
+    // Replace the source file header comment with the generated file header
+    // Match the header pattern used in template files
+    const headerPattern = /\/\*\*[\s\S]*?\* NOTE: This file is read at codegen time and written to output\.[\s\S]*?\*\/\n*/;
+    content = content.replace(headerPattern, getGeneratedFileHeader(description) + '\n');
+    return content;
 }
-
 /**
- * Error thrown when GraphQL request fails
+ * Generate the main client.ts file (OrmClient class)
+ * This is the runtime client that handles GraphQL execution
+ *
+ * Reads from the templates directory for proper type checking.
  */
-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?.() ?? '';
-  }
-}
-`;
+export function generateOrmClientFile() {
     return {
         fileName: 'client.ts',
-        content,
+        content: readTemplateFile('orm-client.ts', 'ORM Client - Runtime GraphQL executor'),
     };
 }
 /**
  * Generate the query-builder.ts file (runtime query builder)
  *
- * Reads from the actual TypeScript file in the source directory,
- * which enables proper type checking and testability.
+ * Reads from the templates directory for proper type checking and testability.
  */
 export function generateQueryBuilderFile() {
-    // Read the query-builder.ts source file
-    // Handle both development (src/) and production (dist/) scenarios
-    let sourceFilePath = path.join(__dirname, 'query-builder.ts');
-    // If running from dist/, look for the source in src/ instead
-    if (!fs.existsSync(sourceFilePath)) {
-        // Navigate from dist/cli/codegen/orm/ to src/cli/codegen/orm/
-        sourceFilePath = path.resolve(__dirname, '../../../../src/cli/codegen/orm/query-builder.ts');
-    }
-    // If still not found, try relative to package root
-    if (!fs.existsSync(sourceFilePath)) {
-        // For installed packages, the file should be adjacent in the same dir
-        throw new Error(`Could not find query-builder.ts source file. ` +
-            `Searched in: ${path.join(__dirname, 'query-builder.ts')} and ` +
-            `${path.resolve(__dirname, '../../../../src/cli/codegen/orm/query-builder.ts')}`);
-    }
-    let sourceContent = fs.readFileSync(sourceFilePath, 'utf-8');
-    // Replace the source file header comment with the generated file header
-    const headerComment = `/**
- * Query Builder - Builds and executes GraphQL operations
- *
- * This is the RUNTIME code that gets copied to generated output.
- * It uses gql-ast to build GraphQL documents programmatically.
- *
- * NOTE: This file is read at codegen time and written to output.
- * Any changes here will affect all generated ORM clients.
- */`;
-    const generatedHeader = `/**
- * Query Builder - Builds and executes GraphQL operations
- * @generated by @constructive-io/graphql-codegen
- * DO NOT EDIT - changes will be overwritten
- */`;
-    sourceContent = sourceContent.replace(headerComment, generatedHeader);
     return {
         fileName: 'query-builder.ts',
-        content: sourceContent,
+        content: readTemplateFile('query-builder.ts', 'Query Builder - Builds and executes GraphQL operations'),
     };
 }
 /**
  * Generate the select-types.ts file
- */
-export function generateSelectTypesFile() {
-    const content = `/**
- * Type utilities for select inference
- * @generated by @constructive-io/graphql-codegen
- * DO NOT EDIT - changes will be overwritten
- */
-
-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
+ * Reads from the templates directory for proper type checking.
  */
-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;
-    };
-`;
+export function generateSelectTypesFile() {
     return {
         fileName: 'select-types.ts',
-        content,
+        content: readTemplateFile('select-types.ts', 'Type utilities for select inference'),
     };
 }
 function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false) {

package/esm/core/generate.js

@@ -8,6 +8,7 @@ import path from 'path';
 import { createSchemaSource, validateSourceOptions } from './introspect';
 import { runCodegenPipeline, validateTablesFound } from './pipeline';
 import { generate as generateReactQueryFiles } from './codegen';
+import { generateRootBarrel } from './codegen/barrel';
 import { generateOrm as generateOrmFiles } from './codegen/orm';
 import { generateSharedTypes } from './codegen/shared';
 import { writeGeneratedFiles } from './output';
@@ -161,16 +162,14 @@ export async function generate(options = {}) {
             allFilesWritten.push(...(writeResult.filesWritten ?? []));
         }
     }
-    // Generate unified barrel when both are enabled
-    if (bothEnabled && !options.dryRun) {
-        const barrelContent = `/**
- * Generated SDK - auto-generated, do not edit
- * @generated by @constructive-io/graphql-codegen
- */
-export * from './types';
-export * from './hooks';
-export * from './orm';
-`;
+    // Generate barrel file at output root
+    // This re-exports from the appropriate subdirectories based on which generators are enabled
+    if (!options.dryRun) {
+        const barrelContent = generateRootBarrel({
+            hasTypes: bothEnabled,
+            hasHooks: runReactQuery,
+            hasOrm: runOrm,
+        });
         await writeGeneratedFiles([{ path: 'index.ts', content: barrelContent }], outputRoot, []);
     }
     const generators = [runReactQuery && 'React Query', runOrm && 'ORM'].filter(Boolean).join(' and ');

package/esm/core/introspect/fetch-schema.js

@@ -2,7 +2,7 @@
  * Fetch GraphQL schema introspection from an endpoint
  */
 import dns from 'node:dns';
-import { Agent } from 'undici';
+import { Agent, fetch } from 'undici';
 import { SCHEMA_INTROSPECTION_QUERY } from './schema-query';
 /**
  * Check if a hostname is localhost or a localhost subdomain
@@ -20,7 +20,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;
                 }
                 dns.lookup(hostname, opts, cb);
@@ -59,7 +66,7 @@ export 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,

package/esm/types/config.d.ts

@@ -223,6 +223,14 @@ export interface GraphQLSDKConfigTarget {
      * @default false
      */
     reactQuery?: boolean;
+    /**
+     * Generate browser-compatible code using native fetch
+     * When true (default), uses native W3C fetch API (works in browsers and Node.js)
+     * When false, uses undici fetch with dispatcher support for localhost DNS resolution
+     * (Node.js only - enables proper *.localhost subdomain resolution on macOS)
+     * @default true
+     */
+    browserCompatible?: boolean;
     /**
      * Query key generation configuration
      * Controls how query keys are structured for cache management

package/esm/types/config.js

@@ -64,6 +64,7 @@ export const DEFAULT_CONFIG = {
     },
     orm: false,
     reactQuery: false,
+    browserCompatible: true,
     queryKeys: DEFAULT_QUERY_KEY_CONFIG,
     watch: DEFAULT_WATCH_CONFIG,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "GraphQL SDK generator for Constructive databases with React Query hooks",
   "keywords": [
     "graphql",
@@ -35,9 +35,9 @@
   "scripts": {
     "clean": "makage clean",
     "prepack": "npm run build",
-    "copy:ts": "makage copy src/core/codegen/orm/query-builder.ts dist/core/codegen/orm --flat",
-    "build": "makage build && npm run copy:ts",
-    "build:dev": "makage build --dev && npm run copy:ts",
+    "copy:templates": "mkdir -p dist/core/codegen/templates && cp src/core/codegen/templates/*.ts dist/core/codegen/templates/",
+    "build": "makage build && npm run copy:templates",
+    "build:dev": "makage build --dev && npm run copy:templates",
     "dev": "ts-node ./src/index.ts",
     "lint": "eslint . --fix",
     "fmt": "oxfmt --write .",
@@ -99,5 +99,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "532b9bae03b2a77fd5dff4981ad2a775bb27397a"
+  "gitHead": "feaeaaeb78656bccab7725854fb1cfc4e724ba0a"
 }

package/types/config.d.ts

@@ -223,6 +223,14 @@ export interface GraphQLSDKConfigTarget {
      * @default false
      */
     reactQuery?: boolean;
+    /**
+     * Generate browser-compatible code using native fetch
+     * When true (default), uses native W3C fetch API (works in browsers and Node.js)
+     * When false, uses undici fetch with dispatcher support for localhost DNS resolution
+     * (Node.js only - enables proper *.localhost subdomain resolution on macOS)
+     * @default true
+     */
+    browserCompatible?: boolean;
     /**
      * Query key generation configuration
      * Controls how query keys are structured for cache management

package/types/config.js

@@ -73,6 +73,7 @@ exports.DEFAULT_CONFIG = {
     },
     orm: false,
     reactQuery: false,
+    browserCompatible: true,
     queryKeys: exports.DEFAULT_QUERY_KEY_CONFIG,
     watch: exports.DEFAULT_WATCH_CONFIG,
 };

package/core/codegen/orm/query-builder.d.ts

@@ -1,85 +0,0 @@
-/**
- * Query Builder - Builds and executes GraphQL operations
- *
- * This is the RUNTIME code that gets copied to generated output.
- * It uses gql-ast to build GraphQL documents programmatically.
- *
- * NOTE: This file is read at codegen time and written to output.
- * Any changes here will affect all generated ORM clients.
- */
-import type { FieldNode } from 'graphql';
-import { OrmClient, QueryResult } from './client';
-export interface QueryBuilderConfig {
-    client: OrmClient;
-    operation: 'query' | 'mutation';
-    operationName: string;
-    fieldName: string;
-    document: string;
-    variables?: Record<string, unknown>;
-}
-export declare class QueryBuilder<TResult> {
-    private config;
-    constructor(config: QueryBuilderConfig);
-    /**
-     * Execute the query and return a discriminated union result
-     * Use result.ok to check success, or .unwrap() to throw on error
-     */
-    execute(): Promise<QueryResult<TResult>>;
-    /**
-     * Execute and unwrap the result, throwing GraphQLRequestError on failure
-     * @throws {GraphQLRequestError} If the query returns errors
-     */
-    unwrap(): Promise<TResult>;
-    /**
-     * Execute and unwrap, returning defaultValue on error instead of throwing
-     */
-    unwrapOr<D>(defaultValue: D): Promise<TResult | D>;
-    /**
-     * Execute and unwrap, calling onError callback on failure
-     */
-    unwrapOrElse<D>(onError: (errors: import('./client').GraphQLError[]) => D): Promise<TResult | D>;
-    toGraphQL(): string;
-    getVariables(): Record<string, unknown> | undefined;
-}
-export declare function buildSelections(select: Record<string, unknown> | undefined): FieldNode[];
-export declare function buildFindManyDocument<TSelect, TWhere>(operationName: string, queryField: string, select: TSelect, args: {
-    where?: TWhere;
-    orderBy?: string[];
-    first?: number;
-    last?: number;
-    after?: string;
-    before?: string;
-    offset?: number;
-}, filterTypeName: string, orderByTypeName: string): {
-    document: string;
-    variables: Record<string, unknown>;
-};
-export declare function buildFindFirstDocument<TSelect, TWhere>(operationName: string, queryField: string, select: TSelect, args: {
-    where?: TWhere;
-}, filterTypeName: string): {
-    document: string;
-    variables: Record<string, unknown>;
-};
-export declare function buildCreateDocument<TSelect, TData>(operationName: string, mutationField: string, entityField: string, select: TSelect, data: TData, inputTypeName: string): {
-    document: string;
-    variables: Record<string, unknown>;
-};
-export declare function buildUpdateDocument<TSelect, TWhere extends {
-    id: string;
-}, TData>(operationName: string, mutationField: string, entityField: string, select: TSelect, where: TWhere, data: TData, inputTypeName: string): {
-    document: string;
-    variables: Record<string, unknown>;
-};
-export declare function buildDeleteDocument<TWhere extends {
-    id: string;
-}>(operationName: string, mutationField: string, entityField: string, where: TWhere, inputTypeName: string): {
-    document: string;
-    variables: Record<string, unknown>;
-};
-export declare function buildCustomDocument<TSelect, TArgs>(operationType: 'query' | 'mutation', operationName: string, fieldName: string, select: TSelect, args: TArgs, variableDefinitions: Array<{
-    name: string;
-    type: string;
-}>): {
-    document: string;
-    variables: Record<string, unknown>;
-};