@constructive-io/graphql-query 3.2.4 → 3.3.0

package/esm/introspect/schema-query.js

@@ -0,0 +1,120 @@
+/**
+ * GraphQL Schema Introspection Query
+ *
+ * Full introspection query that captures all queries, mutations, and types
+ * from a GraphQL endpoint via the standard __schema query.
+ */
+/**
+ * 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 const 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/esm/introspect/transform-schema.js

@@ -0,0 +1,271 @@
+import { getBaseTypeName, isNonNull, unwrapType, } from '../types/introspection';
+// ============================================================================
+// 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
+ */
+export 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
+ */
+export 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)
+ */
+export 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.
+ */
+export 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
+ */
+export 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.)
+ */
+export function getCustomOperations(operations, tableOperationNames) {
+    return operations.filter((op) => !isTableOperation(op, tableOperationNames));
+}
+// Re-export utility functions from introspection types
+export { getBaseTypeName, isNonNull, unwrapType };

package/esm/introspect/transform.js

@@ -0,0 +1,38 @@
+/**
+ * Get table names from CleanTable array
+ */
+export function getTableNames(tables) {
+    return tables.map((t) => t.name);
+}
+/**
+ * Find a table by name
+ */
+export function findTable(tables, name) {
+    return tables.find((t) => t.name === name);
+}
+/**
+ * Filter tables by name pattern (glob-like)
+ */
+export 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/esm/meta-object/convert.js

@@ -1,3 +1,6 @@
+/**
+ * Convert from raw _meta schema response to internal MetaObject format
+ */
 export function convertFromMetaSchema(metaSchema) {
     const { _meta: { tables }, } = metaSchema;
     const result = {

package/esm/meta-object/format.json

@@ -5,44 +5,27 @@
     "definitions": {
         "field": {
             "type": "object",
-            "required": [
-                "name",
-                "type"
-            ],
+            "required": ["name", "type"],
             "additionalProperties": true,
             "properties": {
                 "name": {
                     "type": "string",
                     "default": "id",
-                    "examples": [
-                        "id"
-                    ]
+                    "examples": ["id"]
                 },
                 "type": {
                     "type": "object",
-                    "required": [
-                        "pgType",
-                        "gqlType"
-                    ],
+                    "required": ["pgType", "gqlType"],
                     "additionalProperties": true,
                     "properties": {
                         "gqlType": {
-                            "type": [
-                                "string",
-                                "null"
-                            ]
+                            "type": ["string", "null"]
                         },
                         "pgType": {
-                            "type": [
-                                "string",
-                                "null"
-                            ]
+                            "type": ["string", "null"]
                         },
                         "subtype": {
-                            "type": [
-                                "string",
-                                "null"
-                            ]
+                            "type": ["string", "null"]
                         }
                     }
                 }
@@ -58,9 +41,7 @@
                     "name": {
                         "type": "string",
                         "default": "User",
-                        "examples": [
-                            "User"
-                        ]
+                        "examples": ["User"]
                     },
                     "fields": {
                         "type": "array",
@@ -88,9 +69,7 @@
                                 "refTable": {
                                     "type": "string",
                                     "default": "User",
-                                    "examples": [
-                                        "User"
-                                    ]
+                                    "examples": ["User"]
                                 },
                                 "fromKey": {
                                     "$ref": "#/definitions/field"
@@ -99,25 +78,16 @@
                                     "$ref": "#/definitions/field"
                                 }
                             },
-                            "required": [
-                                "refTable",
-                                "fromKey",
-                                "toKey"
-                            ],
+                            "required": ["refTable", "fromKey", "toKey"],
                             "additionalProperties": false
                         }
                     }
                 },
-                "required": [
-                    "name",
-                    "fields"
-                ],
+                "required": ["name", "fields"],
                 "additionalProperties": false
             }
         }
     },
-    "required": [
-        "tables"
-    ],
+    "required": ["tables"],
     "additionalProperties": false
 }

package/esm/meta-object/validate.js

@@ -1,12 +1,28 @@
 import Ajv from 'ajv';
 import format from './format.json';
+let cachedAjv = null;
+let cachedValidator = null;
+function getValidator() {
+    if (!cachedAjv) {
+        cachedAjv = new Ajv({ allErrors: true });
+        cachedValidator = cachedAjv.compile(format);
+    }
+    return {
+        ajv: cachedAjv,
+        validator: cachedValidator,
+    };
+}
+/**
+ * Validate a MetaObject against the JSON schema
+ * @returns true if valid, or an object with errors and message if invalid
+ */
 export function validateMetaObject(obj) {
-    const ajv = new Ajv({ allErrors: true });
-    const valid = ajv.validate(format, obj);
+    const { ajv, validator } = getValidator();
+    const valid = validator(obj);
     if (valid)
         return true;
     return {
-        errors: ajv.errors,
-        message: ajv.errorsText(ajv.errors, { separator: '\n' }),
+        errors: validator.errors,
+        message: ajv.errorsText(validator.errors, { separator: '\n' }),
     };
 }

package/esm/query-builder.js

@@ -1,5 +1,5 @@
 import { print as gqlPrint } from 'graphql';
-import { camelize, pluralize, underscore } from 'inflection';
+import { camelize, pluralize, underscore } from 'inflekt';
 import { createOne, deleteOne, getAll, getCount, getMany, getOne, patchOne, } from './ast';
 import { validateMetaObject } from './meta-object';
 export * as MetaObject from './meta-object';
@@ -9,7 +9,6 @@ export class QueryBuilder {
     _meta;
     _models;
     _model;
-    _fields;
     _key;
     _queryName;
     _ast;
@@ -33,21 +32,16 @@ export class QueryBuilder {
      * Save all gql queries and mutations by model name for quicker lookup
      */
     initModelMap() {
-        this._models = Object.keys(this._introspection).reduce((map, key) => {
-            const defn = this._introspection[key];
-            map = {
-                ...map,
-                [defn.model]: {
-                    ...map[defn.model],
-                    ...{ [key]: defn },
-                },
-            };
-            return map;
-        }, {});
+        this._models = {};
+        for (const [key, defn] of Object.entries(this._introspection)) {
+            if (!this._models[defn.model]) {
+                this._models[defn.model] = {};
+            }
+            this._models[defn.model][key] = defn;
+        }
     }
     clear() {
         this._model = '';
-        this._fields = [];
         this._key = null;
         this._queryName = '';
         this._ast = null;
@@ -265,7 +259,8 @@ function pickScalarFields(selection, defn) {
             return true;
         return Object.keys(selection).includes(fieldName);
     })
-        .filter((fieldName) => !isRelationalField(fieldName, modelMeta) && isInTableSchema(fieldName))
+        .filter((fieldName) => !isRelationalField(fieldName, modelMeta) &&
+        isInTableSchema(fieldName))
         .map((fieldName) => ({
         name: fieldName,
         isObject: false,
@@ -310,9 +305,10 @@ function pickAllFields(selection, defn) {
             }
             const referencedForeignConstraint = modelMeta.foreignConstraints.find((constraint) => constraint.fromKey.name === fieldName ||
                 constraint.fromKey.alias === fieldName);
-            const subFields = Object.keys(fieldOptions.select).filter((subField) => {
+            const selectOptions = fieldOptions;
+            const subFields = Object.keys(selectOptions.select).filter((subField) => {
                 return (!isRelationalField(subField, modelMeta) &&
-                    isWhiteListed(fieldOptions.select[subField]));
+                    isWhiteListed(selectOptions.select[subField]));
             });
             const isBelongTo = !!referencedForeignConstraint;
             const fieldSelection = {
@@ -320,7 +316,7 @@ function pickAllFields(selection, defn) {
                 isObject: true,
                 isBelongTo,
                 selection: subFields.map((name) => ({ name, isObject: false })),
-                variables: fieldOptions.variables,
+                variables: selectOptions.variables,
             };
             // Need to further expand selection of object fields,
             // but only non-graphql-builtin, non-relation fields

package/esm/types/index.js

@@ -0,0 +1,18 @@
+/**
+ * Barrel export for all types
+ *
+ * Re-exports both the original QueryBuilder runtime types (core.ts)
+ * and the codegen-style types (schema, introspection, query, mutation, selection)
+ */
+// Original QueryBuilder runtime types
+export * from './core';
+// Codegen-style schema types (CleanTable, CleanField, etc.)
+export * from './schema';
+// Introspection types
+export * from './introspection';
+// Query types (QueryOptions, Filter, etc.)
+export * from './query';
+// Mutation types
+export * from './mutation';
+// Selection types (FieldSelection presets, SimpleFieldSelection, etc.)
+export * from './selection';