@constructive-io/graphql-codegen 2.19.0 → 2.20.0

package/cli/codegen/queries.js

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateListQueryHook = generateListQueryHook;
+exports.generateSingleQueryHook = generateSingleQueryHook;
+exports.generateAllQueryHooks = generateAllQueryHooks;
+const ts_ast_1 = require("./ts-ast");
+const gql_ast_1 = require("./gql-ast");
+const utils_1 = require("./utils");
+// ============================================================================
+// List query hook generator
+// ============================================================================
+/**
+ * Generate list query hook file content using AST
+ */
+function generateListQueryHook(table) {
+    const project = (0, ts_ast_1.createProject)();
+    const { typeName, pluralName } = (0, utils_1.getTableNames)(table);
+    const hookName = (0, utils_1.getListQueryHookName)(table);
+    const queryName = (0, utils_1.getAllRowsQueryName)(table);
+    const filterTypeName = (0, utils_1.getFilterTypeName)(table);
+    const orderByTypeName = (0, utils_1.getOrderByTypeName)(table);
+    const scalarFields = (0, utils_1.getScalarFields)(table);
+    // Generate GraphQL document via AST
+    const queryAST = (0, gql_ast_1.buildListQueryAST)({ table });
+    const queryDocument = (0, gql_ast_1.printGraphQL)(queryAST);
+    const sourceFile = (0, ts_ast_1.createSourceFile)(project, (0, utils_1.getListQueryFileName)(table));
+    // Add file header as leading comment
+    sourceFile.insertText(0, (0, ts_ast_1.createFileHeader)(`List query hook for ${typeName}`) + '\n\n');
+    // Collect all filter types used by this table's fields
+    const filterTypesUsed = new Set();
+    for (const field of scalarFields) {
+        const filterType = (0, utils_1.getScalarFilterType)(field.type.gqlType);
+        if (filterType) {
+            filterTypesUsed.add(filterType);
+        }
+    }
+    // Add imports
+    sourceFile.addImportDeclarations([
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '@tanstack/react-query',
+            namedImports: ['useQuery'],
+            typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
+        }),
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '../client',
+            namedImports: ['execute'],
+            typeOnlyNamedImports: ['ExecuteOptions'],
+        }),
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '../types',
+            typeOnlyNamedImports: [typeName, ...Array.from(filterTypesUsed)],
+        }),
+    ]);
+    // Re-export entity type
+    sourceFile.addStatements(`\n// Re-export entity type for convenience\nexport type { ${typeName} };\n`);
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// GraphQL Document');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Add query document constant
+    sourceFile.addVariableStatement((0, ts_ast_1.createConst)(`${queryName}QueryDocument`, '`\n' + queryDocument + '`'));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Types');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Generate filter interface
+    const fieldFilters = scalarFields
+        .map((field) => {
+        const filterType = (0, utils_1.getScalarFilterType)(field.type.gqlType);
+        return filterType ? { fieldName: field.name, filterType } : null;
+    })
+        .filter((f) => f !== null);
+    sourceFile.addInterface((0, ts_ast_1.createFilterInterface)(filterTypeName, fieldFilters));
+    // Generate OrderBy type
+    const orderByValues = [
+        ...scalarFields.flatMap((f) => [
+            `${(0, utils_1.toScreamingSnake)(f.name)}_ASC`,
+            `${(0, utils_1.toScreamingSnake)(f.name)}_DESC`,
+        ]),
+        'NATURAL',
+        'PRIMARY_KEY_ASC',
+        'PRIMARY_KEY_DESC',
+    ];
+    sourceFile.addTypeAlias((0, ts_ast_1.createTypeAlias)(orderByTypeName, (0, ts_ast_1.createUnionType)(orderByValues)));
+    // Variables interface
+    const variablesProps = [
+        { name: 'first', type: 'number', optional: true },
+        { name: 'offset', type: 'number', optional: true },
+        { name: 'filter', type: filterTypeName, optional: true },
+        { name: 'orderBy', type: `${orderByTypeName}[]`, optional: true },
+    ];
+    sourceFile.addInterface((0, ts_ast_1.createInterface)(`${(0, utils_1.ucFirst)(pluralName)}QueryVariables`, variablesProps));
+    // Result interface
+    const resultProps = [
+        {
+            name: queryName,
+            type: `{
+    totalCount: number;
+    nodes: ${typeName}[];
+    pageInfo: {
+      hasNextPage: boolean;
+      hasPreviousPage: boolean;
+      startCursor: string | null;
+      endCursor: string | null;
+    };
+  }`,
+        },
+    ];
+    sourceFile.addInterface((0, ts_ast_1.createInterface)(`${(0, utils_1.ucFirst)(pluralName)}QueryResult`, resultProps));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Query Key');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Query key factory
+    sourceFile.addVariableStatement((0, ts_ast_1.createConst)(`${queryName}QueryKey`, `(variables?: ${(0, utils_1.ucFirst)(pluralName)}QueryVariables) =>
+  ['${typeName.toLowerCase()}', 'list', variables] as const`));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Hook');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Hook function
+    sourceFile.addFunction({
+        name: hookName,
+        isExported: true,
+        parameters: [
+            {
+                name: 'variables',
+                type: `${(0, utils_1.ucFirst)(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: `Omit<UseQueryOptions<${(0, utils_1.ucFirst)(pluralName)}QueryResult, Error>, 'queryKey' | 'queryFn'>`,
+                hasQuestionToken: true,
+            },
+        ],
+        statements: `return useQuery({
+    queryKey: ${queryName}QueryKey(variables),
+    queryFn: () => execute<${(0, utils_1.ucFirst)(pluralName)}QueryResult, ${(0, utils_1.ucFirst)(pluralName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      variables
+    ),
+    ...options,
+  });`,
+        docs: [
+            {
+                description: `Query hook for fetching ${typeName} list
+
+@example
+\`\`\`tsx
+const { data, isLoading } = ${hookName}({
+  first: 10,
+  filter: { name: { equalTo: "example" } },
+  orderBy: ['CREATED_AT_DESC'],
+});
+\`\`\``,
+            },
+        ],
+    });
+    // Add section comment for standalone functions
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Standalone Functions (non-React)');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Fetch function (standalone, no React)
+    sourceFile.addFunction({
+        name: `fetch${(0, utils_1.ucFirst)(pluralName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            {
+                name: 'variables',
+                type: `${(0, utils_1.ucFirst)(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: `Promise<${(0, utils_1.ucFirst)(pluralName)}QueryResult>`,
+        statements: `return execute<${(0, utils_1.ucFirst)(pluralName)}QueryResult, ${(0, utils_1.ucFirst)(pluralName)}QueryVariables>(
+    ${queryName}QueryDocument,
+    variables,
+    options
+  );`,
+        docs: [
+            {
+                description: `Fetch ${typeName} list without React hooks
+
+@example
+\`\`\`ts
+// Direct fetch
+const data = await fetch${(0, utils_1.ucFirst)(pluralName)}Query({ first: 10 });
+
+// With QueryClient
+const data = await queryClient.fetchQuery({
+  queryKey: ${queryName}QueryKey(variables),
+  queryFn: () => fetch${(0, utils_1.ucFirst)(pluralName)}Query(variables),
+});
+\`\`\``,
+            },
+        ],
+    });
+    // Prefetch function (for SSR/QueryClient)
+    sourceFile.addFunction({
+        name: `prefetch${(0, utils_1.ucFirst)(pluralName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            {
+                name: 'queryClient',
+                type: 'QueryClient',
+            },
+            {
+                name: 'variables',
+                type: `${(0, utils_1.ucFirst)(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: 'Promise<void>',
+        statements: `await queryClient.prefetchQuery({
+    queryKey: ${queryName}QueryKey(variables),
+    queryFn: () => execute<${(0, utils_1.ucFirst)(pluralName)}QueryResult, ${(0, utils_1.ucFirst)(pluralName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      variables,
+      options
+    ),
+  });`,
+        docs: [
+            {
+                description: `Prefetch ${typeName} list for SSR or cache warming
+
+@example
+\`\`\`ts
+await prefetch${(0, utils_1.ucFirst)(pluralName)}Query(queryClient, { first: 10 });
+\`\`\``,
+            },
+        ],
+    });
+    return {
+        fileName: (0, utils_1.getListQueryFileName)(table),
+        content: (0, ts_ast_1.getFormattedOutput)(sourceFile),
+    };
+}
+// ============================================================================
+// Single item query hook generator
+// ============================================================================
+/**
+ * Generate single item query hook file content using AST
+ */
+function generateSingleQueryHook(table) {
+    const project = (0, ts_ast_1.createProject)();
+    const { typeName, singularName } = (0, utils_1.getTableNames)(table);
+    const hookName = (0, utils_1.getSingleQueryHookName)(table);
+    const queryName = (0, utils_1.getSingleRowQueryName)(table);
+    // Generate GraphQL document via AST
+    const queryAST = (0, gql_ast_1.buildSingleQueryAST)({ table });
+    const queryDocument = (0, gql_ast_1.printGraphQL)(queryAST);
+    const sourceFile = (0, ts_ast_1.createSourceFile)(project, (0, utils_1.getSingleQueryFileName)(table));
+    // Add file header
+    sourceFile.insertText(0, (0, ts_ast_1.createFileHeader)(`Single item query hook for ${typeName}`) + '\n\n');
+    // Add imports
+    sourceFile.addImportDeclarations([
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '@tanstack/react-query',
+            namedImports: ['useQuery'],
+            typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
+        }),
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '../client',
+            namedImports: ['execute'],
+            typeOnlyNamedImports: ['ExecuteOptions'],
+        }),
+        (0, ts_ast_1.createImport)({
+            moduleSpecifier: '../types',
+            typeOnlyNamedImports: [typeName],
+        }),
+    ]);
+    // Re-export entity type
+    sourceFile.addStatements(`\n// Re-export entity type for convenience\nexport type { ${typeName} };\n`);
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// GraphQL Document');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Add query document constant
+    sourceFile.addVariableStatement((0, ts_ast_1.createConst)(`${queryName}QueryDocument`, '`\n' + queryDocument + '`'));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Types');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Variables interface
+    sourceFile.addInterface((0, ts_ast_1.createInterface)(`${(0, utils_1.ucFirst)(singularName)}QueryVariables`, [
+        { name: 'id', type: 'string' },
+    ]));
+    // Result interface
+    sourceFile.addInterface((0, ts_ast_1.createInterface)(`${(0, utils_1.ucFirst)(singularName)}QueryResult`, [
+        { name: queryName, type: `${typeName} | null` },
+    ]));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Query Key');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Query key factory
+    sourceFile.addVariableStatement((0, ts_ast_1.createConst)(`${queryName}QueryKey`, `(id: string) =>
+  ['${typeName.toLowerCase()}', 'detail', id] as const`));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Hook');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Hook function
+    sourceFile.addFunction({
+        name: hookName,
+        isExported: true,
+        parameters: [
+            { name: 'id', type: 'string' },
+            {
+                name: 'options',
+                type: `Omit<UseQueryOptions<${(0, utils_1.ucFirst)(singularName)}QueryResult, Error>, 'queryKey' | 'queryFn'>`,
+                hasQuestionToken: true,
+            },
+        ],
+        statements: `return useQuery({
+    queryKey: ${queryName}QueryKey(id),
+    queryFn: () => execute<${(0, utils_1.ucFirst)(singularName)}QueryResult, ${(0, utils_1.ucFirst)(singularName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      { id }
+    ),
+    enabled: !!id && (options?.enabled !== false),
+    ...options,
+  });`,
+        docs: [
+            {
+                description: `Query hook for fetching a single ${typeName} by ID
+
+@example
+\`\`\`tsx
+const { data, isLoading } = ${hookName}('uuid-here');
+
+if (data?.${queryName}) {
+  console.log(data.${queryName}.id);
+}
+\`\`\``,
+            },
+        ],
+    });
+    // Add section comment for standalone functions
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Standalone Functions (non-React)');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Fetch function (standalone, no React)
+    sourceFile.addFunction({
+        name: `fetch${(0, utils_1.ucFirst)(singularName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            { name: 'id', type: 'string' },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: `Promise<${(0, utils_1.ucFirst)(singularName)}QueryResult>`,
+        statements: `return execute<${(0, utils_1.ucFirst)(singularName)}QueryResult, ${(0, utils_1.ucFirst)(singularName)}QueryVariables>(
+    ${queryName}QueryDocument,
+    { id },
+    options
+  );`,
+        docs: [
+            {
+                description: `Fetch a single ${typeName} by ID without React hooks
+
+@example
+\`\`\`ts
+const data = await fetch${(0, utils_1.ucFirst)(singularName)}Query('uuid-here');
+\`\`\``,
+            },
+        ],
+    });
+    // Prefetch function (for SSR/QueryClient)
+    sourceFile.addFunction({
+        name: `prefetch${(0, utils_1.ucFirst)(singularName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            { name: 'queryClient', type: 'QueryClient' },
+            { name: 'id', type: 'string' },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: 'Promise<void>',
+        statements: `await queryClient.prefetchQuery({
+    queryKey: ${queryName}QueryKey(id),
+    queryFn: () => execute<${(0, utils_1.ucFirst)(singularName)}QueryResult, ${(0, utils_1.ucFirst)(singularName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      { id },
+      options
+    ),
+  });`,
+        docs: [
+            {
+                description: `Prefetch a single ${typeName} for SSR or cache warming
+
+@example
+\`\`\`ts
+await prefetch${(0, utils_1.ucFirst)(singularName)}Query(queryClient, 'uuid-here');
+\`\`\``,
+            },
+        ],
+    });
+    return {
+        fileName: (0, utils_1.getSingleQueryFileName)(table),
+        content: (0, ts_ast_1.getFormattedOutput)(sourceFile),
+    };
+}
+// ============================================================================
+// Batch generator
+// ============================================================================
+/**
+ * Generate all query hook files for all tables
+ */
+function generateAllQueryHooks(tables) {
+    const files = [];
+    for (const table of tables) {
+        files.push(generateListQueryHook(table));
+        files.push(generateSingleQueryHook(table));
+    }
+    return files;
+}

package/cli/codegen/scalars.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared scalar mappings for code generation
+ */
+export declare const SCALAR_TS_MAP: Record<string, string>;
+export declare const SCALAR_FILTER_MAP: Record<string, string>;
+export declare const SCALAR_NAMES: Set<string>;
+export interface ScalarToTsOptions {
+    unknownScalar?: 'unknown' | 'name';
+    overrides?: Record<string, string>;
+}
+export declare function scalarToTsType(scalarName: string, options?: ScalarToTsOptions): string;
+export declare function scalarToFilterType(scalarName: string): string | null;

package/cli/codegen/scalars.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Shared scalar mappings for code generation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCALAR_NAMES = exports.SCALAR_FILTER_MAP = exports.SCALAR_TS_MAP = void 0;
+exports.scalarToTsType = scalarToTsType;
+exports.scalarToFilterType = scalarToFilterType;
+exports.SCALAR_TS_MAP = {
+    // Standard GraphQL scalars
+    String: 'string',
+    Int: 'number',
+    Float: 'number',
+    Boolean: 'boolean',
+    ID: 'string',
+    // PostGraphile scalars
+    UUID: 'string',
+    Cursor: 'string',
+    Datetime: 'string',
+    Date: 'string',
+    Time: 'string',
+    JSON: 'unknown',
+    BigInt: 'string',
+    BigFloat: 'string',
+    // Geometry types
+    GeoJSON: 'unknown',
+    Geometry: 'unknown',
+    Point: 'unknown',
+    // Interval
+    Interval: 'string',
+    // PostgreSQL-specific types
+    BitString: 'string',
+    FullText: 'string',
+    InternetAddress: 'string',
+    Inet: 'string',
+    Cidr: 'string',
+    MacAddr: 'string',
+    TsVector: 'string',
+    TsQuery: 'string',
+};
+exports.SCALAR_FILTER_MAP = {
+    String: 'StringFilter',
+    Int: 'IntFilter',
+    Float: 'FloatFilter',
+    Boolean: 'BooleanFilter',
+    UUID: 'UUIDFilter',
+    ID: 'UUIDFilter',
+    Datetime: 'DatetimeFilter',
+    Date: 'DateFilter',
+    Time: 'StringFilter',
+    JSON: 'JSONFilter',
+    BigInt: 'BigIntFilter',
+    BigFloat: 'BigFloatFilter',
+    BitString: 'BitStringFilter',
+    InternetAddress: 'InternetAddressFilter',
+    FullText: 'FullTextFilter',
+    Interval: 'StringFilter',
+};
+exports.SCALAR_NAMES = new Set(Object.keys(exports.SCALAR_TS_MAP));
+function scalarToTsType(scalarName, options = {}) {
+    const override = options.overrides?.[scalarName];
+    if (override)
+        return override;
+    const mapped = exports.SCALAR_TS_MAP[scalarName];
+    if (mapped)
+        return mapped;
+    return options.unknownScalar === 'unknown' ? 'unknown' : scalarName;
+}
+function scalarToFilterType(scalarName) {
+    return exports.SCALAR_FILTER_MAP[scalarName] ?? null;
+}

package/cli/codegen/schema-gql-ast.d.ts

@@ -0,0 +1,51 @@
+import type { DocumentNode, FieldNode, VariableDefinitionNode } from 'graphql';
+import type { CleanOperation, CleanArgument, CleanTypeRef, TypeRegistry } from '../../types/schema';
+export interface FieldSelectionConfig {
+    /** Max depth for nested object selections */
+    maxDepth: number;
+    /** Skip the 'query' field in payloads */
+    skipQueryField: boolean;
+    /** Type registry for resolving nested types */
+    typeRegistry?: TypeRegistry;
+}
+/**
+ * Build variable definitions from operation arguments
+ */
+export declare function buildVariableDefinitions(args: CleanArgument[]): VariableDefinitionNode[];
+/**
+ * Build field selections for an object type
+ * Recursively handles nested objects up to maxDepth
+ */
+export declare function buildFieldSelections(typeRef: CleanTypeRef, config: FieldSelectionConfig, currentDepth?: number): FieldNode[];
+export interface CustomQueryConfig {
+    operation: CleanOperation;
+    typeRegistry?: TypeRegistry;
+    maxDepth?: number;
+    skipQueryField?: boolean;
+}
+/**
+ * Build a custom query AST from a CleanOperation
+ */
+export declare function buildCustomQueryAST(config: CustomQueryConfig): DocumentNode;
+export interface CustomMutationConfig {
+    operation: CleanOperation;
+    typeRegistry?: TypeRegistry;
+    maxDepth?: number;
+    skipQueryField?: boolean;
+}
+/**
+ * Build a custom mutation AST from a CleanOperation
+ */
+export declare function buildCustomMutationAST(config: CustomMutationConfig): DocumentNode;
+/**
+ * Print a document AST to GraphQL string
+ */
+export declare function printGraphQL(ast: DocumentNode): string;
+/**
+ * Build and print a custom query in one call
+ */
+export declare function buildCustomQueryString(config: CustomQueryConfig): string;
+/**
+ * Build and print a custom mutation in one call
+ */
+export declare function buildCustomMutationString(config: CustomMutationConfig): string;