graphile-connection-filter 1.1.0

package/esm/plugins/ConnectionFilterCustomOperatorsPlugin.d.ts

@@ -0,0 +1,35 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterCustomOperatorsPlugin
+ *
+ * Processes declarative operator factories from the preset configuration.
+ * Satellite plugins (PostGIS filter, search, pg_trgm, etc.) declare their
+ * operators via `connectionFilterOperatorFactories` in their preset's schema
+ * options. This plugin processes all factories during its own init hook,
+ * populating the filter registry used at schema build time.
+ *
+ * This declarative approach replaces the previous imperative
+ * `build.addConnectionFilterOperator()` API, eliminating timing/ordering
+ * dependencies between plugins.
+ *
+ * @example
+ * ```typescript
+ * // In a satellite plugin's preset:
+ * const MyPreset = {
+ *   schema: {
+ *     connectionFilterOperatorFactories: [
+ *       (build) => [{
+ *         typeNames: 'String',
+ *         operatorName: 'myOp',
+ *         spec: {
+ *           description: 'My operator',
+ *           resolve: (i, v) => build.sql`${i} OP ${v}`,
+ *         },
+ *       }],
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export declare const ConnectionFilterCustomOperatorsPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterCustomOperatorsPlugin.js

@@ -0,0 +1,129 @@
+import '../augmentations';
+import { $$filters } from '../types';
+import { makeApplyFromOperatorSpec } from './operatorApply';
+const version = '1.0.0';
+/**
+ * ConnectionFilterCustomOperatorsPlugin
+ *
+ * Processes declarative operator factories from the preset configuration.
+ * Satellite plugins (PostGIS filter, search, pg_trgm, etc.) declare their
+ * operators via `connectionFilterOperatorFactories` in their preset's schema
+ * options. This plugin processes all factories during its own init hook,
+ * populating the filter registry used at schema build time.
+ *
+ * This declarative approach replaces the previous imperative
+ * `build.addConnectionFilterOperator()` API, eliminating timing/ordering
+ * dependencies between plugins.
+ *
+ * @example
+ * ```typescript
+ * // In a satellite plugin's preset:
+ * const MyPreset = {
+ *   schema: {
+ *     connectionFilterOperatorFactories: [
+ *       (build) => [{
+ *         typeNames: 'String',
+ *         operatorName: 'myOp',
+ *         spec: {
+ *           description: 'My operator',
+ *           resolve: (i, v) => build.sql`${i} OP ${v}`,
+ *         },
+ *       }],
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export const ConnectionFilterCustomOperatorsPlugin = {
+    name: 'ConnectionFilterCustomOperatorsPlugin',
+    version,
+    description: 'Processes declarative operator factories for custom filter operator registration',
+    schema: {
+        hooks: {
+            build(build) {
+                // Initialize the filter registry
+                build[$$filters] = new Map();
+                return build;
+            },
+            init(_, build) {
+                const { inflection } = build;
+                const factories = build.options.connectionFilterOperatorFactories;
+                if (!factories || !Array.isArray(factories) || factories.length === 0) {
+                    return _;
+                }
+                // Process each factory: call it with build, register all returned operators
+                for (const factory of factories) {
+                    const registrations = factory(build);
+                    if (!registrations || !Array.isArray(registrations)) {
+                        continue;
+                    }
+                    for (const registration of registrations) {
+                        const { typeNames: typeNameOrNames, operatorName, spec } = registration;
+                        const typeNames = Array.isArray(typeNameOrNames)
+                            ? typeNameOrNames
+                            : [typeNameOrNames];
+                        for (const typeName of typeNames) {
+                            const filterTypeName = inflection.filterFieldType(typeName);
+                            let operatorSpecByFilterName = build[$$filters].get(filterTypeName);
+                            if (!operatorSpecByFilterName) {
+                                operatorSpecByFilterName = new Map();
+                                build[$$filters].set(filterTypeName, operatorSpecByFilterName);
+                            }
+                            if (operatorSpecByFilterName.has(operatorName)) {
+                                throw new Error(`Filter '${operatorName}' already registered on '${filterTypeName}'`);
+                            }
+                            operatorSpecByFilterName.set(operatorName, spec);
+                        }
+                    }
+                }
+                return _;
+            },
+            /**
+             * Applies custom operators to their respective filter types.
+             * When a type like "StringFilter" has custom operators registered,
+             * they are added as fields with apply functions.
+             */
+            GraphQLInputObjectType_fields(inFields, build, context) {
+                let fields = inFields;
+                const { scope: { pgConnectionFilterOperators }, Self, fieldWithHooks, } = context;
+                if (!pgConnectionFilterOperators) {
+                    return fields;
+                }
+                const operatorSpecByFilterName = build[$$filters].get(Self.name);
+                if (!operatorSpecByFilterName) {
+                    return fields;
+                }
+                const { inputTypeName } = pgConnectionFilterOperators;
+                const fieldInputType = build.getTypeByName(inputTypeName);
+                if (!fieldInputType) {
+                    return fields;
+                }
+                for (const [filterName, spec] of operatorSpecByFilterName.entries()) {
+                    const { description, resolveInputCodec, resolveType } = spec;
+                    const firstCodec = pgConnectionFilterOperators.pgCodecs[0];
+                    const inputCodec = resolveInputCodec
+                        ? resolveInputCodec(firstCodec)
+                        : firstCodec;
+                    const codecGraphQLType = build.getGraphQLTypeByPgCodec(inputCodec, 'input');
+                    if (!codecGraphQLType) {
+                        continue;
+                    }
+                    const type = resolveType
+                        ? resolveType(codecGraphQLType)
+                        : codecGraphQLType;
+                    fields = build.extend(fields, {
+                        [filterName]: fieldWithHooks({
+                            fieldName: filterName,
+                            isPgConnectionFilterOperator: true,
+                        }, {
+                            description,
+                            type,
+                            apply: makeApplyFromOperatorSpec(build, Self.name, filterName, spec, type),
+                        }),
+                    }, '');
+                }
+                return fields;
+            },
+        },
+    },
+};

package/esm/plugins/ConnectionFilterForwardRelationsPlugin.d.ts

@@ -0,0 +1,28 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterForwardRelationsPlugin
+ *
+ * Adds forward relation filter fields to table filter types.
+ * A "forward" relation is one where the current table has a FK referencing another table.
+ *
+ * For example, if `orders` has `client_id` referencing `clients`,
+ * then `OrderFilter` gets a `clientByClientId` field of type `ClientFilter`,
+ * allowing queries like:
+ *
+ * ```graphql
+ * allOrders(filter: {
+ *   clientByClientId: { name: { startsWith: "Acme" } }
+ * }) { ... }
+ * ```
+ *
+ * The SQL generated is an EXISTS subquery:
+ * ```sql
+ * WHERE EXISTS (
+ *   SELECT 1 FROM clients
+ *   WHERE clients.id = orders.client_id
+ *   AND <nested filter conditions>
+ * )
+ * ```
+ */
+export declare const ConnectionFilterForwardRelationsPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterForwardRelationsPlugin.js

@@ -0,0 +1,168 @@
+import '../augmentations';
+import { makeAssertAllowed } from '../utils';
+const version = '1.0.0';
+/**
+ * ConnectionFilterForwardRelationsPlugin
+ *
+ * Adds forward relation filter fields to table filter types.
+ * A "forward" relation is one where the current table has a FK referencing another table.
+ *
+ * For example, if `orders` has `client_id` referencing `clients`,
+ * then `OrderFilter` gets a `clientByClientId` field of type `ClientFilter`,
+ * allowing queries like:
+ *
+ * ```graphql
+ * allOrders(filter: {
+ *   clientByClientId: { name: { startsWith: "Acme" } }
+ * }) { ... }
+ * ```
+ *
+ * The SQL generated is an EXISTS subquery:
+ * ```sql
+ * WHERE EXISTS (
+ *   SELECT 1 FROM clients
+ *   WHERE clients.id = orders.client_id
+ *   AND <nested filter conditions>
+ * )
+ * ```
+ */
+export const ConnectionFilterForwardRelationsPlugin = {
+    name: 'ConnectionFilterForwardRelationsPlugin',
+    version,
+    description: 'Adds forward relation filter fields to connection filter types',
+    inflection: {
+        add: {
+            filterForwardRelationExistsFieldName(_preset, relationFieldName) {
+                return `${relationFieldName}Exists`;
+            },
+            filterSingleRelationFieldName(_preset, fieldName) {
+                return fieldName;
+            },
+        },
+    },
+    schema: {
+        entityBehavior: {
+            pgCodecRelation: 'filterBy',
+        },
+        hooks: {
+            GraphQLInputObjectType_fields(inFields, build, context) {
+                let fields = inFields;
+                // Runtime check: only proceed if relation filters are enabled
+                if (!build.options.connectionFilterRelations) {
+                    return fields;
+                }
+                const { extend, inflection, sql, graphql: { GraphQLBoolean }, EXPORTABLE, } = build;
+                const { fieldWithHooks, scope: { pgCodec, isPgConnectionFilter }, } = context;
+                if (!isPgConnectionFilter || !pgCodec || !pgCodec.attributes) {
+                    return fields;
+                }
+                const assertAllowed = makeAssertAllowed(build);
+                const source = Object.values(build.input.pgRegistry.pgResources).find((s) => s.codec === pgCodec && !s.parameters);
+                if (!source)
+                    return fields;
+                const relations = source.getRelations();
+                const forwardRelations = Object.entries(relations).filter(([_relationName, relation]) => !relation.isReferencee);
+                const requireIndex = build.options.connectionFilterRelationsRequireIndex !== false;
+                for (const [relationName, relation] of forwardRelations) {
+                    const foreignTable = relation.remoteResource;
+                    if (!build.behavior.pgCodecRelationMatches(relation, 'filterBy')) {
+                        continue;
+                    }
+                    // Skip function-based sources
+                    if (typeof foreignTable.from === 'function') {
+                        continue;
+                    }
+                    // Skip unindexed relations when requireIndex is enabled.
+                    // PgIndexBehaviorsPlugin sets relation.extensions.isIndexed = false
+                    // on backward relations without supporting indexes. For forward
+                    // relations this is less common (the referenced PK is always indexed)
+                    // but we check it for consistency.
+                    if (requireIndex && relation.extensions?.isIndexed === false) {
+                        continue;
+                    }
+                    const fieldName = inflection.singleRelation({
+                        registry: source.registry,
+                        codec: source.codec,
+                        relationName,
+                    });
+                    const filterFieldName = inflection.filterSingleRelationFieldName(fieldName);
+                    const foreignTableTypeName = inflection.tableType(foreignTable.codec);
+                    const foreignTableFilterTypeName = inflection.filterType(foreignTableTypeName);
+                    const ForeignTableFilterType = build.getTypeByName(foreignTableFilterTypeName);
+                    if (!ForeignTableFilterType)
+                        continue;
+                    const foreignTableExpression = foreignTable.from;
+                    const localAttributes = relation.localAttributes;
+                    const remoteAttributes = relation.remoteAttributes;
+                    // Add the relation filter field (e.g. clientByClientId: ClientFilter)
+                    fields = extend(fields, {
+                        [filterFieldName]: fieldWithHooks({
+                            fieldName: filterFieldName,
+                            isPgConnectionFilterField: true,
+                        }, () => ({
+                            description: `Filter by the object\u2019s \`${fieldName}\` relation.`,
+                            type: ForeignTableFilterType,
+                            apply: EXPORTABLE((assertAllowed, foreignTable, foreignTableExpression, localAttributes, remoteAttributes, sql) => function ($where, value) {
+                                assertAllowed(value, 'object');
+                                if (value == null)
+                                    return;
+                                const $subQuery = $where.existsPlan({
+                                    tableExpression: foreignTableExpression,
+                                    alias: foreignTable.name,
+                                });
+                                localAttributes.forEach((localAttribute, i) => {
+                                    const remoteAttribute = remoteAttributes[i];
+                                    $subQuery.where(sql `${$where.alias}.${sql.identifier(localAttribute)} = ${$subQuery.alias}.${sql.identifier(remoteAttribute)}`);
+                                });
+                                return $subQuery;
+                            }, [
+                                assertAllowed,
+                                foreignTable,
+                                foreignTableExpression,
+                                localAttributes,
+                                remoteAttributes,
+                                sql,
+                            ]),
+                        })),
+                    }, `Adding connection filter forward relation field from ${source.name} to ${foreignTable.name}`);
+                    // Add an "exists" field for nullable FKs (e.g. clientByClientIdExists: Boolean)
+                    const keyIsNullable = relation.localAttributes.some((col) => !source.codec.attributes[col]?.notNull);
+                    if (keyIsNullable) {
+                        const existsFieldName = inflection.filterForwardRelationExistsFieldName(fieldName);
+                        fields = extend(fields, {
+                            [existsFieldName]: fieldWithHooks({
+                                fieldName: existsFieldName,
+                                isPgConnectionFilterField: true,
+                            }, () => ({
+                                description: `A related \`${fieldName}\` exists.`,
+                                type: GraphQLBoolean,
+                                apply: EXPORTABLE((assertAllowed, foreignTable, foreignTableExpression, localAttributes, remoteAttributes, sql) => function ($where, value) {
+                                    assertAllowed(value, 'scalar');
+                                    if (value == null)
+                                        return;
+                                    const $subQuery = $where.existsPlan({
+                                        tableExpression: foreignTableExpression,
+                                        alias: foreignTable.name,
+                                        equals: value,
+                                    });
+                                    localAttributes.forEach((localAttribute, i) => {
+                                        const remoteAttribute = remoteAttributes[i];
+                                        $subQuery.where(sql `${$where.alias}.${sql.identifier(localAttribute)} = ${$subQuery.alias}.${sql.identifier(remoteAttribute)}`);
+                                    });
+                                }, [
+                                    assertAllowed,
+                                    foreignTable,
+                                    foreignTableExpression,
+                                    localAttributes,
+                                    remoteAttributes,
+                                    sql,
+                                ]),
+                            })),
+                        }, `Adding connection filter forward relation exists field for ${fieldName}`);
+                    }
+                }
+                return fields;
+            },
+        },
+    },
+};

package/esm/plugins/ConnectionFilterInflectionPlugin.d.ts

@@ -0,0 +1,11 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterInflectionPlugin
+ *
+ * Adds inflection methods for naming filter types:
+ * - filterType(typeName) -> e.g. "UserFilter"
+ * - filterFieldType(typeName) -> e.g. "StringFilter"
+ * - filterFieldListType(typeName) -> e.g. "StringListFilter"
+ */
+export declare const ConnectionFilterInflectionPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterInflectionPlugin.js

@@ -0,0 +1,27 @@
+import '../augmentations';
+/**
+ * ConnectionFilterInflectionPlugin
+ *
+ * Adds inflection methods for naming filter types:
+ * - filterType(typeName) -> e.g. "UserFilter"
+ * - filterFieldType(typeName) -> e.g. "StringFilter"
+ * - filterFieldListType(typeName) -> e.g. "StringListFilter"
+ */
+export const ConnectionFilterInflectionPlugin = {
+    name: 'ConnectionFilterInflectionPlugin',
+    version: '1.0.0',
+    description: 'Adds inflection methods for connection filter type naming',
+    inflection: {
+        add: {
+            filterType(_preset, typeName) {
+                return `${typeName}Filter`;
+            },
+            filterFieldType(_preset, typeName) {
+                return `${typeName}Filter`;
+            },
+            filterFieldListType(_preset, typeName) {
+                return `${typeName}ListFilter`;
+            },
+        },
+    },
+};

package/esm/plugins/ConnectionFilterLogicalOperatorsPlugin.d.ts

@@ -0,0 +1,15 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterLogicalOperatorsPlugin
+ *
+ * Adds the `and`, `or`, and `not` logical operators to filter types.
+ *
+ * - `and`: [Filter!] - all conditions must match (uses $where.andPlan())
+ * - `or`: [Filter!] - any condition must match (uses $where.orPlan())
+ * - `not`: Filter - negates the condition (uses $where.notPlan())
+ *
+ * These are only added if the filter type has at least one other field
+ * (to avoid creating useless logical-only filter types).
+ */
+export declare const ConnectionFilterLogicalOperatorsPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterLogicalOperatorsPlugin.js

@@ -0,0 +1,86 @@
+import '../augmentations';
+import { makeAssertAllowed } from '../utils';
+const version = '1.0.0';
+/**
+ * ConnectionFilterLogicalOperatorsPlugin
+ *
+ * Adds the `and`, `or`, and `not` logical operators to filter types.
+ *
+ * - `and`: [Filter!] - all conditions must match (uses $where.andPlan())
+ * - `or`: [Filter!] - any condition must match (uses $where.orPlan())
+ * - `not`: Filter - negates the condition (uses $where.notPlan())
+ *
+ * These are only added if the filter type has at least one other field
+ * (to avoid creating useless logical-only filter types).
+ */
+export const ConnectionFilterLogicalOperatorsPlugin = {
+    name: 'ConnectionFilterLogicalOperatorsPlugin',
+    version,
+    description: 'Adds and/or/not logical operators to connection filter types',
+    schema: {
+        hooks: {
+            GraphQLInputObjectType_fields(fields, build, context) {
+                const { extend, graphql: { GraphQLList, GraphQLNonNull }, EXPORTABLE, } = build;
+                const { fieldWithHooks, scope: { isPgConnectionFilter }, Self, } = context;
+                if (!isPgConnectionFilter)
+                    return fields;
+                // Check runtime option — allows toggling without removing the plugin
+                if (build.options.connectionFilterLogicalOperators === false) {
+                    return fields;
+                }
+                // Don't add logical operators if there are no other fields
+                if (Object.keys(fields).length === 0) {
+                    return fields;
+                }
+                const assertAllowed = makeAssertAllowed(build);
+                const logicalOperatorFields = {
+                    and: fieldWithHooks({
+                        fieldName: 'and',
+                        isPgConnectionFilterOperatorLogical: true,
+                    }, {
+                        description: 'Checks for all expressions in this list.',
+                        type: new GraphQLList(new GraphQLNonNull(Self)),
+                        apply: EXPORTABLE((assertAllowed) => function ($where, value) {
+                            assertAllowed(value, 'list');
+                            if (value == null)
+                                return;
+                            const $and = $where.andPlan();
+                            return $and;
+                        }, [assertAllowed]),
+                    }),
+                    or: fieldWithHooks({
+                        fieldName: 'or',
+                        isPgConnectionFilterOperatorLogical: true,
+                    }, {
+                        description: 'Checks for any expressions in this list.',
+                        type: new GraphQLList(new GraphQLNonNull(Self)),
+                        apply: EXPORTABLE((assertAllowed) => function ($where, value) {
+                            assertAllowed(value, 'list');
+                            if (value == null)
+                                return;
+                            const $or = $where.orPlan();
+                            // Each entry in the OR list should use AND internally
+                            return () => $or.andPlan();
+                        }, [assertAllowed]),
+                    }),
+                    not: fieldWithHooks({
+                        fieldName: 'not',
+                        isPgConnectionFilterOperatorLogical: true,
+                    }, {
+                        description: 'Negates the expression.',
+                        type: Self,
+                        apply: EXPORTABLE((assertAllowed) => function ($where, value) {
+                            assertAllowed(value, 'object');
+                            if (value == null)
+                                return;
+                            const $not = $where.notPlan();
+                            const $and = $not.andPlan();
+                            return $and;
+                        }, [assertAllowed]),
+                    }),
+                };
+                return extend(fields, logicalOperatorFields, '');
+            },
+        },
+    },
+};

package/esm/plugins/ConnectionFilterOperatorsPlugin.d.ts

@@ -0,0 +1,21 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterOperatorsPlugin
+ *
+ * Registers all built-in filter operators on the per-scalar operator types
+ * (e.g. StringFilter, IntFilter, DatetimeFilter, etc.).
+ *
+ * Operator categories:
+ * - Standard: isNull, equalTo, notEqualTo, distinctFrom, notDistinctFrom, in, notIn
+ * - Sort: lessThan, lessThanOrEqualTo, greaterThan, greaterThanOrEqualTo
+ * - Pattern matching (text-like): includes, startsWith, endsWith, like + insensitive variants
+ * - Hstore: contains, containsKey, containsAllKeys, containsAnyKeys, containedBy
+ * - JSONB: contains, containsKey, containsAllKeys, containsAnyKeys, containedBy
+ * - Inet: contains, containsOrEqualTo, containedBy, containedByOrEqualTo, containsOrContainedBy
+ * - Array: contains, containedBy, overlaps, anyEqualTo, anyNotEqualTo, any comparison operators
+ * - Range: contains, containsElement, containedBy, overlaps, strictlyLeftOf, strictlyRightOf, etc.
+ * - Enum: standard + sort operators
+ * - Case-insensitive variants of standard and sort operators
+ */
+export declare const ConnectionFilterOperatorsPlugin: GraphileConfig.Plugin;