@constructive-io/graphql-codegen 2.22.1 → 2.23.0

package/esm/cli/introspect/pluralize.js

@@ -0,0 +1,83 @@
+/**
+ * Pluralization utilities for inferring entity names from PostGraphile patterns
+ *
+ * Uses the 'inflection' package which is already a dependency of this package.
+ */
+import * as inflection from 'inflection';
+/**
+ * Latin plural suffixes that inflection handles differently than PostGraphile.
+ *
+ * The inflection library correctly singularizes Latin words (schemata → schematum),
+ * but PostGraphile uses English-style naming (schemata → schema).
+ *
+ * Format: [pluralSuffix, singularSuffix]
+ */
+const LATIN_SUFFIX_OVERRIDES = [
+    // Common Latin plural endings
+    ['schemata', 'schema'],
+    ['criteria', 'criterion'],
+    ['phenomena', 'phenomenon'],
+    ['media', 'medium'],
+    ['memoranda', 'memorandum'],
+    ['strata', 'stratum'],
+    ['curricula', 'curriculum'],
+    ['data', 'datum'],
+];
+/**
+ * Convert a word to its singular form
+ * @example "Users" → "User", "People" → "Person", "Schemata" → "Schema", "ApiSchemata" → "ApiSchema"
+ */
+export function singularize(word) {
+    // Check for Latin suffix overrides (handles compound words like "ApiSchemata")
+    const lowerWord = word.toLowerCase();
+    for (const [pluralSuffix, singularSuffix] of LATIN_SUFFIX_OVERRIDES) {
+        if (lowerWord.endsWith(pluralSuffix)) {
+            // Find where the suffix starts in the original word (preserving case)
+            const suffixStart = word.length - pluralSuffix.length;
+            const prefix = word.slice(0, suffixStart);
+            const originalSuffix = word.slice(suffixStart);
+            // Preserve the casing of the first letter of the suffix
+            const isUpperSuffix = originalSuffix[0] === originalSuffix[0].toUpperCase();
+            const newSuffix = isUpperSuffix
+                ? singularSuffix.charAt(0).toUpperCase() + singularSuffix.slice(1)
+                : singularSuffix;
+            return prefix + newSuffix;
+        }
+    }
+    return inflection.singularize(word);
+}
+/**
+ * Convert a word to its plural form
+ * @example "User" → "Users", "Person" → "People"
+ */
+export function pluralize(word) {
+    return inflection.pluralize(word);
+}
+/**
+ * Convert PascalCase to camelCase
+ * @example "UserProfile" → "userProfile"
+ */
+export function lcFirst(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+/**
+ * Convert camelCase to PascalCase
+ * @example "userProfile" → "UserProfile"
+ */
+export function ucFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+ * Convert a plural PascalCase type name to singular camelCase field name
+ * @example "Users" → "user", "OrderItems" → "orderItem"
+ */
+export function toFieldName(pluralTypeName) {
+    return lcFirst(singularize(pluralTypeName));
+}
+/**
+ * Convert a singular PascalCase type name to plural camelCase query name
+ * @example "User" → "users", "OrderItem" → "orderItems"
+ */
+export function toQueryName(singularTypeName) {
+    return lcFirst(pluralize(singularTypeName));
+}

package/esm/cli/introspect/source/endpoint.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Endpoint Schema Source
+ *
+ * Fetches GraphQL schema via introspection from a live endpoint.
+ * Wraps the existing fetchSchema() function with the SchemaSource interface.
+ */
+import type { SchemaSource, SchemaSourceResult } from './types';
+export interface EndpointSchemaSourceOptions {
+    /**
+     * GraphQL endpoint URL
+     */
+    endpoint: string;
+    /**
+     * Optional authorization header value (e.g., "Bearer token")
+     */
+    authorization?: string;
+    /**
+     * Optional additional headers
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+}
+/**
+ * Schema source that fetches from a live GraphQL endpoint
+ */
+export declare class EndpointSchemaSource implements SchemaSource {
+    private readonly options;
+    constructor(options: EndpointSchemaSourceOptions);
+    fetch(): Promise<SchemaSourceResult>;
+    describe(): string;
+}

package/esm/cli/introspect/source/endpoint.js

@@ -0,0 +1,31 @@
+import { SchemaSourceError } from './types';
+import { fetchSchema } from '../fetch-schema';
+/**
+ * Schema source that fetches from a live GraphQL endpoint
+ */
+export class EndpointSchemaSource {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async fetch() {
+        const result = await fetchSchema({
+            endpoint: this.options.endpoint,
+            authorization: this.options.authorization,
+            headers: this.options.headers,
+            timeout: this.options.timeout,
+        });
+        if (!result.success) {
+            throw new SchemaSourceError(result.error ?? 'Unknown error fetching schema', this.describe());
+        }
+        if (!result.data) {
+            throw new SchemaSourceError('No introspection data returned', this.describe());
+        }
+        return {
+            introspection: result.data,
+        };
+    }
+    describe() {
+        return `endpoint: ${this.options.endpoint}`;
+    }
+}

package/esm/cli/introspect/source/file.d.ts

@@ -0,0 +1,20 @@
+import type { SchemaSource, SchemaSourceResult } from './types';
+export interface FileSchemaSourceOptions {
+    /**
+     * Path to the GraphQL schema file (.graphql)
+     * Can be absolute or relative to current working directory
+     */
+    schemaPath: string;
+}
+/**
+ * Schema source that loads from a local GraphQL schema file
+ *
+ * Supports .graphql files containing SDL (Schema Definition Language).
+ * The SDL is parsed using graphql-js and converted to introspection format.
+ */
+export declare class FileSchemaSource implements SchemaSource {
+    private readonly options;
+    constructor(options: FileSchemaSourceOptions);
+    fetch(): Promise<SchemaSourceResult>;
+    describe(): string;
+}

package/esm/cli/introspect/source/file.js

@@ -0,0 +1,66 @@
+/**
+ * File Schema Source
+ *
+ * Loads GraphQL schema from a local .graphql SDL file and converts it
+ * to introspection format using the graphql package.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { buildSchema, introspectionFromSchema } from 'graphql';
+import { SchemaSourceError } from './types';
+/**
+ * Schema source that loads from a local GraphQL schema file
+ *
+ * Supports .graphql files containing SDL (Schema Definition Language).
+ * The SDL is parsed using graphql-js and converted to introspection format.
+ */
+export class FileSchemaSource {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async fetch() {
+        const absolutePath = path.isAbsolute(this.options.schemaPath)
+            ? this.options.schemaPath
+            : path.resolve(process.cwd(), this.options.schemaPath);
+        // Check file exists
+        if (!fs.existsSync(absolutePath)) {
+            throw new SchemaSourceError(`Schema file not found: ${absolutePath}`, this.describe());
+        }
+        // Read file content
+        let sdl;
+        try {
+            sdl = await fs.promises.readFile(absolutePath, 'utf-8');
+        }
+        catch (err) {
+            throw new SchemaSourceError(`Failed to read schema file: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Validate non-empty
+        if (!sdl.trim()) {
+            throw new SchemaSourceError('Schema file is empty', this.describe());
+        }
+        // Parse SDL to GraphQL schema
+        let schema;
+        try {
+            schema = buildSchema(sdl);
+        }
+        catch (err) {
+            throw new SchemaSourceError(`Invalid GraphQL SDL: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Convert to introspection format
+        let introspectionResult;
+        try {
+            introspectionResult = introspectionFromSchema(schema);
+        }
+        catch (err) {
+            throw new SchemaSourceError(`Failed to generate introspection: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Convert graphql-js introspection result to our mutable type
+        // The graphql-js types are readonly, but our types are mutable
+        const introspection = JSON.parse(JSON.stringify(introspectionResult));
+        return { introspection };
+    }
+    describe() {
+        return `file: ${this.options.schemaPath}`;
+    }
+}

package/esm/cli/introspect/source/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Schema Source Module
+ *
+ * Provides a unified interface for loading GraphQL schemas from different sources:
+ * - Live GraphQL endpoints (via introspection)
+ * - Static .graphql schema files
+ */
+export * from './types';
+export * from './endpoint';
+export * from './file';
+import type { SchemaSource } from './types';
+export interface CreateSchemaSourceOptions {
+    /**
+     * GraphQL endpoint URL (for live introspection)
+     */
+    endpoint?: string;
+    /**
+     * Path to GraphQL schema file (.graphql)
+     */
+    schema?: string;
+    /**
+     * Optional authorization header for endpoint requests
+     */
+    authorization?: string;
+    /**
+     * Optional additional headers for endpoint requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds (for endpoint requests)
+     */
+    timeout?: number;
+}
+/**
+ * Create a schema source based on configuration
+ *
+ * @param options - Source configuration
+ * @returns Appropriate SchemaSource implementation
+ * @throws Error if neither endpoint nor schema is provided
+ */
+export declare function createSchemaSource(options: CreateSchemaSourceOptions): SchemaSource;
+/**
+ * Validate that source options are valid (at least one source specified)
+ */
+export declare function validateSourceOptions(options: CreateSchemaSourceOptions): {
+    valid: boolean;
+    error?: string;
+};

package/esm/cli/introspect/source/index.js

@@ -0,0 +1,54 @@
+/**
+ * Schema Source Module
+ *
+ * Provides a unified interface for loading GraphQL schemas from different sources:
+ * - Live GraphQL endpoints (via introspection)
+ * - Static .graphql schema files
+ */
+export * from './types';
+export * from './endpoint';
+export * from './file';
+import { EndpointSchemaSource } from './endpoint';
+import { FileSchemaSource } from './file';
+/**
+ * Create a schema source based on configuration
+ *
+ * @param options - Source configuration
+ * @returns Appropriate SchemaSource implementation
+ * @throws Error if neither endpoint nor schema is provided
+ */
+export function createSchemaSource(options) {
+    if (options.schema) {
+        return new FileSchemaSource({
+            schemaPath: options.schema,
+        });
+    }
+    if (options.endpoint) {
+        return new EndpointSchemaSource({
+            endpoint: options.endpoint,
+            authorization: options.authorization,
+            headers: options.headers,
+            timeout: options.timeout,
+        });
+    }
+    throw new Error('Either endpoint or schema must be provided. ' +
+        'Use --endpoint for live introspection or --schema for a local file.');
+}
+/**
+ * Validate that source options are valid (at least one source specified)
+ */
+export function validateSourceOptions(options) {
+    if (!options.endpoint && !options.schema) {
+        return {
+            valid: false,
+            error: 'Either endpoint or schema must be provided',
+        };
+    }
+    if (options.endpoint && options.schema) {
+        return {
+            valid: false,
+            error: 'Cannot use both endpoint and schema. Choose one source.',
+        };
+    }
+    return { valid: true };
+}

package/esm/cli/introspect/source/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Schema Source Types
+ *
+ * Defines the interface for schema sources, allowing the codegen pipeline
+ * to work with both live GraphQL endpoints and static schema files.
+ */
+import type { IntrospectionQueryResponse } from '../../../types/introspection';
+/**
+ * Result from fetching a schema source
+ */
+export interface SchemaSourceResult {
+    /**
+     * The GraphQL introspection data
+     */
+    introspection: IntrospectionQueryResponse;
+}
+/**
+ * Abstract interface for schema sources
+ *
+ * Implementations:
+ * - EndpointSchemaSource: Fetches from a live GraphQL endpoint
+ * - FileSchemaSource: Loads from a local .graphql schema file
+ */
+export interface SchemaSource {
+    /**
+     * Fetch or load the GraphQL introspection data
+     * @throws SchemaSourceError if fetching fails
+     */
+    fetch(): Promise<SchemaSourceResult>;
+    /**
+     * Human-readable description of the source (for logging)
+     * @example "endpoint: https://api.example.com/graphql"
+     * @example "file: ./schema.graphql"
+     */
+    describe(): string;
+}
+/**
+ * Error thrown when a schema source fails to fetch
+ */
+export declare class SchemaSourceError extends Error {
+    /**
+     * Description of the source that failed
+     */
+    readonly source: string;
+    /**
+     * Original error that caused the failure
+     */
+    readonly cause?: Error;
+    constructor(message: string, 
+    /**
+     * Description of the source that failed
+     */
+    source: string, 
+    /**
+     * Original error that caused the failure
+     */
+    cause?: Error);
+}

package/esm/cli/introspect/source/types.js

@@ -0,0 +1,23 @@
+/**
+ * Error thrown when a schema source fails to fetch
+ */
+export class SchemaSourceError extends Error {
+    source;
+    cause;
+    constructor(message, 
+    /**
+     * Description of the source that failed
+     */
+    source, 
+    /**
+     * Original error that caused the failure
+     */
+    cause) {
+        super(`${message} (source: ${source})`);
+        this.source = source;
+        this.cause = cause;
+        this.name = 'SchemaSourceError';
+        // Maintain proper prototype chain
+        Object.setPrototypeOf(this, SchemaSourceError.prototype);
+    }
+}

package/esm/cli/introspect/transform.d.ts

@@ -1,12 +1,11 @@
 /**
- * Transform _meta query response to CleanTable[] format
+ * Table utility functions for CleanTable[]
+ *
+ * Note: The _meta transform functions have been removed.
+ * Tables are now inferred from standard GraphQL introspection
+ * using inferTablesFromIntrospection() in ./infer-tables.ts
  */
 import type { CleanTable } from '../../types/schema';
-import type { MetaQueryResponse } from './meta-query';
-/**
- * Transform _meta response to CleanTable array
- */
-export declare function transformMetaToCleanTables(metaResponse: MetaQueryResponse): CleanTable[];
 /**
  * Get table names from CleanTable array
  */

package/esm/cli/introspect/transform.js

@@ -1,175 +1,3 @@
-/**
- * Transform _meta response to CleanTable array
- */
-export function transformMetaToCleanTables(metaResponse) {
-    const { tables } = metaResponse._meta;
-    return tables.map((table) => transformTable(table));
-}
-/**
- * Transform a single MetaTable to CleanTable
- */
-function transformTable(table) {
-    return {
-        name: table.name,
-        fields: transformFields(table.fields),
-        relations: transformRelations(table.relations),
-        inflection: transformInflection(table.inflection),
-        query: transformQuery(table.query),
-        constraints: transformConstraints(table),
-    };
-}
-/**
- * Transform MetaField[] to CleanField[]
- */
-function transformFields(fields) {
-    return fields.map((field) => ({
-        name: field.name,
-        type: transformFieldType(field.type),
-    }));
-}
-/**
- * Transform MetaFieldType to CleanFieldType
- */
-function transformFieldType(type) {
-    return {
-        gqlType: type.gqlType,
-        isArray: type.isArray,
-        modifier: type.modifier,
-        pgAlias: type.pgAlias,
-        pgType: type.pgType,
-        subtype: type.subtype,
-        typmod: type.typmod,
-    };
-}
-/**
- * Transform table relations
- */
-function transformRelations(relations) {
-    return {
-        belongsTo: relations.belongsTo.map(transformBelongsTo),
-        hasOne: relations.hasOne.map(transformHasOne),
-        hasMany: relations.hasMany.map(transformHasMany),
-        manyToMany: relations.manyToMany.map(transformManyToMany),
-    };
-}
-/**
- * Transform belongsTo relation
- */
-function transformBelongsTo(rel) {
-    return {
-        fieldName: rel.fieldName,
-        isUnique: rel.isUnique,
-        referencesTable: rel.references.name,
-        type: rel.type,
-        keys: transformFields(rel.keys),
-    };
-}
-/**
- * Transform hasOne relation
- */
-function transformHasOne(rel) {
-    return {
-        fieldName: rel.fieldName,
-        isUnique: rel.isUnique,
-        referencedByTable: rel.referencedBy.name,
-        type: rel.type,
-        keys: transformFields(rel.keys),
-    };
-}
-/**
- * Transform hasMany relation
- */
-function transformHasMany(rel) {
-    return {
-        fieldName: rel.fieldName,
-        isUnique: rel.isUnique,
-        referencedByTable: rel.referencedBy.name,
-        type: rel.type,
-        keys: transformFields(rel.keys),
-    };
-}
-/**
- * Transform manyToMany relation
- */
-function transformManyToMany(rel) {
-    return {
-        fieldName: rel.fieldName,
-        rightTable: rel.rightTable.name,
-        junctionTable: rel.junctionTable.name,
-        type: rel.type,
-    };
-}
-/**
- * Transform inflection data
- */
-function transformInflection(inflection) {
-    return {
-        allRows: inflection.allRows,
-        allRowsSimple: inflection.allRowsSimple,
-        conditionType: inflection.conditionType,
-        connection: inflection.connection,
-        createField: inflection.createField,
-        createInputType: inflection.createInputType,
-        createPayloadType: inflection.createPayloadType,
-        deleteByPrimaryKey: inflection.deleteByPrimaryKey,
-        deletePayloadType: inflection.deletePayloadType,
-        edge: inflection.edge,
-        edgeField: inflection.edgeField,
-        enumType: inflection.enumType,
-        filterType: inflection.filterType,
-        inputType: inflection.inputType,
-        orderByType: inflection.orderByType,
-        patchField: inflection.patchField,
-        patchType: inflection.patchType,
-        tableFieldName: inflection.tableFieldName,
-        tableType: inflection.tableType,
-        typeName: inflection.typeName,
-        updateByPrimaryKey: inflection.updateByPrimaryKey,
-        updatePayloadType: inflection.updatePayloadType,
-    };
-}
-/**
- * Transform query names
- */
-function transformQuery(query) {
-    return {
-        all: query.all,
-        one: query.one,
-        create: query.create,
-        update: query.update,
-        delete: query.delete,
-    };
-}
-/**
- * Transform constraints
- */
-function transformConstraints(table) {
-    return {
-        primaryKey: table.primaryKeyConstraints.map(transformConstraint),
-        foreignKey: table.foreignKeyConstraints.map(transformForeignKeyConstraint),
-        unique: table.uniqueConstraints.map(transformConstraint),
-    };
-}
-/**
- * Transform a basic constraint
- */
-function transformConstraint(constraint) {
-    return {
-        name: constraint.name,
-        fields: transformFields(constraint.fields),
-    };
-}
-/**
- * Transform a foreign key constraint
- */
-function transformForeignKeyConstraint(constraint) {
-    return {
-        name: constraint.name,
-        fields: transformFields(constraint.fields),
-        refTable: constraint.refTable.name,
-        refFields: transformFields(constraint.refFields),
-    };
-}
 /**
  * Get table names from CleanTable array
  */

package/esm/cli/watch/cache.d.ts

@@ -4,11 +4,10 @@
  * Only stores the hash in memory - no file I/O during normal operation.
  * Touch file feature is optional and only writes when explicitly configured.
  */
-import type { MetaQueryResponse } from '../introspect/meta-query';
 import type { IntrospectionQueryResponse } from '../../types/introspection';
 /**
  * Lightweight in-memory schema cache
- * Only stores the combined hash string to detect changes
+ * Only stores the schema hash string to detect changes
  */
 export declare class SchemaCache {
     /** Current schema hash (in-memory only) */
@@ -17,7 +16,7 @@ export declare class SchemaCache {
      * Check if schema has changed by comparing hashes
      * This is the hot path - must be efficient
      */
-    hasChanged(meta: MetaQueryResponse, schema: IntrospectionQueryResponse): Promise<{
+    hasChanged(schema: IntrospectionQueryResponse): Promise<{
         changed: boolean;
         newHash: string;
     }>;
@@ -34,7 +33,7 @@ export declare class SchemaCache {
      */
     clear(): void;
     /**
-     * Compute hash from meta and schema responses
+     * Compute hash from schema response
      */
     private computeHash;
 }

package/esm/cli/watch/cache.js

@@ -6,10 +6,10 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { hashObject, combineHashes } from './hash';
+import { hashObject } from './hash';
 /**
  * Lightweight in-memory schema cache
- * Only stores the combined hash string to detect changes
+ * Only stores the schema hash string to detect changes
  */
 export class SchemaCache {
     /** Current schema hash (in-memory only) */
@@ -18,8 +18,8 @@ export class SchemaCache {
      * Check if schema has changed by comparing hashes
      * This is the hot path - must be efficient
      */
-    async hasChanged(meta, schema) {
-        const newHash = await this.computeHash(meta, schema);
+    async hasChanged(schema) {
+        const newHash = await this.computeHash(schema);
         const changed = this.currentHash === null || this.currentHash !== newHash;
         return { changed, newHash };
     }
@@ -42,14 +42,10 @@ export class SchemaCache {
         this.currentHash = null;
     }
     /**
-     * Compute hash from meta and schema responses
+     * Compute hash from schema response
      */
-    async computeHash(meta, schema) {
-        // Hash each response separately then combine
-        // This is more efficient than stringifying both together
-        const metaHash = await hashObject(meta);
-        const schemaHash = await hashObject(schema);
-        return combineHashes(metaHash, schemaHash);
+    async computeHash(schema) {
+        return hashObject(schema);
     }
 }
 /**