@constructive-io/graphql-query 3.2.4 → 3.3.0

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;
+}

package/types/mutation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Mutation-related types
+ */
+import type { FieldSelection } from './selection';
+/**
+ * Options for mutation operations
+ */
+export interface MutationOptions {
+    /** Fields to return after mutation */
+    returning?: string[];
+    /** Field selection for returned data */
+    fieldSelection?: FieldSelection;
+}
+/**
+ * Input for create mutations
+ * Wraps the actual data in PostGraphile's expected format
+ */
+export interface CreateInput<T = Record<string, unknown>> {
+    [tableName: string]: T;
+}
+/**
+ * Input for update mutations
+ */
+export interface UpdateInput<T = Record<string, unknown>> {
+    /** Primary key value */
+    id: string | number;
+    /** Fields to update */
+    patch: T;
+}
+/**
+ * Input for delete mutations
+ */
+export interface DeleteInput {
+    /** Primary key value */
+    id: string | number;
+}
+/**
+ * Standard mutation result
+ */
+export interface MutationResult<T = unknown> {
+    /** The affected record */
+    data?: T;
+    /** Client mutation ID (PostGraphile) */
+    clientMutationId?: string;
+}

package/types/mutation.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Mutation-related types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/query.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Query-related types for building GraphQL operations
+ */
+import type { FieldSelection } from './selection';
+/**
+ * Relay-style pagination info
+ */
+export interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+}
+/**
+ * Relay-style connection result
+ */
+export interface ConnectionResult<T = unknown> {
+    nodes: T[];
+    totalCount: number;
+    pageInfo: PageInfo;
+}
+/**
+ * Options for building SELECT queries
+ */
+export interface QueryOptions {
+    /** Number of records to fetch (alias for first) */
+    first?: number;
+    /** Alias for first */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Cursor for forward pagination */
+    after?: string;
+    /** Cursor for backward pagination */
+    before?: string;
+    /** Filter conditions */
+    where?: Filter;
+    /** Sort order */
+    orderBy?: OrderByItem[];
+    /** Field selection options */
+    fieldSelection?: FieldSelection;
+    /**
+     * Maps requested relation field names to actual schema field names (or null to omit).
+     * When the mapped name differs from the key, a GraphQL alias is emitted so the
+     * consumer sees a stable field name regardless of the server-side name.
+     *
+     * Example: `{ contact: 'contactByOwnerId' }` emits `contact: contactByOwnerId { … }`
+     * Pass `null` to suppress a relation entirely: `{ internalNotes: null }`
+     */
+    relationFieldMap?: Record<string, string | null>;
+    /** Include pageInfo in response */
+    includePageInfo?: boolean;
+}
+/**
+ * Single order by specification
+ */
+export interface OrderByItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * All supported filter operators
+ */
+export type FilterOperator = 'isNull' | 'equalTo' | 'notEqualTo' | 'distinctFrom' | 'notDistinctFrom' | 'in' | 'notIn' | 'lessThan' | 'lessThanOrEqualTo' | 'greaterThan' | 'greaterThanOrEqualTo' | 'includes' | 'notIncludes' | 'includesInsensitive' | 'notIncludesInsensitive' | 'startsWith' | 'notStartsWith' | 'startsWithInsensitive' | 'notStartsWithInsensitive' | 'endsWith' | 'notEndsWith' | 'endsWithInsensitive' | 'notEndsWithInsensitive' | 'like' | 'notLike' | 'likeInsensitive' | 'notLikeInsensitive' | 'equalToInsensitive' | 'notEqualToInsensitive' | 'distinctFromInsensitive' | 'notDistinctFromInsensitive' | 'inInsensitive' | 'notInInsensitive' | 'contains' | 'containedBy' | 'overlaps' | 'intersects' | 'intersects3D' | 'containsProperly' | 'coveredBy' | 'covers' | 'crosses' | 'disjoint' | 'orderingEquals' | 'touches' | 'within' | 'bboxIntersects2D' | 'bboxIntersects3D' | 'bboxOverlapsOrLeftOf' | 'bboxOverlapsOrRightOf' | 'bboxOverlapsOrBelow' | 'bboxOverlapsOrAbove' | 'bboxLeftOf' | 'bboxRightOf' | 'bboxBelow' | 'bboxAbove' | 'bboxContains' | 'bboxEquals';
+/**
+ * Filter on a single field
+ */
+export type FieldFilter = {
+    [K in FilterOperator]?: unknown;
+};
+/**
+ * Filter on related records
+ */
+export interface RelationalFilter {
+    /** All related records must match */
+    every?: Filter;
+    /** At least one related record must match */
+    some?: Filter;
+    /** No related records match */
+    none?: Filter;
+}
+/**
+ * Main filter type - can be nested
+ */
+export type Filter = {
+    [field: string]: FieldFilter | RelationalFilter | Filter;
+} & {
+    and?: Filter[];
+    or?: Filter[];
+    not?: Filter;
+};

package/types/query.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Query-related types for building GraphQL operations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/schema.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Core schema types for representing PostGraphile table metadata
+ * These are "clean" versions that remove nullable/undefined complexity
+ */
+/**
+ * Represents a database table with its fields and relations
+ */
+export interface CleanTable {
+    name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
+    fields: CleanField[];
+    relations: CleanRelations;
+    /** PostGraphile inflection rules for this table */
+    inflection?: TableInflection;
+    /** Query operation names from introspection */
+    query?: TableQueryNames;
+    /** Constraint information */
+    constraints?: TableConstraints;
+}
+/**
+ * PostGraphile-generated names for this table
+ */
+export interface TableInflection {
+    /** All rows connection query name (e.g., "users") */
+    allRows: string;
+    /** Simple all rows query name */
+    allRowsSimple: string;
+    /** Condition type name (e.g., "UserCondition") */
+    conditionType: string;
+    /** Connection type name (e.g., "UsersConnection") */
+    connection: string;
+    /** Create field name */
+    createField: string;
+    /** Create input type (e.g., "CreateUserInput") */
+    createInputType: string;
+    /** Create payload type */
+    createPayloadType: string;
+    /** Delete by primary key mutation name */
+    deleteByPrimaryKey: string | null;
+    /** Delete payload type */
+    deletePayloadType: string;
+    /** Edge type name */
+    edge: string;
+    /** Edge field name */
+    edgeField: string;
+    /** Enum type name */
+    enumType: string;
+    /** Filter type name (e.g., "UserFilter") */
+    filterType: string | null;
+    /** Input type name (e.g., "UserInput") */
+    inputType: string;
+    /** OrderBy enum type (e.g., "UsersOrderBy") */
+    orderByType: string;
+    /** Patch field name */
+    patchField: string;
+    /** Patch type (e.g., "UserPatch") */
+    patchType: string | null;
+    /** Table field name (singular, e.g., "user") */
+    tableFieldName: string;
+    /** Table type name (e.g., "User") */
+    tableType: string;
+    /** Type name */
+    typeName: string;
+    /** Update by primary key mutation name */
+    updateByPrimaryKey: string | null;
+    /** Update payload type */
+    updatePayloadType: string | null;
+}
+/**
+ * Query operation names from introspection
+ */
+export interface TableQueryNames {
+    /** All rows query name */
+    all: string;
+    /** Single row query name */
+    one: string | null;
+    /** Create mutation name */
+    create: string;
+    /** Update mutation name */
+    update: string | null;
+    /** Delete mutation name */
+    delete: string | null;
+    /** Patch field name in update mutation input (e.g., "userPatch" for UpdateUserInput) */
+    patchFieldName?: string;
+}
+/**
+ * Table constraints
+ */
+export interface TableConstraints {
+    primaryKey: ConstraintInfo[];
+    foreignKey: ForeignKeyConstraint[];
+    unique: ConstraintInfo[];
+}
+export interface ConstraintInfo {
+    name: string;
+    fields: CleanField[];
+}
+export interface ForeignKeyConstraint extends ConstraintInfo {
+    refTable: string;
+    refFields: CleanField[];
+}
+/**
+ * Represents a field/column in a table
+ */
+export interface CleanField {
+    name: string;
+    /** Description from PostgreSQL COMMENT (smart comments stripped) */
+    description?: string;
+    type: CleanFieldType;
+    /** Whether the column has a NOT NULL constraint (inferred from NON_NULL wrapper on entity type field) */
+    isNotNull?: boolean | null;
+    /** Whether the column has a DEFAULT value (inferred by comparing entity vs CreateInput field nullability) */
+    hasDefault?: boolean | null;
+}
+/**
+ * Field type information from PostGraphile introspection
+ */
+export interface CleanFieldType {
+    /** GraphQL type name (e.g., "String", "UUID", "Int") */
+    gqlType: string;
+    /** Whether this is an array type */
+    isArray: boolean;
+    /** Type modifier (for precision, length, etc.) */
+    modifier?: string | number | null;
+    /** PostgreSQL type alias (domain name) */
+    pgAlias?: string | null;
+    /** PostgreSQL native type (e.g., "text", "uuid", "integer") */
+    pgType?: string | null;
+    /** Subtype for composite types */
+    subtype?: string | null;
+    /** Type modifier from PostgreSQL */
+    typmod?: number | null;
+}
+/**
+ * All relation types for a table
+ */
+export interface CleanRelations {
+    belongsTo: CleanBelongsToRelation[];
+    hasOne: CleanHasOneRelation[];
+    hasMany: CleanHasManyRelation[];
+    manyToMany: CleanManyToManyRelation[];
+}
+/**
+ * BelongsTo relation (foreign key on this table)
+ */
+export interface CleanBelongsToRelation {
+    fieldName: string | null;
+    isUnique: boolean;
+    referencesTable: string;
+    type: string | null;
+    keys: CleanField[];
+}
+/**
+ * HasOne relation (foreign key on other table, unique)
+ */
+export interface CleanHasOneRelation {
+    fieldName: string | null;
+    isUnique: boolean;
+    referencedByTable: string;
+    type: string | null;
+    keys: CleanField[];
+}
+/**
+ * HasMany relation (foreign key on other table, not unique)
+ */
+export interface CleanHasManyRelation {
+    fieldName: string | null;
+    isUnique: boolean;
+    referencedByTable: string;
+    type: string | null;
+    keys: CleanField[];
+}
+/**
+ * ManyToMany relation (through junction table)
+ */
+export interface CleanManyToManyRelation {
+    fieldName: string | null;
+    rightTable: string;
+    junctionTable: string;
+    type: string | null;
+}
+/**
+ * Clean representation of a GraphQL operation (query or mutation)
+ * Derived from introspection data
+ */
+export interface CleanOperation {
+    /** Operation name (e.g., "login", "currentUser", "cars") */
+    name: string;
+    /** Operation kind */
+    kind: 'query' | 'mutation';
+    /** Arguments/variables for the operation */
+    args: CleanArgument[];
+    /** Return type */
+    returnType: CleanTypeRef;
+    /** Description from schema */
+    description?: string;
+    /** Whether this is deprecated */
+    isDeprecated?: boolean;
+    /** Deprecation reason */
+    deprecationReason?: string;
+}
+/**
+ * Clean representation of an operation argument
+ */
+export interface CleanArgument {
+    /** Argument name */
+    name: string;
+    /** Argument type */
+    type: CleanTypeRef;
+    /** Default value (as string) */
+    defaultValue?: string;
+    /** Description from schema */
+    description?: string;
+}
+/**
+ * Clean type reference - simplified from introspection TypeRef
+ */
+export interface CleanTypeRef {
+    /** Type kind */
+    kind: 'SCALAR' | 'OBJECT' | 'INPUT_OBJECT' | 'ENUM' | 'LIST' | 'NON_NULL';
+    /** Type name (null for LIST and NON_NULL wrappers) */
+    name: string | null;
+    /** Inner type for LIST and NON_NULL wrappers */
+    ofType?: CleanTypeRef;
+    /** Resolved TypeScript type string */
+    tsType?: string;
+    /** Fields for OBJECT types */
+    fields?: CleanObjectField[];
+    /** Input fields for INPUT_OBJECT types */
+    inputFields?: CleanArgument[];
+    /** Values for ENUM types */
+    enumValues?: string[];
+}
+/**
+ * Field on an object type
+ */
+export interface CleanObjectField {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: CleanTypeRef;
+    /** Description */
+    description?: string;
+}
+/**
+ * Registry of all types in the schema for resolution
+ */
+export type TypeRegistry = Map<string, ResolvedType>;
+/**
+ * Resolved type with all details populated
+ */
+export interface ResolvedType {
+    kind: 'SCALAR' | 'OBJECT' | 'INPUT_OBJECT' | 'ENUM' | 'INTERFACE' | 'UNION';
+    name: string;
+    description?: string;
+    /** Fields for OBJECT types */
+    fields?: CleanObjectField[];
+    /** Input fields for INPUT_OBJECT types */
+    inputFields?: CleanArgument[];
+    /** Values for ENUM types */
+    enumValues?: string[];
+    /** Possible types for UNION types */
+    possibleTypes?: string[];
+}

package/types/schema.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Core schema types for representing PostGraphile table metadata
+ * These are "clean" versions that remove nullable/undefined complexity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/selection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Field selection types for controlling which fields are included in queries
+ */
+/**
+ * Simple field selection options
+ */
+export interface SimpleFieldSelection {
+    /** Specific fields to include */
+    select?: string[];
+    /** Relations to include with their fields */
+    include?: Record<string, string[] | boolean>;
+    /** Simple relation inclusion (just names) */
+    includeRelations?: string[];
+    /** Fields to exclude */
+    exclude?: string[];
+    /** Maximum depth for nested relations */
+    maxDepth?: number;
+}
+/**
+ * Predefined field selection presets
+ */
+export type FieldSelectionPreset = 
+/** Just id and primary display field */
+'minimal'
+/** Common display fields */
+ | 'display'
+/** All scalar fields */
+ | 'all'
+/** All fields including relations */
+ | 'full';
+/**
+ * Main field selection type - preset or custom
+ */
+export type FieldSelection = FieldSelectionPreset | SimpleFieldSelection;
+/**
+ * Internal selection options format used by query builder
+ */
+export interface SelectionOptions {
+    [fieldName: string]: boolean | {
+        select: Record<string, boolean>;
+        variables?: Record<string, unknown>;
+    };
+}

package/types/selection.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Field selection types for controlling which fields are included in queries
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility functions for GraphQL query generation
+ */
+/**
+ * Strip PostGraphile smart comments and boilerplate from a description string.
+ *
+ * Smart comments are lines starting with `@` (e.g., `@omit`, `@name newName`).
+ * Boilerplate descriptions are generic PostGraphile-generated text that repeats
+ * on every mutation input, clientMutationId field, etc.
+ *
+ * This returns only the meaningful human-readable portion of the comment,
+ * or undefined if the result is empty or boilerplate.
+ *
+ * @param description - Raw description from GraphQL introspection
+ * @returns Cleaned description, or undefined if empty/boilerplate
+ */
+export declare function stripSmartComments(description: string | null | undefined, enabled?: boolean): string | undefined;