@constructive-io/graphql-codegen 2.19.0 → 2.20.0

package/esm/types/config.d.ts

@@ -0,0 +1,199 @@
+/**
+ * SDK Configuration types
+ */
+/**
+ * Main configuration for graphql-codegen
+ */
+export interface GraphQLSDKConfig {
+    /**
+     * GraphQL endpoint URL (must expose _meta query)
+     */
+    endpoint: string;
+    /**
+     * Headers to include in introspection requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Output directory for generated code
+     * @default './generated/graphql'
+     */
+    output?: string;
+    /**
+     * Table filtering options (for table-based CRUD operations from _meta)
+     */
+    tables?: {
+        /** Tables to include (glob patterns supported) */
+        include?: string[];
+        /** Tables to exclude (glob patterns supported) */
+        exclude?: string[];
+    };
+    /**
+     * Query operation filtering (for ALL queries from __schema introspection)
+     * Glob patterns supported (e.g., 'current*', '*ByUsername')
+     */
+    queries?: {
+        /** Query names to include - defaults to ['*'] */
+        include?: string[];
+        /** Query names to exclude - defaults to ['_meta', 'query'] */
+        exclude?: string[];
+    };
+    /**
+     * Mutation operation filtering (for ALL mutations from __schema introspection)
+     * Glob patterns supported (e.g., 'create*', 'login', 'register')
+     */
+    mutations?: {
+        /** Mutation names to include - defaults to ['*'] */
+        include?: string[];
+        /** Mutation names to exclude */
+        exclude?: string[];
+    };
+    /**
+     * Fields to exclude globally from all tables
+     */
+    excludeFields?: string[];
+    /**
+     * Hook generation options
+     */
+    hooks?: {
+        /** Generate query hooks */
+        queries?: boolean;
+        /** Generate mutation hooks */
+        mutations?: boolean;
+        /** Prefix for query keys */
+        queryKeyPrefix?: string;
+    };
+    /**
+     * PostGraphile-specific options
+     */
+    postgraphile?: {
+        /** PostgreSQL schema to introspect */
+        schema?: string;
+    };
+    /**
+     * Code generation options
+     */
+    codegen?: {
+        /** Max depth for nested object field selection (default: 2) */
+        maxFieldDepth?: number;
+        /** Skip 'query' field on mutation payloads (default: true) */
+        skipQueryField?: boolean;
+    };
+    /**
+     * ORM client generation options
+     * When set, generates a Prisma-like ORM client in addition to or instead of React Query hooks
+     */
+    orm?: {
+        /**
+         * Output directory for generated ORM client
+         * @default './generated/orm'
+         */
+        output?: string;
+        /**
+         * Whether to import shared types from hooks output or generate standalone
+         * When true, ORM types.ts will re-export from ../graphql/types
+         * @default true
+         */
+        useSharedTypes?: boolean;
+    };
+    /**
+     * Watch mode configuration (dev-only feature)
+     * When enabled via CLI --watch flag, the CLI will poll the endpoint for schema changes
+     */
+    watch?: WatchConfig;
+}
+/**
+ * Watch mode configuration options
+ *
+ * Watch mode uses in-memory caching for efficiency - no file I/O during polling.
+ */
+export interface WatchConfig {
+    /**
+     * Polling interval in milliseconds
+     * @default 3000
+     */
+    pollInterval?: number;
+    /**
+     * Debounce delay in milliseconds before regenerating
+     * Prevents rapid regeneration during schema migrations
+     * @default 800
+     */
+    debounce?: number;
+    /**
+     * File to touch on schema change (useful for triggering external tools like tsc/webpack)
+     * This is the only file I/O in watch mode.
+     * @example '.trigger'
+     */
+    touchFile?: string;
+    /**
+     * Clear terminal on regeneration
+     * @default true
+     */
+    clearScreen?: boolean;
+}
+/**
+ * Resolved watch configuration with defaults applied
+ */
+export interface ResolvedWatchConfig {
+    pollInterval: number;
+    debounce: number;
+    touchFile: string | null;
+    clearScreen: boolean;
+}
+/**
+ * Resolved configuration with defaults applied
+ */
+export interface ResolvedConfig extends Required<Omit<GraphQLSDKConfig, 'headers' | 'tables' | 'queries' | 'mutations' | 'hooks' | 'postgraphile' | 'codegen' | 'orm' | 'watch'>> {
+    headers: Record<string, string>;
+    tables: {
+        include: string[];
+        exclude: string[];
+    };
+    queries: {
+        include: string[];
+        exclude: string[];
+    };
+    mutations: {
+        include: string[];
+        exclude: string[];
+    };
+    hooks: {
+        queries: boolean;
+        mutations: boolean;
+        queryKeyPrefix: string;
+    };
+    postgraphile: {
+        schema: string;
+    };
+    codegen: {
+        maxFieldDepth: number;
+        skipQueryField: boolean;
+    };
+    orm: {
+        output: string;
+        useSharedTypes: boolean;
+    } | null;
+    watch: ResolvedWatchConfig;
+}
+/**
+ * Default watch configuration values
+ */
+export declare const DEFAULT_WATCH_CONFIG: ResolvedWatchConfig;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'endpoint'>;
+/**
+ * Default ORM configuration values
+ */
+export declare const DEFAULT_ORM_CONFIG: {
+    output: string;
+    useSharedTypes: boolean;
+};
+/**
+ * Helper function to define configuration with type checking
+ */
+export declare function defineConfig(config: GraphQLSDKConfig): GraphQLSDKConfig;
+/**
+ * Resolve configuration by applying defaults
+ */
+export declare function resolveConfig(config: GraphQLSDKConfig): ResolvedConfig;

package/esm/types/config.js

@@ -0,0 +1,106 @@
+/**
+ * SDK Configuration types
+ */
+/**
+ * Default watch configuration values
+ */
+export const DEFAULT_WATCH_CONFIG = {
+    pollInterval: 3000,
+    debounce: 800,
+    touchFile: null,
+    clearScreen: true,
+};
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    headers: {},
+    output: './generated/graphql',
+    tables: {
+        include: ['*'],
+        exclude: [],
+    },
+    queries: {
+        include: ['*'],
+        exclude: ['_meta', 'query'], // Internal PostGraphile queries
+    },
+    mutations: {
+        include: ['*'],
+        exclude: [],
+    },
+    excludeFields: [],
+    hooks: {
+        queries: true,
+        mutations: true,
+        queryKeyPrefix: 'graphql',
+    },
+    postgraphile: {
+        schema: 'public',
+    },
+    codegen: {
+        maxFieldDepth: 2,
+        skipQueryField: true,
+    },
+    orm: null, // ORM generation disabled by default
+    watch: DEFAULT_WATCH_CONFIG,
+};
+/**
+ * Default ORM configuration values
+ */
+export const DEFAULT_ORM_CONFIG = {
+    output: './generated/orm',
+    useSharedTypes: true,
+};
+/**
+ * Helper function to define configuration with type checking
+ */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Resolve configuration by applying defaults
+ */
+export function resolveConfig(config) {
+    return {
+        endpoint: config.endpoint,
+        headers: config.headers ?? DEFAULT_CONFIG.headers,
+        output: config.output ?? DEFAULT_CONFIG.output,
+        tables: {
+            include: config.tables?.include ?? DEFAULT_CONFIG.tables.include,
+            exclude: config.tables?.exclude ?? DEFAULT_CONFIG.tables.exclude,
+        },
+        queries: {
+            include: config.queries?.include ?? DEFAULT_CONFIG.queries.include,
+            exclude: config.queries?.exclude ?? DEFAULT_CONFIG.queries.exclude,
+        },
+        mutations: {
+            include: config.mutations?.include ?? DEFAULT_CONFIG.mutations.include,
+            exclude: config.mutations?.exclude ?? DEFAULT_CONFIG.mutations.exclude,
+        },
+        excludeFields: config.excludeFields ?? DEFAULT_CONFIG.excludeFields,
+        hooks: {
+            queries: config.hooks?.queries ?? DEFAULT_CONFIG.hooks.queries,
+            mutations: config.hooks?.mutations ?? DEFAULT_CONFIG.hooks.mutations,
+            queryKeyPrefix: config.hooks?.queryKeyPrefix ?? DEFAULT_CONFIG.hooks.queryKeyPrefix,
+        },
+        postgraphile: {
+            schema: config.postgraphile?.schema ?? DEFAULT_CONFIG.postgraphile.schema,
+        },
+        codegen: {
+            maxFieldDepth: config.codegen?.maxFieldDepth ?? DEFAULT_CONFIG.codegen.maxFieldDepth,
+            skipQueryField: config.codegen?.skipQueryField ?? DEFAULT_CONFIG.codegen.skipQueryField,
+        },
+        orm: config.orm
+            ? {
+                output: config.orm.output ?? DEFAULT_ORM_CONFIG.output,
+                useSharedTypes: config.orm.useSharedTypes ?? DEFAULT_ORM_CONFIG.useSharedTypes,
+            }
+            : null,
+        watch: {
+            pollInterval: config.watch?.pollInterval ?? DEFAULT_WATCH_CONFIG.pollInterval,
+            debounce: config.watch?.debounce ?? DEFAULT_WATCH_CONFIG.debounce,
+            touchFile: config.watch?.touchFile ?? DEFAULT_WATCH_CONFIG.touchFile,
+            clearScreen: config.watch?.clearScreen ?? DEFAULT_WATCH_CONFIG.clearScreen,
+        },
+    };
+}

package/esm/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type exports for @constructive-io/graphql-codegen
+ */
+export type { CleanTable, CleanField, CleanFieldType, CleanRelations, CleanBelongsToRelation, CleanHasOneRelation, CleanHasManyRelation, CleanManyToManyRelation, TableInflection, TableQueryNames, TableConstraints, ConstraintInfo, ForeignKeyConstraint, } from './schema';
+export type { PageInfo, ConnectionResult, QueryOptions, OrderByItem, FilterOperator, FieldFilter, RelationalFilter, Filter, } from './query';
+export type { MutationOptions, CreateInput, UpdateInput, DeleteInput, MutationResult, } from './mutation';
+export type { SimpleFieldSelection, FieldSelectionPreset, FieldSelection, SelectionOptions, } from './selection';
+export type { GraphQLSDKConfig, ResolvedConfig, } from './config';
+export { defineConfig, resolveConfig, DEFAULT_CONFIG } from './config';

package/esm/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type exports for @constructive-io/graphql-codegen
+ */
+export { defineConfig, resolveConfig, DEFAULT_CONFIG } from './config';

package/esm/types/introspection.d.ts

@@ -0,0 +1,121 @@
+/**
+ * GraphQL Introspection Types
+ *
+ * Standard types for GraphQL schema introspection via __schema query.
+ * These mirror the GraphQL introspection spec.
+ */
+/**
+ * Reference to a GraphQL type - can be nested for wrappers like NON_NULL and LIST
+ */
+export interface IntrospectionTypeRef {
+    kind: IntrospectionTypeKind;
+    name: string | null;
+    ofType: IntrospectionTypeRef | null;
+}
+export type IntrospectionTypeKind = 'SCALAR' | 'OBJECT' | 'INPUT_OBJECT' | 'ENUM' | 'LIST' | 'NON_NULL' | 'INTERFACE' | 'UNION';
+/**
+ * Input value - used for both field arguments and INPUT_OBJECT fields
+ */
+export interface IntrospectionInputValue {
+    name: string;
+    description: string | null;
+    type: IntrospectionTypeRef;
+    defaultValue: string | null;
+}
+/**
+ * Field on an OBJECT or INTERFACE type
+ */
+export interface IntrospectionField {
+    name: string;
+    description: string | null;
+    args: IntrospectionInputValue[];
+    type: IntrospectionTypeRef;
+    isDeprecated: boolean;
+    deprecationReason: string | null;
+}
+/**
+ * Enum value definition
+ */
+export interface IntrospectionEnumValue {
+    name: string;
+    description: string | null;
+    isDeprecated: boolean;
+    deprecationReason: string | null;
+}
+/**
+ * Complete type definition from introspection
+ */
+export interface IntrospectionType {
+    kind: IntrospectionTypeKind;
+    name: string;
+    description: string | null;
+    /** Fields for OBJECT and INTERFACE types */
+    fields: IntrospectionField[] | null;
+    /** Input fields for INPUT_OBJECT types */
+    inputFields: IntrospectionInputValue[] | null;
+    /** Possible types for INTERFACE and UNION types */
+    possibleTypes: Array<{
+        name: string;
+    }> | null;
+    /** Enum values for ENUM types */
+    enumValues: IntrospectionEnumValue[] | null;
+    /** Interfaces implemented by OBJECT types */
+    interfaces: Array<{
+        name: string;
+    }> | null;
+}
+/**
+ * Root type references in schema
+ */
+export interface IntrospectionRootType {
+    name: string;
+}
+/**
+ * Full schema introspection result
+ */
+export interface IntrospectionSchema {
+    queryType: IntrospectionRootType;
+    mutationType: IntrospectionRootType | null;
+    subscriptionType: IntrospectionRootType | null;
+    types: IntrospectionType[];
+    directives: IntrospectionDirective[];
+}
+/**
+ * Directive definition
+ */
+export interface IntrospectionDirective {
+    name: string;
+    description: string | null;
+    locations: string[];
+    args: IntrospectionInputValue[];
+}
+/**
+ * Response from introspection query
+ */
+export interface IntrospectionQueryResponse {
+    __schema: IntrospectionSchema;
+}
+/**
+ * Check if type kind is a wrapper (LIST or NON_NULL)
+ */
+export declare function isWrapperType(kind: IntrospectionTypeKind): boolean;
+/**
+ * Check if type kind is a named type (has a name)
+ */
+export declare function isNamedType(kind: IntrospectionTypeKind): boolean;
+/**
+ * Unwrap a type reference to get the base named type
+ */
+export declare function unwrapType(typeRef: IntrospectionTypeRef): IntrospectionTypeRef;
+/**
+ * Get the base type name from a possibly wrapped type
+ */
+export declare function getBaseTypeName(typeRef: IntrospectionTypeRef): string | null;
+/**
+ * Check if a type reference is non-null (required)
+ */
+export declare function isNonNull(typeRef: IntrospectionTypeRef): boolean;
+/**
+ * Check if a type reference is a list
+ */
+export declare function isList(typeRef: IntrospectionTypeRef): boolean;

package/esm/types/introspection.js

@@ -0,0 +1,54 @@
+/**
+ * GraphQL Introspection Types
+ *
+ * Standard types for GraphQL schema introspection via __schema query.
+ * These mirror the GraphQL introspection spec.
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Check if type kind is a wrapper (LIST or NON_NULL)
+ */
+export function isWrapperType(kind) {
+    return kind === 'LIST' || kind === 'NON_NULL';
+}
+/**
+ * Check if type kind is a named type (has a name)
+ */
+export function isNamedType(kind) {
+    return !isWrapperType(kind);
+}
+/**
+ * Unwrap a type reference to get the base named type
+ */
+export function unwrapType(typeRef) {
+    let current = typeRef;
+    while (current.ofType) {
+        current = current.ofType;
+    }
+    return current;
+}
+/**
+ * Get the base type name from a possibly wrapped type
+ */
+export function getBaseTypeName(typeRef) {
+    return unwrapType(typeRef).name;
+}
+/**
+ * Check if a type reference is non-null (required)
+ */
+export function isNonNull(typeRef) {
+    return typeRef.kind === 'NON_NULL';
+}
+/**
+ * Check if a type reference is a list
+ */
+export function isList(typeRef) {
+    if (typeRef.kind === 'LIST')
+        return true;
+    if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {
+        return typeRef.ofType.kind === 'LIST';
+    }
+    return false;
+}

package/esm/types/mutation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Mutation-related types
+ */
+import type { FieldSelection } from './selection';
+/**
+ * Options for mutation operations
+ */
+export interface MutationOptions {
+    /** Fields to return after mutation */
+    returning?: string[];
+    /** Field selection for returned data */
+    fieldSelection?: FieldSelection;
+}
+/**
+ * Input for create mutations
+ * Wraps the actual data in PostGraphile's expected format
+ */
+export interface CreateInput<T = Record<string, unknown>> {
+    [tableName: string]: T;
+}
+/**
+ * Input for update mutations
+ */
+export interface UpdateInput<T = Record<string, unknown>> {
+    /** Primary key value */
+    id: string | number;
+    /** Fields to update */
+    patch: T;
+}
+/**
+ * Input for delete mutations
+ */
+export interface DeleteInput {
+    /** Primary key value */
+    id: string | number;
+}
+/**
+ * Standard mutation result
+ */
+export interface MutationResult<T = unknown> {
+    /** The affected record */
+    data?: T;
+    /** Client mutation ID (PostGraphile) */
+    clientMutationId?: string;
+}

package/esm/types/mutation.js

@@ -0,0 +1,4 @@
+/**
+ * Mutation-related types
+ */
+export {};

package/esm/types/query.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Query-related types for building GraphQL operations
+ */
+import type { FieldSelection } from './selection';
+/**
+ * Relay-style pagination info
+ */
+export interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+}
+/**
+ * Relay-style connection result
+ */
+export interface ConnectionResult<T = unknown> {
+    nodes: T[];
+    totalCount: number;
+    pageInfo: PageInfo;
+}
+/**
+ * Options for building SELECT queries
+ */
+export interface QueryOptions {
+    /** Number of records to fetch (alias for first) */
+    first?: number;
+    /** Alias for first */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Cursor for forward pagination */
+    after?: string;
+    /** Cursor for backward pagination */
+    before?: string;
+    /** Filter conditions */
+    where?: Filter;
+    /** Sort order */
+    orderBy?: OrderByItem[];
+    /** Field selection options */
+    fieldSelection?: FieldSelection;
+    /** Include pageInfo in response */
+    includePageInfo?: boolean;
+}
+/**
+ * Single order by specification
+ */
+export interface OrderByItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * All supported filter operators
+ */
+export type FilterOperator = 'isNull' | 'equalTo' | 'notEqualTo' | 'distinctFrom' | 'notDistinctFrom' | 'in' | 'notIn' | 'lessThan' | 'lessThanOrEqualTo' | 'greaterThan' | 'greaterThanOrEqualTo' | 'includes' | 'notIncludes' | 'includesInsensitive' | 'notIncludesInsensitive' | 'startsWith' | 'notStartsWith' | 'startsWithInsensitive' | 'notStartsWithInsensitive' | 'endsWith' | 'notEndsWith' | 'endsWithInsensitive' | 'notEndsWithInsensitive' | 'like' | 'notLike' | 'likeInsensitive' | 'notLikeInsensitive' | 'equalToInsensitive' | 'notEqualToInsensitive' | 'distinctFromInsensitive' | 'notDistinctFromInsensitive' | 'inInsensitive' | 'notInInsensitive' | 'contains' | 'containedBy' | 'overlaps' | 'intersects' | 'intersects3D' | 'containsProperly' | 'coveredBy' | 'covers' | 'crosses' | 'disjoint' | 'orderingEquals' | 'touches' | 'within' | 'bboxIntersects2D' | 'bboxIntersects3D' | 'bboxOverlapsOrLeftOf' | 'bboxOverlapsOrRightOf' | 'bboxOverlapsOrBelow' | 'bboxOverlapsOrAbove' | 'bboxLeftOf' | 'bboxRightOf' | 'bboxBelow' | 'bboxAbove' | 'bboxContains' | 'bboxEquals';
+/**
+ * Filter on a single field
+ */
+export type FieldFilter = {
+    [K in FilterOperator]?: unknown;
+};
+/**
+ * Filter on related records
+ */
+export interface RelationalFilter {
+    /** All related records must match */
+    every?: Filter;
+    /** At least one related record must match */
+    some?: Filter;
+    /** No related records match */
+    none?: Filter;
+}
+/**
+ * Main filter type - can be nested
+ */
+export type Filter = {
+    [field: string]: FieldFilter | RelationalFilter | Filter;
+} & {
+    and?: Filter[];
+    or?: Filter[];
+    not?: Filter;
+};

package/esm/types/query.js

@@ -0,0 +1,4 @@
+/**
+ * Query-related types for building GraphQL operations
+ */
+export {};