@constructive-io/graphql-codegen 2.19.0 → 2.20.0

package/esm/cli/codegen/queries.js

@@ -0,0 +1,433 @@
+import { createProject, createSourceFile, getFormattedOutput, createFileHeader, createImport, createInterface, createConst, createTypeAlias, createUnionType, createFilterInterface, } from './ts-ast';
+import { buildListQueryAST, buildSingleQueryAST, printGraphQL, } from './gql-ast';
+import { getTableNames, getListQueryHookName, getSingleQueryHookName, getListQueryFileName, getSingleQueryFileName, getAllRowsQueryName, getSingleRowQueryName, getFilterTypeName, getOrderByTypeName, getScalarFields, getScalarFilterType, toScreamingSnake, ucFirst, } from './utils';
+// ============================================================================
+// List query hook generator
+// ============================================================================
+/**
+ * Generate list query hook file content using AST
+ */
+export function generateListQueryHook(table) {
+    const project = createProject();
+    const { typeName, pluralName } = getTableNames(table);
+    const hookName = getListQueryHookName(table);
+    const queryName = getAllRowsQueryName(table);
+    const filterTypeName = getFilterTypeName(table);
+    const orderByTypeName = getOrderByTypeName(table);
+    const scalarFields = getScalarFields(table);
+    // Generate GraphQL document via AST
+    const queryAST = buildListQueryAST({ table });
+    const queryDocument = printGraphQL(queryAST);
+    const sourceFile = createSourceFile(project, getListQueryFileName(table));
+    // Add file header as leading comment
+    sourceFile.insertText(0, 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 = getScalarFilterType(field.type.gqlType);
+        if (filterType) {
+            filterTypesUsed.add(filterType);
+        }
+    }
+    // Add imports
+    sourceFile.addImportDeclarations([
+        createImport({
+            moduleSpecifier: '@tanstack/react-query',
+            namedImports: ['useQuery'],
+            typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
+        }),
+        createImport({
+            moduleSpecifier: '../client',
+            namedImports: ['execute'],
+            typeOnlyNamedImports: ['ExecuteOptions'],
+        }),
+        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(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 = getScalarFilterType(field.type.gqlType);
+        return filterType ? { fieldName: field.name, filterType } : null;
+    })
+        .filter((f) => f !== null);
+    sourceFile.addInterface(createFilterInterface(filterTypeName, fieldFilters));
+    // Generate OrderBy type
+    const orderByValues = [
+        ...scalarFields.flatMap((f) => [
+            `${toScreamingSnake(f.name)}_ASC`,
+            `${toScreamingSnake(f.name)}_DESC`,
+        ]),
+        'NATURAL',
+        'PRIMARY_KEY_ASC',
+        'PRIMARY_KEY_DESC',
+    ];
+    sourceFile.addTypeAlias(createTypeAlias(orderByTypeName, 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(createInterface(`${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(createInterface(`${ucFirst(pluralName)}QueryResult`, resultProps));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Query Key');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Query key factory
+    sourceFile.addVariableStatement(createConst(`${queryName}QueryKey`, `(variables?: ${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: `${ucFirst(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: `Omit<UseQueryOptions<${ucFirst(pluralName)}QueryResult, Error>, 'queryKey' | 'queryFn'>`,
+                hasQuestionToken: true,
+            },
+        ],
+        statements: `return useQuery({
+    queryKey: ${queryName}QueryKey(variables),
+    queryFn: () => execute<${ucFirst(pluralName)}QueryResult, ${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${ucFirst(pluralName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            {
+                name: 'variables',
+                type: `${ucFirst(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: `Promise<${ucFirst(pluralName)}QueryResult>`,
+        statements: `return execute<${ucFirst(pluralName)}QueryResult, ${ucFirst(pluralName)}QueryVariables>(
+    ${queryName}QueryDocument,
+    variables,
+    options
+  );`,
+        docs: [
+            {
+                description: `Fetch ${typeName} list without React hooks
+
+@example
+\`\`\`ts
+// Direct fetch
+const data = await fetch${ucFirst(pluralName)}Query({ first: 10 });
+
+// With QueryClient
+const data = await queryClient.fetchQuery({
+  queryKey: ${queryName}QueryKey(variables),
+  queryFn: () => fetch${ucFirst(pluralName)}Query(variables),
+});
+\`\`\``,
+            },
+        ],
+    });
+    // Prefetch function (for SSR/QueryClient)
+    sourceFile.addFunction({
+        name: `prefetch${ucFirst(pluralName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            {
+                name: 'queryClient',
+                type: 'QueryClient',
+            },
+            {
+                name: 'variables',
+                type: `${ucFirst(pluralName)}QueryVariables`,
+                hasQuestionToken: true,
+            },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: 'Promise<void>',
+        statements: `await queryClient.prefetchQuery({
+    queryKey: ${queryName}QueryKey(variables),
+    queryFn: () => execute<${ucFirst(pluralName)}QueryResult, ${ucFirst(pluralName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      variables,
+      options
+    ),
+  });`,
+        docs: [
+            {
+                description: `Prefetch ${typeName} list for SSR or cache warming
+
+@example
+\`\`\`ts
+await prefetch${ucFirst(pluralName)}Query(queryClient, { first: 10 });
+\`\`\``,
+            },
+        ],
+    });
+    return {
+        fileName: getListQueryFileName(table),
+        content: getFormattedOutput(sourceFile),
+    };
+}
+// ============================================================================
+// Single item query hook generator
+// ============================================================================
+/**
+ * Generate single item query hook file content using AST
+ */
+export function generateSingleQueryHook(table) {
+    const project = createProject();
+    const { typeName, singularName } = getTableNames(table);
+    const hookName = getSingleQueryHookName(table);
+    const queryName = getSingleRowQueryName(table);
+    // Generate GraphQL document via AST
+    const queryAST = buildSingleQueryAST({ table });
+    const queryDocument = printGraphQL(queryAST);
+    const sourceFile = createSourceFile(project, getSingleQueryFileName(table));
+    // Add file header
+    sourceFile.insertText(0, createFileHeader(`Single item query hook for ${typeName}`) + '\n\n');
+    // Add imports
+    sourceFile.addImportDeclarations([
+        createImport({
+            moduleSpecifier: '@tanstack/react-query',
+            namedImports: ['useQuery'],
+            typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
+        }),
+        createImport({
+            moduleSpecifier: '../client',
+            namedImports: ['execute'],
+            typeOnlyNamedImports: ['ExecuteOptions'],
+        }),
+        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(createConst(`${queryName}QueryDocument`, '`\n' + queryDocument + '`'));
+    // Add section comment
+    sourceFile.addStatements('\n// ============================================================================');
+    sourceFile.addStatements('// Types');
+    sourceFile.addStatements('// ============================================================================\n');
+    // Variables interface
+    sourceFile.addInterface(createInterface(`${ucFirst(singularName)}QueryVariables`, [
+        { name: 'id', type: 'string' },
+    ]));
+    // Result interface
+    sourceFile.addInterface(createInterface(`${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(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<${ucFirst(singularName)}QueryResult, Error>, 'queryKey' | 'queryFn'>`,
+                hasQuestionToken: true,
+            },
+        ],
+        statements: `return useQuery({
+    queryKey: ${queryName}QueryKey(id),
+    queryFn: () => execute<${ucFirst(singularName)}QueryResult, ${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${ucFirst(singularName)}Query`,
+        isExported: true,
+        isAsync: true,
+        parameters: [
+            { name: 'id', type: 'string' },
+            {
+                name: 'options',
+                type: 'ExecuteOptions',
+                hasQuestionToken: true,
+            },
+        ],
+        returnType: `Promise<${ucFirst(singularName)}QueryResult>`,
+        statements: `return execute<${ucFirst(singularName)}QueryResult, ${ucFirst(singularName)}QueryVariables>(
+    ${queryName}QueryDocument,
+    { id },
+    options
+  );`,
+        docs: [
+            {
+                description: `Fetch a single ${typeName} by ID without React hooks
+
+@example
+\`\`\`ts
+const data = await fetch${ucFirst(singularName)}Query('uuid-here');
+\`\`\``,
+            },
+        ],
+    });
+    // Prefetch function (for SSR/QueryClient)
+    sourceFile.addFunction({
+        name: `prefetch${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<${ucFirst(singularName)}QueryResult, ${ucFirst(singularName)}QueryVariables>(
+      ${queryName}QueryDocument,
+      { id },
+      options
+    ),
+  });`,
+        docs: [
+            {
+                description: `Prefetch a single ${typeName} for SSR or cache warming
+
+@example
+\`\`\`ts
+await prefetch${ucFirst(singularName)}Query(queryClient, 'uuid-here');
+\`\`\``,
+            },
+        ],
+    });
+    return {
+        fileName: getSingleQueryFileName(table),
+        content: getFormattedOutput(sourceFile),
+    };
+}
+// ============================================================================
+// Batch generator
+// ============================================================================
+/**
+ * Generate all query hook files for all tables
+ */
+export function generateAllQueryHooks(tables) {
+    const files = [];
+    for (const table of tables) {
+        files.push(generateListQueryHook(table));
+        files.push(generateSingleQueryHook(table));
+    }
+    return files;
+}

package/esm/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/esm/cli/codegen/scalars.js

@@ -0,0 +1,66 @@
+/**
+ * Shared scalar mappings for code generation
+ */
+export const 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',
+};
+export const 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',
+};
+export const SCALAR_NAMES = new Set(Object.keys(SCALAR_TS_MAP));
+export function scalarToTsType(scalarName, options = {}) {
+    const override = options.overrides?.[scalarName];
+    if (override)
+        return override;
+    const mapped = SCALAR_TS_MAP[scalarName];
+    if (mapped)
+        return mapped;
+    return options.unknownScalar === 'unknown' ? 'unknown' : scalarName;
+}
+export function scalarToFilterType(scalarName) {
+    return SCALAR_FILTER_MAP[scalarName] ?? null;
+}

package/esm/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;