@constructive-io/graphql-codegen 2.19.0 → 2.20.0

package/index.js

@@ -1,4 +1,11 @@
 "use strict";
+/**
+ * @constructive-io/graphql-codegen
+ *
+ * CLI-based GraphQL SDK generator for PostGraphile endpoints.
+ * Introspects via _meta query and generates typed queries, mutations,
+ * and React Query v5 hooks.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,6 +21,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./gql"), exports);
-__exportStar(require("./codegen"), exports);
-__exportStar(require("./options"), exports);
+exports.defineConfig = void 0;
+// Core types
+__exportStar(require("./types"), exports);
+// Core query building
+__exportStar(require("./core"), exports);
+// Generators
+__exportStar(require("./generators"), exports);
+// Client utilities
+__exportStar(require("./client"), exports);
+// Config definition helper
+var config_1 = require("./types/config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "2.19.0",
-  "description": "Generate queries and mutations for use with Graphile",
+  "version": "2.20.0",
+  "description": "CLI-based GraphQL SDK generator for PostGraphile endpoints with React Query hooks",
+  "keywords": [
+    "graphql",
+    "postgraphile",
+    "codegen",
+    "react-query",
+    "tanstack-query",
+    "typescript",
+    "graphile",
+    "constructive"
+  ],
   "author": "Constructive <developers@constructive.io>",
-  "main": "index.js",
-  "module": "esm/index.js",
-  "types": "index.d.ts",
-  "homepage": "https://github.com/constructive-io/constructive",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "directory": "dist"
-  },
+  "homepage": "https://github.com/constructive-io/constructive",
   "repository": {
     "type": "git",
     "url": "https://github.com/constructive-io/constructive"
@@ -19,43 +22,61 @@
   "bugs": {
     "url": "https://github.com/constructive-io/constructive/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "bin": {
+    "graphql-codegen": "index.js"
+  },
   "scripts": {
     "clean": "makage clean",
     "prepack": "npm run build",
     "build": "makage build",
     "build:dev": "makage build --dev",
+    "dev": "ts-node ./src/index.ts",
     "lint": "eslint . --fix",
     "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch"
-  },
-  "devDependencies": {
-    "@constructive-io/graphql-test": "^2.13.0",
-    "@types/babel__generator": "^7.27.0",
-    "@types/inflection": "^2.0.0",
-    "makage": "^0.1.10"
+    "test:watch": "jest --watch",
+    "example:orm": "tsx examples/test-orm.ts",
+    "example:rq": "tsx examples/test-rq.ts",
+    "example:schema": "tsx examples/download-schema.ts"
   },
   "dependencies": {
-    "@babel/generator": "^7.26.3",
-    "@babel/parser": "^7.28.5",
-    "@babel/types": "^7.26.3",
-    "@graphql-codegen/core": "5.0.0",
-    "@graphql-codegen/typescript": "5.0.5",
-    "@graphql-codegen/typescript-graphql-request": "6.0.1",
-    "@graphql-codegen/typescript-operations": "5.0.5",
-    "@graphql-codegen/typescript-react-query": "6.1.1",
+    "ajv": "^8.17.1",
+    "commander": "^12.1.0",
     "gql-ast": "^2.4.6",
-    "graphql": "15.10.1",
-    "graphql-request": "6.1.0",
-    "graphql-tag": "2.12.6",
-    "inflection": "^1.12.0",
-    "introspectron": "^2.16.0"
+    "graphql": "15.8.0",
+    "inflection": "^3.0.2",
+    "jiti": "^2.6.1",
+    "prettier": "^3.7.4",
+    "ts-morph": "^27.0.2"
   },
-  "keywords": [
-    "graphql",
-    "codegen",
-    "generator",
-    "graphile",
-    "constructive"
-  ],
-  "gitHead": "e6171117d5498f38f456dfaf7e8a497dd7d2a30b"
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.16",
+    "@types/inflection": "^1.13.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.27",
+    "@types/react": "^19.2.7",
+    "jest": "^29.7.0",
+    "react": "^19.2.3",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.9.3"
+  },
+  "gitHead": "baa2f7598cde3baf3f05f161a11bafa12c66f6aa"
 }

package/react/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * React integration exports
+ * Will be populated in Phase 8
+ */
+export declare const REACT_VERSION = "0.1.0";

package/react/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * React integration exports
+ * Will be populated in Phase 8
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REACT_VERSION = void 0;
+// Placeholder exports - will be implemented
+exports.REACT_VERSION = '0.1.0';

package/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/types/config.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * SDK Configuration types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ORM_CONFIG = exports.DEFAULT_CONFIG = exports.DEFAULT_WATCH_CONFIG = void 0;
+exports.defineConfig = defineConfig;
+exports.resolveConfig = resolveConfig;
+/**
+ * Default watch configuration values
+ */
+exports.DEFAULT_WATCH_CONFIG = {
+    pollInterval: 3000,
+    debounce: 800,
+    touchFile: null,
+    clearScreen: true,
+};
+/**
+ * Default configuration values
+ */
+exports.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: exports.DEFAULT_WATCH_CONFIG,
+};
+/**
+ * Default ORM configuration values
+ */
+exports.DEFAULT_ORM_CONFIG = {
+    output: './generated/orm',
+    useSharedTypes: true,
+};
+/**
+ * Helper function to define configuration with type checking
+ */
+function defineConfig(config) {
+    return config;
+}
+/**
+ * Resolve configuration by applying defaults
+ */
+function resolveConfig(config) {
+    return {
+        endpoint: config.endpoint,
+        headers: config.headers ?? exports.DEFAULT_CONFIG.headers,
+        output: config.output ?? exports.DEFAULT_CONFIG.output,
+        tables: {
+            include: config.tables?.include ?? exports.DEFAULT_CONFIG.tables.include,
+            exclude: config.tables?.exclude ?? exports.DEFAULT_CONFIG.tables.exclude,
+        },
+        queries: {
+            include: config.queries?.include ?? exports.DEFAULT_CONFIG.queries.include,
+            exclude: config.queries?.exclude ?? exports.DEFAULT_CONFIG.queries.exclude,
+        },
+        mutations: {
+            include: config.mutations?.include ?? exports.DEFAULT_CONFIG.mutations.include,
+            exclude: config.mutations?.exclude ?? exports.DEFAULT_CONFIG.mutations.exclude,
+        },
+        excludeFields: config.excludeFields ?? exports.DEFAULT_CONFIG.excludeFields,
+        hooks: {
+            queries: config.hooks?.queries ?? exports.DEFAULT_CONFIG.hooks.queries,
+            mutations: config.hooks?.mutations ?? exports.DEFAULT_CONFIG.hooks.mutations,
+            queryKeyPrefix: config.hooks?.queryKeyPrefix ?? exports.DEFAULT_CONFIG.hooks.queryKeyPrefix,
+        },
+        postgraphile: {
+            schema: config.postgraphile?.schema ?? exports.DEFAULT_CONFIG.postgraphile.schema,
+        },
+        codegen: {
+            maxFieldDepth: config.codegen?.maxFieldDepth ?? exports.DEFAULT_CONFIG.codegen.maxFieldDepth,
+            skipQueryField: config.codegen?.skipQueryField ?? exports.DEFAULT_CONFIG.codegen.skipQueryField,
+        },
+        orm: config.orm
+            ? {
+                output: config.orm.output ?? exports.DEFAULT_ORM_CONFIG.output,
+                useSharedTypes: config.orm.useSharedTypes ?? exports.DEFAULT_ORM_CONFIG.useSharedTypes,
+            }
+            : null,
+        watch: {
+            pollInterval: config.watch?.pollInterval ?? exports.DEFAULT_WATCH_CONFIG.pollInterval,
+            debounce: config.watch?.debounce ?? exports.DEFAULT_WATCH_CONFIG.debounce,
+            touchFile: config.watch?.touchFile ?? exports.DEFAULT_WATCH_CONFIG.touchFile,
+            clearScreen: config.watch?.clearScreen ?? exports.DEFAULT_WATCH_CONFIG.clearScreen,
+        },
+    };
+}

package/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/types/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Type exports for @constructive-io/graphql-codegen
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = exports.resolveConfig = exports.defineConfig = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_CONFIG; } });

package/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/types/introspection.js

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