graphile-connection-filter 1.1.0

package/esm/plugins/ConnectionFilterTypesPlugin.d.ts

@@ -0,0 +1,12 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterTypesPlugin
+ *
+ * Registers the filter types in the schema:
+ * 1. Per-table filter types (e.g. UserFilter) - registered for every codec with attributes
+ * 2. Per-scalar operator types (e.g. StringFilter, IntFilter) - registered for each scalar type
+ *
+ * Also adds `connectionFilterOperatorsDigest` and `escapeLikeWildcards` to the build object.
+ */
+export declare const ConnectionFilterTypesPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterTypesPlugin.js

@@ -0,0 +1,225 @@
+import '../augmentations';
+const version = '1.0.0';
+/**
+ * Determines if a codec is suitable for scalar/enum/domain/array filtering.
+ * Excludes void, composite types, anonymous types, and polymorphic types.
+ */
+function isSuitableForFiltering(build, codec) {
+    return (codec !== build.dataplanPg.TYPES.void &&
+        !codec.attributes &&
+        !codec.isAnonymous &&
+        !codec.polymorphism &&
+        (!codec.arrayOfCodec || isSuitableForFiltering(build, codec.arrayOfCodec)) &&
+        (!codec.domainOfCodec || isSuitableForFiltering(build, codec.domainOfCodec)));
+}
+/**
+ * ConnectionFilterTypesPlugin
+ *
+ * Registers the filter types in the schema:
+ * 1. Per-table filter types (e.g. UserFilter) - registered for every codec with attributes
+ * 2. Per-scalar operator types (e.g. StringFilter, IntFilter) - registered for each scalar type
+ *
+ * Also adds `connectionFilterOperatorsDigest` and `escapeLikeWildcards` to the build object.
+ */
+export const ConnectionFilterTypesPlugin = {
+    name: 'ConnectionFilterTypesPlugin',
+    version,
+    description: 'Registers connection filter input types for tables and scalars',
+    schema: {
+        behaviorRegistry: {
+            add: {
+                filterProc: {
+                    description: 'Can this function be filtered?',
+                    entities: ['pgResource'],
+                },
+                filter: {
+                    description: 'Can this table be filtered?',
+                    entities: ['pgResource'],
+                },
+            },
+        },
+        entityBehavior: {
+            pgCodec: 'filter',
+            pgResource: {
+                inferred(behavior, entity, build) {
+                    if (entity.parameters) {
+                        return [
+                            behavior,
+                            build.options.connectionFilterSetofFunctions
+                                ? 'filterProc'
+                                : '-filterProc',
+                        ];
+                    }
+                    else {
+                        return ['filter', behavior];
+                    }
+                },
+            },
+        },
+        hooks: {
+            build(build) {
+                const { inflection, options: { connectionFilterAllowedFieldTypes, connectionFilterArrays, }, EXPORTABLE, } = build;
+                // Add connectionFilterOperatorsDigest to the build object
+                build.connectionFilterOperatorsDigest = (codec) => {
+                    const finalBuild = build;
+                    const { dataplanPg: { getInnerCodec, TYPES, isEnumCodec }, } = finalBuild;
+                    if (!isSuitableForFiltering(finalBuild, codec)) {
+                        return null;
+                    }
+                    // Unwrap to the simple type
+                    const pgSimpleCodec = getInnerCodec(codec);
+                    if (!pgSimpleCodec)
+                        return null;
+                    if (pgSimpleCodec.polymorphism ||
+                        pgSimpleCodec.attributes ||
+                        pgSimpleCodec.isAnonymous) {
+                        return null;
+                    }
+                    // json type has no valid operators (use jsonb instead)
+                    if (pgSimpleCodec === TYPES.json) {
+                        return null;
+                    }
+                    const itemCodec = codec.arrayOfCodec ?? codec;
+                    const fieldTypeName = build.getGraphQLTypeNameByPgCodec(itemCodec, 'output');
+                    if (!fieldTypeName)
+                        return null;
+                    const fieldTypeMeta = build.getTypeMetaByName(fieldTypeName);
+                    if (!fieldTypeMeta)
+                        return null;
+                    const fieldInputTypeName = build.getGraphQLTypeNameByPgCodec(itemCodec, 'input');
+                    if (!fieldInputTypeName)
+                        return null;
+                    const fieldInputTypeMeta = build.getTypeMetaByName(fieldInputTypeName);
+                    if (!fieldInputTypeMeta)
+                        return null;
+                    // Skip unrecognized types that PostGraphile maps to String
+                    const namedTypeName = fieldTypeName;
+                    const namedInputTypeName = fieldInputTypeName;
+                    const actualStringCodecs = [
+                        TYPES.bpchar,
+                        TYPES.char,
+                        TYPES.name,
+                        TYPES.text,
+                        TYPES.varchar,
+                        TYPES.citext,
+                    ];
+                    if (namedInputTypeName === 'String' &&
+                        !actualStringCodecs.includes(pgSimpleCodec)) {
+                        return null;
+                    }
+                    // Respect connectionFilterAllowedFieldTypes
+                    if (connectionFilterAllowedFieldTypes &&
+                        !connectionFilterAllowedFieldTypes.includes(namedTypeName)) {
+                        return null;
+                    }
+                    // Respect connectionFilterArrays
+                    const isArray = !!codec.arrayOfCodec;
+                    if (isArray && !connectionFilterArrays) {
+                        return null;
+                    }
+                    const listType = !!(codec.arrayOfCodec ||
+                        codec.domainOfCodec?.arrayOfCodec ||
+                        codec.rangeOfCodec?.arrayOfCodec);
+                    const operatorsTypeName = listType
+                        ? inflection.filterFieldListType(namedTypeName)
+                        : inflection.filterFieldType(namedTypeName);
+                    const rangeElementInputTypeName = codec.rangeOfCodec && !codec.rangeOfCodec.arrayOfCodec
+                        ? build.getGraphQLTypeNameByPgCodec(codec.rangeOfCodec, 'input')
+                        : null;
+                    const domainBaseTypeName = codec.domainOfCodec && !codec.domainOfCodec.arrayOfCodec
+                        ? build.getGraphQLTypeNameByPgCodec(codec.domainOfCodec, 'output')
+                        : null;
+                    return {
+                        isList: listType,
+                        operatorsTypeName,
+                        relatedTypeName: namedTypeName,
+                        inputTypeName: fieldInputTypeName,
+                        rangeElementInputTypeName,
+                        domainBaseTypeName,
+                    };
+                };
+                // Add escapeLikeWildcards helper
+                build.escapeLikeWildcards = EXPORTABLE(() => function (input) {
+                    if ('string' !== typeof input) {
+                        throw new Error('Non-string input was provided to escapeLikeWildcards');
+                    }
+                    return input.split('%').join('\\%').split('_').join('\\_');
+                }, []);
+                return build;
+            },
+            init: {
+                after: ['PgCodecs'],
+                callback(_, build) {
+                    const { inflection } = build;
+                    // Register per-table filter types (e.g. UserFilter)
+                    for (const pgCodec of build.allPgCodecs) {
+                        if (!pgCodec.attributes) {
+                            continue;
+                        }
+                        const nodeTypeName = build.getGraphQLTypeNameByPgCodec(pgCodec, 'output');
+                        if (!nodeTypeName) {
+                            continue;
+                        }
+                        const filterTypeName = inflection.filterType(nodeTypeName);
+                        build.registerInputObjectType(filterTypeName, {
+                            pgCodec,
+                            isPgConnectionFilter: true,
+                        }, () => ({
+                            description: `A filter to be used against \`${nodeTypeName}\` object types. All fields are combined with a logical \u2018and.\u2019`,
+                        }), 'ConnectionFilterTypesPlugin');
+                    }
+                    // Register per-scalar operator types (e.g. StringFilter, IntFilter)
+                    const codecsByFilterTypeName = {};
+                    for (const codec of build.allPgCodecs) {
+                        const digest = build.connectionFilterOperatorsDigest(codec);
+                        if (!digest)
+                            continue;
+                        const { isList, operatorsTypeName, relatedTypeName, inputTypeName, rangeElementInputTypeName, domainBaseTypeName, } = digest;
+                        if (!codecsByFilterTypeName[operatorsTypeName]) {
+                            codecsByFilterTypeName[operatorsTypeName] = {
+                                isList,
+                                relatedTypeName,
+                                pgCodecs: [codec],
+                                inputTypeName,
+                                rangeElementInputTypeName,
+                                domainBaseTypeName,
+                            };
+                        }
+                        else {
+                            // Validate consistency
+                            for (const key of [
+                                'isList',
+                                'relatedTypeName',
+                                'inputTypeName',
+                                'rangeElementInputTypeName',
+                            ]) {
+                                if (digest[key] !==
+                                    codecsByFilterTypeName[operatorsTypeName][key]) {
+                                    throw new Error(`${key} mismatch: existing codecs (${codecsByFilterTypeName[operatorsTypeName].pgCodecs
+                                        .map((c) => c.name)
+                                        .join(', ')}) had ${key} = ${codecsByFilterTypeName[operatorsTypeName][key]}, but ${codec.name} instead has ${key} = ${digest[key]}`);
+                                }
+                            }
+                            codecsByFilterTypeName[operatorsTypeName].pgCodecs.push(codec);
+                        }
+                    }
+                    for (const [operatorsTypeName, { isList, relatedTypeName, pgCodecs, inputTypeName, rangeElementInputTypeName, domainBaseTypeName, },] of Object.entries(codecsByFilterTypeName)) {
+                        build.registerInputObjectType(operatorsTypeName, {
+                            pgConnectionFilterOperators: {
+                                isList,
+                                pgCodecs,
+                                inputTypeName,
+                                rangeElementInputTypeName,
+                                domainBaseTypeName,
+                            },
+                        }, () => ({
+                            name: operatorsTypeName,
+                            description: `A filter to be used against ${relatedTypeName}${isList ? ' List' : ''} fields. All fields are combined with a logical \u2018and.\u2019`,
+                        }), 'ConnectionFilterTypesPlugin');
+                    }
+                    return _;
+                },
+            },
+        },
+    },
+};

package/esm/plugins/index.d.ts

@@ -0,0 +1,11 @@
+export { ConnectionFilterInflectionPlugin } from './ConnectionFilterInflectionPlugin';
+export { ConnectionFilterTypesPlugin } from './ConnectionFilterTypesPlugin';
+export { ConnectionFilterArgPlugin } from './ConnectionFilterArgPlugin';
+export { ConnectionFilterAttributesPlugin } from './ConnectionFilterAttributesPlugin';
+export { ConnectionFilterOperatorsPlugin } from './ConnectionFilterOperatorsPlugin';
+export { ConnectionFilterCustomOperatorsPlugin } from './ConnectionFilterCustomOperatorsPlugin';
+export { ConnectionFilterLogicalOperatorsPlugin } from './ConnectionFilterLogicalOperatorsPlugin';
+export { ConnectionFilterComputedAttributesPlugin } from './ConnectionFilterComputedAttributesPlugin';
+export { ConnectionFilterForwardRelationsPlugin } from './ConnectionFilterForwardRelationsPlugin';
+export { ConnectionFilterBackwardRelationsPlugin } from './ConnectionFilterBackwardRelationsPlugin';
+export { makeApplyFromOperatorSpec } from './operatorApply';

package/esm/plugins/index.js

@@ -0,0 +1,11 @@
+export { ConnectionFilterInflectionPlugin } from './ConnectionFilterInflectionPlugin';
+export { ConnectionFilterTypesPlugin } from './ConnectionFilterTypesPlugin';
+export { ConnectionFilterArgPlugin } from './ConnectionFilterArgPlugin';
+export { ConnectionFilterAttributesPlugin } from './ConnectionFilterAttributesPlugin';
+export { ConnectionFilterOperatorsPlugin } from './ConnectionFilterOperatorsPlugin';
+export { ConnectionFilterCustomOperatorsPlugin } from './ConnectionFilterCustomOperatorsPlugin';
+export { ConnectionFilterLogicalOperatorsPlugin } from './ConnectionFilterLogicalOperatorsPlugin';
+export { ConnectionFilterComputedAttributesPlugin } from './ConnectionFilterComputedAttributesPlugin';
+export { ConnectionFilterForwardRelationsPlugin } from './ConnectionFilterForwardRelationsPlugin';
+export { ConnectionFilterBackwardRelationsPlugin } from './ConnectionFilterBackwardRelationsPlugin';
+export { makeApplyFromOperatorSpec } from './operatorApply';

package/esm/plugins/operatorApply.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates an `apply` function for a filter operator field.
+ *
+ * This is the core execution logic: given a PgCondition ($where) and an input value,
+ * it resolves the SQL identifier, SQL value, and calls the operator's resolve function
+ * to produce a SQL WHERE clause fragment, then applies it via `$where.where(fragment)`.
+ *
+ * The `pgFilterAttribute` extension on $where provides the context about which
+ * column is being filtered, including the attribute name, codec, and any expression.
+ */
+export declare function makeApplyFromOperatorSpec(build: any, _typeName: string, fieldName: string, spec: any, _type: any): any;

package/esm/plugins/operatorApply.js

@@ -0,0 +1,70 @@
+/**
+ * Creates an `apply` function for a filter operator field.
+ *
+ * This is the core execution logic: given a PgCondition ($where) and an input value,
+ * it resolves the SQL identifier, SQL value, and calls the operator's resolve function
+ * to produce a SQL WHERE clause fragment, then applies it via `$where.where(fragment)`.
+ *
+ * The `pgFilterAttribute` extension on $where provides the context about which
+ * column is being filtered, including the attribute name, codec, and any expression.
+ */
+export function makeApplyFromOperatorSpec(build, _typeName, fieldName, spec, _type) {
+    const { sql, dataplanPg: { TYPES, sqlValueWithCodec }, EXPORTABLE, } = build;
+    const { resolve, resolveInput, resolveSqlIdentifier, resolveSqlValue, resolveInputCodec, } = spec;
+    const { options: { connectionFilterAllowNullInput } } = build;
+    return EXPORTABLE((connectionFilterAllowNullInput, fieldName, resolve, resolveInput, resolveInputCodec, resolveSqlIdentifier, resolveSqlValue, sql, sqlValueWithCodec) => function ($where, value) {
+        if (!$where.extensions?.pgFilterAttribute) {
+            throw new Error("Planning error: expected 'pgFilterAttribute' to be present on the $where plan's extensions; your extensions to the connection filter plugin do not implement the required interfaces.");
+        }
+        if (value === undefined) {
+            return;
+        }
+        const { fieldName: parentFieldName, attributeName, attribute, codec, expression, } = $where.extensions.pgFilterAttribute;
+        // Determine the SQL expression for the column
+        const sourceAlias = attribute
+            ? attribute.expression
+                ? attribute.expression($where.alias)
+                : sql `${$where.alias}.${sql.identifier(attributeName)}`
+            : expression
+                ? expression
+                : $where.alias;
+        const sourceCodec = codec ?? attribute.codec;
+        // Optionally override the SQL identifier (e.g. cast citext to text)
+        const [sqlIdentifier, identifierCodec] = resolveSqlIdentifier
+            ? resolveSqlIdentifier(sourceAlias, sourceCodec)
+            : [sourceAlias, sourceCodec];
+        // Handle null input
+        if (connectionFilterAllowNullInput && value === null) {
+            return;
+        }
+        if (!connectionFilterAllowNullInput && value === null) {
+            throw Object.assign(new Error('Null literals are forbidden in filter argument input.'), {});
+        }
+        // Optionally transform the input value
+        const resolvedInput = resolveInput ? resolveInput(value) : value;
+        // Determine the input codec
+        const inputCodec = resolveInputCodec
+            ? resolveInputCodec(codec ?? attribute.codec)
+            : codec ?? attribute.codec;
+        // Generate the SQL value
+        const sqlValue = resolveSqlValue
+            ? resolveSqlValue($where, value, inputCodec)
+            : sqlValueWithCodec(resolvedInput, inputCodec);
+        // Generate the WHERE clause fragment and apply it
+        const fragment = resolve(sqlIdentifier, sqlValue, value, $where, {
+            fieldName: parentFieldName ?? null,
+            operatorName: fieldName,
+        });
+        $where.where(fragment);
+    }, [
+        connectionFilterAllowNullInput,
+        fieldName,
+        resolve,
+        resolveInput,
+        resolveInputCodec,
+        resolveSqlIdentifier,
+        resolveSqlValue,
+        sql,
+        sqlValueWithCodec,
+    ]);
+}

package/esm/preset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Connection Filter Preset
+ *
+ * Provides a convenient preset factory for including connection filtering
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectionFilterPreset } from 'graphile-connection-filter';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConnectionFilterPreset(),
+ *     // or with options:
+ *     ConnectionFilterPreset({
+ *       connectionFilterLogicalOperators: true,
+ *       connectionFilterArrays: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import './augmentations';
+import type { GraphileConfig } from 'graphile-config';
+import type { ConnectionFilterOptions } from './types';
+/**
+ * Creates a preset that includes the connection filter plugins with the given options.
+ *
+ * All plugins are always included. Use the schema options to control behavior:
+ * - `connectionFilterLogicalOperators: false` to exclude and/or/not
+ * - `connectionFilterArrays: false` to exclude array type filters
+ * - `connectionFilterAllowNullInput: true` to allow null literals
+ */
+export declare function ConnectionFilterPreset(options?: ConnectionFilterOptions): GraphileConfig.Preset;
+export default ConnectionFilterPreset;

package/esm/preset.js

@@ -0,0 +1,72 @@
+/**
+ * Connection Filter Preset
+ *
+ * Provides a convenient preset factory for including connection filtering
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectionFilterPreset } from 'graphile-connection-filter';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConnectionFilterPreset(),
+ *     // or with options:
+ *     ConnectionFilterPreset({
+ *       connectionFilterLogicalOperators: true,
+ *       connectionFilterArrays: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import './augmentations';
+import { ConnectionFilterInflectionPlugin, ConnectionFilterTypesPlugin, ConnectionFilterArgPlugin, ConnectionFilterAttributesPlugin, ConnectionFilterOperatorsPlugin, ConnectionFilterCustomOperatorsPlugin, ConnectionFilterLogicalOperatorsPlugin, ConnectionFilterComputedAttributesPlugin, ConnectionFilterForwardRelationsPlugin, ConnectionFilterBackwardRelationsPlugin, } from './plugins';
+/**
+ * Default schema options for the connection filter.
+ */
+const defaultSchemaOptions = {
+    connectionFilterArgumentName: 'where',
+    connectionFilterArrays: true,
+    connectionFilterLogicalOperators: true,
+    connectionFilterAllowNullInput: false,
+    connectionFilterSetofFunctions: true,
+    connectionFilterComputedColumns: true,
+    connectionFilterRelations: false,
+    connectionFilterRelationsRequireIndex: true,
+};
+/**
+ * Creates a preset that includes the connection filter plugins with the given options.
+ *
+ * All plugins are always included. Use the schema options to control behavior:
+ * - `connectionFilterLogicalOperators: false` to exclude and/or/not
+ * - `connectionFilterArrays: false` to exclude array type filters
+ * - `connectionFilterAllowNullInput: true` to allow null literals
+ */
+export function ConnectionFilterPreset(options = {}) {
+    const mergedOptions = { ...defaultSchemaOptions, ...options };
+    const plugins = [
+        ConnectionFilterInflectionPlugin,
+        ConnectionFilterTypesPlugin,
+        ConnectionFilterArgPlugin,
+        ConnectionFilterAttributesPlugin,
+        ConnectionFilterOperatorsPlugin,
+        ConnectionFilterCustomOperatorsPlugin,
+    ];
+    // Logical operators plugin always included — checks
+    // build.options.connectionFilterLogicalOperators at runtime
+    plugins.push(ConnectionFilterLogicalOperatorsPlugin);
+    // Computed columns are opt-in (disabled by default)
+    if (mergedOptions.connectionFilterComputedColumns) {
+        plugins.push(ConnectionFilterComputedAttributesPlugin);
+    }
+    // Relation filter plugins are always included but check
+    // build.options.connectionFilterRelations at runtime
+    plugins.push(ConnectionFilterForwardRelationsPlugin);
+    plugins.push(ConnectionFilterBackwardRelationsPlugin);
+    return {
+        plugins,
+        schema: mergedOptions,
+    };
+}
+export default ConnectionFilterPreset;

package/esm/types.d.ts

@@ -0,0 +1,146 @@
+import type { SQL } from 'pg-sql2';
+import type { GraphQLInputType } from 'graphql';
+/**
+ * Symbol used to store the filter operator registry on the build object.
+ */
+export declare const $$filters: unique symbol;
+/**
+ * Specification for a filter operator.
+ *
+ * This is the contract that satellite plugins (PostGIS, search, pgvector, etc.)
+ * use when calling `addConnectionFilterOperator`.
+ */
+export interface ConnectionFilterOperatorSpec {
+    /** Human-readable description for the GraphQL schema. */
+    description?: string;
+    /**
+     * Core resolve function: given the SQL identifier for the column and the SQL
+     * value for the user input, return a SQL fragment for the WHERE clause.
+     */
+    resolve: (sqlIdentifier: SQL, sqlValue: SQL, input: unknown, $where: any, details: {
+        fieldName: string | null;
+        operatorName: string;
+    }) => SQL;
+    /**
+     * Optional: transform the user input before encoding to SQL.
+     * e.g. wrapping a LIKE pattern with `%`.
+     */
+    resolveInput?: (input: unknown) => unknown;
+    /**
+     * Optional: override the codec used for encoding the input value to SQL.
+     * Receives the column's codec and returns the codec to use for the input.
+     */
+    resolveInputCodec?: (codec: any) => any;
+    /**
+     * Optional: override the SQL identifier and its codec.
+     * Useful for casting columns (e.g. citext -> text for case-sensitive matching).
+     */
+    resolveSqlIdentifier?: (sqlIdentifier: SQL, codec: any) => [SQL, any];
+    /**
+     * Optional: completely override how the SQL value is generated.
+     * Receives the $where plan, the raw input value, and the resolved input codec.
+     */
+    resolveSqlValue?: ($where: any, value: unknown, inputCodec: any) => SQL;
+    /**
+     * Optional: override the GraphQL input type for this operator.
+     * Receives the default field input type and returns the type to use.
+     */
+    resolveType?: (fieldType: GraphQLInputType) => GraphQLInputType;
+}
+/**
+ * A single operator registration returned by a factory function.
+ * Declares which type(s) the operator applies to, its name, and its spec.
+ */
+export interface ConnectionFilterOperatorRegistration {
+    /** The GraphQL type name(s) this operator applies to (e.g. 'String', 'Int', or an array). */
+    typeNames: string | string[];
+    /** The operator field name (e.g. 'similarTo', 'matches', 'intersects'). */
+    operatorName: string;
+    /** The operator specification (resolve function, description, etc.). */
+    spec: ConnectionFilterOperatorSpec;
+}
+/**
+ * A factory function that receives the build object and returns operator registrations.
+ * This is the declarative replacement for `build.addConnectionFilterOperator()`.
+ *
+ * Satellite plugins declare these in their preset's `connectionFilterOperatorFactories`
+ * option. The connection filter plugin processes them during its own init hook,
+ * eliminating timing dependencies between plugins.
+ *
+ * @example
+ * ```typescript
+ * const myFactory: ConnectionFilterOperatorFactory = (build) => [
+ *   {
+ *     typeNames: 'String',
+ *     operatorName: 'similarTo',
+ *     spec: {
+ *       description: 'Fuzzy match',
+ *       resolve: (i, v) => build.sql`similarity(${i}, ${v}) > 0.3`,
+ *     },
+ *   },
+ * ];
+ * ```
+ */
+export type ConnectionFilterOperatorFactory = (build: any) => ConnectionFilterOperatorRegistration[];
+/**
+ * Configuration options for the connection filter preset.
+ */
+export interface ConnectionFilterOptions {
+    /** The GraphQL argument name for the filter. Default: 'where' */
+    connectionFilterArgumentName?: string;
+    /** Allow filtering on array columns. Default: true */
+    connectionFilterArrays?: boolean;
+    /** Include logical operators (and/or/not). Default: true */
+    connectionFilterLogicalOperators?: boolean;
+    /** Allow null literals in filter input. Default: false */
+    connectionFilterAllowNullInput?: boolean;
+    /** Restrict which field types can be filtered. Default: all types */
+    connectionFilterAllowedFieldTypes?: string[];
+    /** Restrict which operators are available. Default: all operators */
+    connectionFilterAllowedOperators?: string[];
+    /** Rename operators. Keys are default names, values are custom names. */
+    connectionFilterOperatorNames?: Record<string, string>;
+    /** Allow filtering on setof functions. Default: true */
+    connectionFilterSetofFunctions?: boolean;
+    /** Allow filtering on computed columns. Default: true */
+    connectionFilterComputedColumns?: boolean;
+    /** Allow filtering on related tables via FK relationships. Default: false */
+    connectionFilterRelations?: boolean;
+    /** Only create relation filter fields for FKs with supporting indexes.
+     * Prevents EXISTS subqueries that would cause sequential scans on large tables.
+     * Default: true */
+    connectionFilterRelationsRequireIndex?: boolean;
+    /**
+     * Declarative operator factories. Each factory receives the build object and
+     * returns an array of operator registrations. This replaces the imperative
+     * `build.addConnectionFilterOperator()` API.
+     *
+     * Satellite plugins (PostGIS, search, pg_trgm, etc.) declare their operators
+     * here instead of calling `addConnectionFilterOperator` in an init hook.
+     * The connection filter plugin processes all factories during its own init,
+     * eliminating timing/ordering dependencies.
+     */
+    connectionFilterOperatorFactories?: ConnectionFilterOperatorFactory[];
+}
+/**
+ * Digest of operator type information for a given codec.
+ * Used to determine which filter type (e.g. StringFilter, IntFilter) to create.
+ */
+export interface ConnectionFilterOperatorsDigest {
+    isList: boolean;
+    operatorsTypeName: string;
+    relatedTypeName: string;
+    inputTypeName: string;
+    rangeElementInputTypeName: string | null;
+    domainBaseTypeName: string | null;
+}
+/**
+ * Scope metadata stored on operator filter types (e.g. StringFilter, IntFilter).
+ */
+export interface PgConnectionFilterOperatorsScope {
+    isList: boolean;
+    pgCodecs: any[];
+    inputTypeName: string;
+    rangeElementInputTypeName: string | null;
+    domainBaseTypeName: string | null;
+}

package/esm/types.js

@@ -0,0 +1,4 @@
+/**
+ * Symbol used to store the filter operator registry on the build object.
+ */
+export const $$filters = Symbol('connectionFilters');

package/esm/utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Utility functions for the connection filter plugin.
+ */
+/**
+ * Check if a value is an empty object (no own enumerable keys).
+ */
+export declare function isEmpty(o: unknown): boolean;
+/**
+ * Check if a pgResource is a computed scalar attribute function.
+ * A computed attribute is a function that:
+ * - has parameters
+ * - returns a scalar (no attributes on codec)
+ * - is unique (returns single row)
+ * - first parameter's codec has attributes (i.e. takes a table row)
+ */
+export declare function isComputedScalarAttributeResource(s: any): boolean;
+/**
+ * Get all computed attribute resources for a given source.
+ */
+export declare function getComputedAttributeResources(build: any, source: any): any[];
+/**
+ * Walks from a PgCondition up to the PgSelectQueryBuilder.
+ * Uses the .parent property on PgCondition to traverse up the chain,
+ * following Benjie's pattern from postgraphile-plugin-fulltext-filter.
+ *
+ * This is used by satellite plugins (search, BM25, pgvector) that need
+ * to access the query builder from within a filter's apply callback
+ * to inject SELECT expressions (for ranking/scoring) and ORDER BY clauses.
+ *
+ * @param build - The Graphile Build object (needs build.dataplanPg.PgCondition)
+ * @param $condition - The PgCondition instance from the filter apply callback
+ * @returns The PgSelectQueryBuilder if found, or null
+ */
+export declare function getQueryBuilder(build: GraphileBuild.Build, $condition: any): any | null;
+/**
+ * Creates an assertion function that validates filter input values.
+ *
+ * Rejects empty objects in nested contexts (logical operators, relation filters)
+ * and optionally rejects null literals based on the connectionFilterAllowNullInput option.
+ *
+ * Note: Top-level empty filter `{}` is handled in ConnectionFilterArgPlugin's
+ * applyPlan — it's treated as "no filter" and skipped, not rejected.
+ */
+export declare function makeAssertAllowed(build: any): (value: unknown, mode: 'object' | 'list') => void;