@constructive-io/graphql-query 3.2.4 → 3.3.0

package/introspect/schema-query.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GraphQL Schema Introspection Query
+ *
+ * Full introspection query that captures all queries, mutations, and types
+ * from a GraphQL endpoint via the standard __schema query.
+ */
+import type { IntrospectionQueryResponse } from '../types/introspection';
+/**
+ * Full schema introspection query
+ *
+ * Captures:
+ * - All Query fields with args and return types
+ * - All Mutation fields with args and return types
+ * - All types (OBJECT, INPUT_OBJECT, ENUM, SCALAR) for resolution
+ *
+ * Uses a recursive TypeRef fragment to handle deeply nested type wrappers
+ * (e.g., [String!]! = NON_NULL(LIST(NON_NULL(SCALAR))))
+ */
+export declare const SCHEMA_INTROSPECTION_QUERY = "\nquery IntrospectSchema {\n  __schema {\n    queryType {\n      name\n    }\n    mutationType {\n      name\n    }\n    subscriptionType {\n      name\n    }\n    types {\n      kind\n      name\n      description\n      fields(includeDeprecated: true) {\n        name\n        description\n        args {\n          name\n          description\n          type {\n            ...TypeRef\n          }\n          defaultValue\n        }\n        type {\n          ...TypeRef\n        }\n        isDeprecated\n        deprecationReason\n      }\n      inputFields {\n        name\n        description\n        type {\n          ...TypeRef\n        }\n        defaultValue\n      }\n      interfaces {\n        name\n      }\n      enumValues(includeDeprecated: true) {\n        name\n        description\n        isDeprecated\n        deprecationReason\n      }\n      possibleTypes {\n        name\n      }\n    }\n    directives {\n      name\n      description\n      locations\n      args {\n        name\n        description\n        type {\n          ...TypeRef\n        }\n        defaultValue\n      }\n    }\n  }\n}\n\nfragment TypeRef on __Type {\n  kind\n  name\n  ofType {\n    kind\n    name\n    ofType {\n      kind\n      name\n      ofType {\n        kind\n        name\n        ofType {\n          kind\n          name\n          ofType {\n            kind\n            name\n            ofType {\n              kind\n              name\n              ofType {\n                kind\n                name\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";
+export type { IntrospectionQueryResponse };

package/introspect/schema-query.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * GraphQL Schema Introspection Query
+ *
+ * Full introspection query that captures all queries, mutations, and types
+ * from a GraphQL endpoint via the standard __schema query.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_INTROSPECTION_QUERY = void 0;
+/**
+ * Full schema introspection query
+ *
+ * Captures:
+ * - All Query fields with args and return types
+ * - All Mutation fields with args and return types
+ * - All types (OBJECT, INPUT_OBJECT, ENUM, SCALAR) for resolution
+ *
+ * Uses a recursive TypeRef fragment to handle deeply nested type wrappers
+ * (e.g., [String!]! = NON_NULL(LIST(NON_NULL(SCALAR))))
+ */
+exports.SCHEMA_INTROSPECTION_QUERY = `
+query IntrospectSchema {
+  __schema {
+    queryType {
+      name
+    }
+    mutationType {
+      name
+    }
+    subscriptionType {
+      name
+    }
+    types {
+      kind
+      name
+      description
+      fields(includeDeprecated: true) {
+        name
+        description
+        args {
+          name
+          description
+          type {
+            ...TypeRef
+          }
+          defaultValue
+        }
+        type {
+          ...TypeRef
+        }
+        isDeprecated
+        deprecationReason
+      }
+      inputFields {
+        name
+        description
+        type {
+          ...TypeRef
+        }
+        defaultValue
+      }
+      interfaces {
+        name
+      }
+      enumValues(includeDeprecated: true) {
+        name
+        description
+        isDeprecated
+        deprecationReason
+      }
+      possibleTypes {
+        name
+      }
+    }
+    directives {
+      name
+      description
+      locations
+      args {
+        name
+        description
+        type {
+          ...TypeRef
+        }
+        defaultValue
+      }
+    }
+  }
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+`;

package/introspect/transform-schema.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Transform GraphQL introspection data to clean operation types
+ *
+ * This module converts raw introspection responses into the CleanOperation
+ * format used by code generators.
+ */
+import type { IntrospectionQueryResponse, IntrospectionType } from '../types/introspection';
+import { getBaseTypeName, isNonNull, unwrapType } from '../types/introspection';
+import type { CleanOperation, TypeRegistry } from '../types/schema';
+/**
+ * Build a type registry from introspection types
+ * Maps type names to their full resolved definitions
+ *
+ * This is a two-pass process to handle circular references:
+ * 1. First pass: Create all type entries with basic info
+ * 2. Second pass: Resolve fields with references to other types
+ */
+export declare function buildTypeRegistry(types: IntrospectionType[]): TypeRegistry;
+export interface TransformSchemaResult {
+    queries: CleanOperation[];
+    mutations: CleanOperation[];
+    typeRegistry: TypeRegistry;
+}
+/**
+ * Transform introspection response to clean operations
+ */
+export declare function transformSchemaToOperations(response: IntrospectionQueryResponse): TransformSchemaResult;
+/**
+ * Filter operations by include/exclude patterns
+ * Uses glob-like patterns (supports * wildcard)
+ */
+export declare function filterOperations(operations: CleanOperation[], include?: string[], exclude?: string[]): CleanOperation[];
+/**
+ * Result type for table operation names lookup
+ */
+export interface TableOperationNames {
+    queries: Set<string>;
+    mutations: Set<string>;
+}
+/**
+ * Get the set of table-related operation names from tables
+ * Used to identify which operations are already covered by table generators
+ *
+ * IMPORTANT: This uses EXACT matches only from _meta.query fields.
+ * Any operation not explicitly listed in _meta will flow through as a
+ * custom operation, ensuring 100% coverage of the schema.
+ *
+ * Table operations (generated by table generators):
+ * - Queries: all (list), one (single by PK)
+ * - Mutations: create, update (by PK), delete (by PK)
+ *
+ * Custom operations (generated by custom operation generators):
+ * - Unique constraint lookups: *ByUsername, *ByEmail, etc.
+ * - Unique constraint mutations: update*By*, delete*By*
+ * - True custom operations: login, register, bootstrapUser, etc.
+ */
+export declare function getTableOperationNames(tables: Array<{
+    name: string;
+    query?: {
+        all: string;
+        one: string | null;
+        create: string;
+        update: string | null;
+        delete: string | null;
+    };
+}>): TableOperationNames;
+/**
+ * Check if an operation is a table operation (already handled by table generators)
+ *
+ * Uses EXACT match only - no pattern matching. This ensures:
+ * 1. Only operations explicitly in _meta.query are treated as table operations
+ * 2. All other operations (including update*By*, delete*By*) become custom operations
+ * 3. 100% schema coverage is guaranteed
+ */
+export declare function isTableOperation(operation: CleanOperation, tableOperationNames: TableOperationNames): boolean;
+/**
+ * Get only custom operations (not covered by table generators)
+ *
+ * This returns ALL operations that are not exact matches for table CRUD operations.
+ * Includes:
+ * - Unique constraint queries (*ByUsername, *ByEmail, etc.)
+ * - Unique constraint mutations (update*By*, delete*By*)
+ * - True custom operations (login, register, bootstrapUser, etc.)
+ */
+export declare function getCustomOperations(operations: CleanOperation[], tableOperationNames: TableOperationNames): CleanOperation[];
+export { getBaseTypeName, isNonNull, unwrapType };

package/introspect/transform-schema.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapType = exports.isNonNull = exports.getBaseTypeName = void 0;
+exports.buildTypeRegistry = buildTypeRegistry;
+exports.transformSchemaToOperations = transformSchemaToOperations;
+exports.filterOperations = filterOperations;
+exports.getTableOperationNames = getTableOperationNames;
+exports.isTableOperation = isTableOperation;
+exports.getCustomOperations = getCustomOperations;
+const introspection_1 = require("../types/introspection");
+Object.defineProperty(exports, "getBaseTypeName", { enumerable: true, get: function () { return introspection_1.getBaseTypeName; } });
+Object.defineProperty(exports, "isNonNull", { enumerable: true, get: function () { return introspection_1.isNonNull; } });
+Object.defineProperty(exports, "unwrapType", { enumerable: true, get: function () { return introspection_1.unwrapType; } });
+// ============================================================================
+// Type Registry Builder
+// ============================================================================
+/**
+ * Build a type registry from introspection types
+ * Maps type names to their full resolved definitions
+ *
+ * This is a two-pass process to handle circular references:
+ * 1. First pass: Create all type entries with basic info
+ * 2. Second pass: Resolve fields with references to other types
+ */
+function buildTypeRegistry(types) {
+    const registry = new Map();
+    // First pass: Create all type entries
+    for (const type of types) {
+        // Skip built-in types that start with __
+        if (type.name.startsWith('__'))
+            continue;
+        const resolvedType = {
+            kind: type.kind,
+            name: type.name,
+            description: type.description ?? undefined,
+        };
+        // Resolve enum values for ENUM types (no circular refs possible)
+        if (type.kind === 'ENUM' && type.enumValues) {
+            resolvedType.enumValues = type.enumValues.map((ev) => ev.name);
+        }
+        // Resolve possible types for UNION types (no circular refs for names)
+        if (type.kind === 'UNION' && type.possibleTypes) {
+            resolvedType.possibleTypes = type.possibleTypes.map((pt) => pt.name);
+        }
+        registry.set(type.name, resolvedType);
+    }
+    // Second pass: Resolve fields (now that all types exist in registry)
+    for (const type of types) {
+        if (type.name.startsWith('__'))
+            continue;
+        const resolvedType = registry.get(type.name);
+        if (!resolvedType)
+            continue;
+        // Resolve fields for OBJECT types
+        if (type.kind === 'OBJECT' && type.fields) {
+            resolvedType.fields = type.fields.map((field) => transformFieldToCleanObjectFieldShallow(field));
+        }
+        // Resolve input fields for INPUT_OBJECT types
+        if (type.kind === 'INPUT_OBJECT' && type.inputFields) {
+            resolvedType.inputFields = type.inputFields.map((field) => transformInputValueToCleanArgumentShallow(field));
+        }
+    }
+    return registry;
+}
+/**
+ * Transform field to CleanObjectField without resolving nested types
+ * (shallow transformation to avoid circular refs)
+ */
+function transformFieldToCleanObjectFieldShallow(field) {
+    return {
+        name: field.name,
+        type: transformTypeRefShallow(field.type),
+        description: field.description ?? undefined,
+    };
+}
+/**
+ * Transform input value to CleanArgument without resolving nested types
+ */
+function transformInputValueToCleanArgumentShallow(inputValue) {
+    return {
+        name: inputValue.name,
+        type: transformTypeRefShallow(inputValue.type),
+        defaultValue: inputValue.defaultValue ?? undefined,
+        description: inputValue.description ?? undefined,
+    };
+}
+/**
+ * Transform TypeRef without resolving nested types
+ * Only handles wrappers (LIST, NON_NULL) and stores the type name
+ */
+function transformTypeRefShallow(typeRef) {
+    const cleanRef = {
+        kind: typeRef.kind,
+        name: typeRef.name,
+    };
+    if (typeRef.ofType) {
+        cleanRef.ofType = transformTypeRefShallow(typeRef.ofType);
+    }
+    return cleanRef;
+}
+/**
+ * Transform introspection response to clean operations
+ */
+function transformSchemaToOperations(response) {
+    const { __schema: schema } = response;
+    const { types, queryType, mutationType } = schema;
+    // Build type registry first
+    const typeRegistry = buildTypeRegistry(types);
+    // Find Query and Mutation types
+    const queryTypeDef = types.find((t) => t.name === queryType.name);
+    const mutationTypeDef = mutationType
+        ? types.find((t) => t.name === mutationType.name)
+        : null;
+    // Transform queries
+    const queries = queryTypeDef?.fields
+        ? queryTypeDef.fields.map((field) => transformFieldToCleanOperation(field, 'query', types))
+        : [];
+    // Transform mutations
+    const mutations = mutationTypeDef?.fields
+        ? mutationTypeDef.fields.map((field) => transformFieldToCleanOperation(field, 'mutation', types))
+        : [];
+    return { queries, mutations, typeRegistry };
+}
+// ============================================================================
+// Field to Operation Transformation
+// ============================================================================
+/**
+ * Transform an introspection field to a CleanOperation
+ */
+function transformFieldToCleanOperation(field, kind, types) {
+    return {
+        name: field.name,
+        kind,
+        args: field.args.map((arg) => transformInputValueToCleanArgument(arg, types)),
+        returnType: transformTypeRefToCleanTypeRef(field.type, types),
+        description: field.description ?? undefined,
+        isDeprecated: field.isDeprecated,
+        deprecationReason: field.deprecationReason ?? undefined,
+    };
+}
+/**
+ * Transform an input value to CleanArgument
+ */
+function transformInputValueToCleanArgument(inputValue, types) {
+    return {
+        name: inputValue.name,
+        type: transformTypeRefToCleanTypeRef(inputValue.type, types),
+        defaultValue: inputValue.defaultValue ?? undefined,
+        description: inputValue.description ?? undefined,
+    };
+}
+// ============================================================================
+// Type Reference Transformation
+// ============================================================================
+/**
+ * Transform an introspection TypeRef to CleanTypeRef
+ * Recursively handles wrapper types (LIST, NON_NULL)
+ *
+ * NOTE: We intentionally do NOT resolve nested fields here to avoid
+ * infinite recursion from circular type references. Fields are resolved
+ * lazily via the TypeRegistry when needed for code generation.
+ */
+function transformTypeRefToCleanTypeRef(typeRef, types) {
+    const cleanRef = {
+        kind: typeRef.kind,
+        name: typeRef.name,
+    };
+    // Recursively transform ofType for wrappers (LIST, NON_NULL)
+    if (typeRef.ofType) {
+        cleanRef.ofType = transformTypeRefToCleanTypeRef(typeRef.ofType, types);
+    }
+    // For named types, only resolve enum values (they don't have circular refs)
+    // Fields are NOT resolved here - they're resolved via TypeRegistry during codegen
+    if (typeRef.name && !typeRef.ofType) {
+        const typeDef = types.find((t) => t.name === typeRef.name);
+        if (typeDef) {
+            // Add enum values for ENUM types (safe, no recursion)
+            if (typeDef.kind === 'ENUM' && typeDef.enumValues) {
+                cleanRef.enumValues = typeDef.enumValues.map((ev) => ev.name);
+            }
+            // NOTE: OBJECT and INPUT_OBJECT fields are resolved via TypeRegistry
+            // to avoid circular reference issues
+        }
+    }
+    return cleanRef;
+}
+// ============================================================================
+// Operation Filtering
+// ============================================================================
+/**
+ * Filter operations by include/exclude patterns
+ * Uses glob-like patterns (supports * wildcard)
+ */
+function filterOperations(operations, include, exclude) {
+    let result = operations;
+    if (include && include.length > 0) {
+        result = result.filter((op) => matchesPatterns(op.name, include));
+    }
+    if (exclude && exclude.length > 0) {
+        result = result.filter((op) => !matchesPatterns(op.name, exclude));
+    }
+    return result;
+}
+/**
+ * Check if a name matches any of the patterns
+ * Supports simple glob patterns with * wildcard
+ */
+function matchesPatterns(name, patterns) {
+    return patterns.some((pattern) => {
+        if (pattern === '*')
+            return true;
+        if (pattern.includes('*')) {
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+            return regex.test(name);
+        }
+        return name === pattern;
+    });
+}
+/**
+ * Get the set of table-related operation names from tables
+ * Used to identify which operations are already covered by table generators
+ *
+ * IMPORTANT: This uses EXACT matches only from _meta.query fields.
+ * Any operation not explicitly listed in _meta will flow through as a
+ * custom operation, ensuring 100% coverage of the schema.
+ *
+ * Table operations (generated by table generators):
+ * - Queries: all (list), one (single by PK)
+ * - Mutations: create, update (by PK), delete (by PK)
+ *
+ * Custom operations (generated by custom operation generators):
+ * - Unique constraint lookups: *ByUsername, *ByEmail, etc.
+ * - Unique constraint mutations: update*By*, delete*By*
+ * - True custom operations: login, register, bootstrapUser, etc.
+ */
+function getTableOperationNames(tables) {
+    const queries = new Set();
+    const mutations = new Set();
+    for (const table of tables) {
+        if (table.query) {
+            // Add exact query names from _meta
+            queries.add(table.query.all);
+            if (table.query.one) {
+                queries.add(table.query.one);
+            }
+            // Add exact mutation names from _meta
+            mutations.add(table.query.create);
+            if (table.query.update)
+                mutations.add(table.query.update);
+            if (table.query.delete)
+                mutations.add(table.query.delete);
+        }
+    }
+    return { queries, mutations };
+}
+/**
+ * Check if an operation is a table operation (already handled by table generators)
+ *
+ * Uses EXACT match only - no pattern matching. This ensures:
+ * 1. Only operations explicitly in _meta.query are treated as table operations
+ * 2. All other operations (including update*By*, delete*By*) become custom operations
+ * 3. 100% schema coverage is guaranteed
+ */
+function isTableOperation(operation, tableOperationNames) {
+    if (operation.kind === 'query') {
+        return tableOperationNames.queries.has(operation.name);
+    }
+    return tableOperationNames.mutations.has(operation.name);
+}
+/**
+ * Get only custom operations (not covered by table generators)
+ *
+ * This returns ALL operations that are not exact matches for table CRUD operations.
+ * Includes:
+ * - Unique constraint queries (*ByUsername, *ByEmail, etc.)
+ * - Unique constraint mutations (update*By*, delete*By*)
+ * - True custom operations (login, register, bootstrapUser, etc.)
+ */
+function getCustomOperations(operations, tableOperationNames) {
+    return operations.filter((op) => !isTableOperation(op, tableOperationNames));
+}

package/introspect/transform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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';
+/**
+ * Get table names from CleanTable array
+ */
+export declare function getTableNames(tables: CleanTable[]): string[];
+/**
+ * Find a table by name
+ */
+export declare function findTable(tables: CleanTable[], name: string): CleanTable | undefined;
+/**
+ * Filter tables by name pattern (glob-like)
+ */
+export declare function filterTables(tables: CleanTable[], include?: string[], exclude?: string[]): CleanTable[];

package/introspect/transform.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTableNames = getTableNames;
+exports.findTable = findTable;
+exports.filterTables = filterTables;
+/**
+ * Get table names from CleanTable array
+ */
+function getTableNames(tables) {
+    return tables.map((t) => t.name);
+}
+/**
+ * Find a table by name
+ */
+function findTable(tables, name) {
+    return tables.find((t) => t.name === name);
+}
+/**
+ * Filter tables by name pattern (glob-like)
+ */
+function filterTables(tables, include, exclude) {
+    let result = tables;
+    if (include && include.length > 0) {
+        result = result.filter((t) => matchesPatterns(t.name, include));
+    }
+    if (exclude && exclude.length > 0) {
+        result = result.filter((t) => !matchesPatterns(t.name, exclude));
+    }
+    return result;
+}
+/**
+ * Check if a name matches any of the patterns
+ * Supports simple glob patterns with * wildcard
+ */
+function matchesPatterns(name, patterns) {
+    return patterns.some((pattern) => {
+        if (pattern.includes('*')) {
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+            return regex.test(name);
+        }
+        return name === pattern;
+    });
+}

package/meta-object/convert.d.ts

@@ -58,5 +58,8 @@ interface ConvertedTable {
 interface ConvertedMetaObject {
     tables: ConvertedTable[];
 }
+/**
+ * Convert from raw _meta schema response to internal MetaObject format
+ */
 export declare function convertFromMetaSchema(metaSchema: MetaSchemaInput): ConvertedMetaObject;
 export {};

package/meta-object/convert.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertFromMetaSchema = convertFromMetaSchema;
+/**
+ * Convert from raw _meta schema response to internal MetaObject format
+ */
 function convertFromMetaSchema(metaSchema) {
     const { _meta: { tables }, } = metaSchema;
     const result = {