graphile-connection-filter 1.1.0

package/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/plugins/ConnectionFilterTypesPlugin.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionFilterTypesPlugin = void 0;
+require("../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.
+ */
+exports.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/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/plugins/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeApplyFromOperatorSpec = exports.ConnectionFilterBackwardRelationsPlugin = exports.ConnectionFilterForwardRelationsPlugin = exports.ConnectionFilterComputedAttributesPlugin = exports.ConnectionFilterLogicalOperatorsPlugin = exports.ConnectionFilterCustomOperatorsPlugin = exports.ConnectionFilterOperatorsPlugin = exports.ConnectionFilterAttributesPlugin = exports.ConnectionFilterArgPlugin = exports.ConnectionFilterTypesPlugin = exports.ConnectionFilterInflectionPlugin = void 0;
+var ConnectionFilterInflectionPlugin_1 = require("./ConnectionFilterInflectionPlugin");
+Object.defineProperty(exports, "ConnectionFilterInflectionPlugin", { enumerable: true, get: function () { return ConnectionFilterInflectionPlugin_1.ConnectionFilterInflectionPlugin; } });
+var ConnectionFilterTypesPlugin_1 = require("./ConnectionFilterTypesPlugin");
+Object.defineProperty(exports, "ConnectionFilterTypesPlugin", { enumerable: true, get: function () { return ConnectionFilterTypesPlugin_1.ConnectionFilterTypesPlugin; } });
+var ConnectionFilterArgPlugin_1 = require("./ConnectionFilterArgPlugin");
+Object.defineProperty(exports, "ConnectionFilterArgPlugin", { enumerable: true, get: function () { return ConnectionFilterArgPlugin_1.ConnectionFilterArgPlugin; } });
+var ConnectionFilterAttributesPlugin_1 = require("./ConnectionFilterAttributesPlugin");
+Object.defineProperty(exports, "ConnectionFilterAttributesPlugin", { enumerable: true, get: function () { return ConnectionFilterAttributesPlugin_1.ConnectionFilterAttributesPlugin; } });
+var ConnectionFilterOperatorsPlugin_1 = require("./ConnectionFilterOperatorsPlugin");
+Object.defineProperty(exports, "ConnectionFilterOperatorsPlugin", { enumerable: true, get: function () { return ConnectionFilterOperatorsPlugin_1.ConnectionFilterOperatorsPlugin; } });
+var ConnectionFilterCustomOperatorsPlugin_1 = require("./ConnectionFilterCustomOperatorsPlugin");
+Object.defineProperty(exports, "ConnectionFilterCustomOperatorsPlugin", { enumerable: true, get: function () { return ConnectionFilterCustomOperatorsPlugin_1.ConnectionFilterCustomOperatorsPlugin; } });
+var ConnectionFilterLogicalOperatorsPlugin_1 = require("./ConnectionFilterLogicalOperatorsPlugin");
+Object.defineProperty(exports, "ConnectionFilterLogicalOperatorsPlugin", { enumerable: true, get: function () { return ConnectionFilterLogicalOperatorsPlugin_1.ConnectionFilterLogicalOperatorsPlugin; } });
+var ConnectionFilterComputedAttributesPlugin_1 = require("./ConnectionFilterComputedAttributesPlugin");
+Object.defineProperty(exports, "ConnectionFilterComputedAttributesPlugin", { enumerable: true, get: function () { return ConnectionFilterComputedAttributesPlugin_1.ConnectionFilterComputedAttributesPlugin; } });
+var ConnectionFilterForwardRelationsPlugin_1 = require("./ConnectionFilterForwardRelationsPlugin");
+Object.defineProperty(exports, "ConnectionFilterForwardRelationsPlugin", { enumerable: true, get: function () { return ConnectionFilterForwardRelationsPlugin_1.ConnectionFilterForwardRelationsPlugin; } });
+var ConnectionFilterBackwardRelationsPlugin_1 = require("./ConnectionFilterBackwardRelationsPlugin");
+Object.defineProperty(exports, "ConnectionFilterBackwardRelationsPlugin", { enumerable: true, get: function () { return ConnectionFilterBackwardRelationsPlugin_1.ConnectionFilterBackwardRelationsPlugin; } });
+var operatorApply_1 = require("./operatorApply");
+Object.defineProperty(exports, "makeApplyFromOperatorSpec", { enumerable: true, get: function () { return operatorApply_1.makeApplyFromOperatorSpec; } });

package/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/plugins/operatorApply.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeApplyFromOperatorSpec = makeApplyFromOperatorSpec;
+/**
+ * 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.
+ */
+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/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/preset.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * 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,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionFilterPreset = ConnectionFilterPreset;
+require("./augmentations");
+const plugins_1 = require("./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
+ */
+function ConnectionFilterPreset(options = {}) {
+    const mergedOptions = { ...defaultSchemaOptions, ...options };
+    const plugins = [
+        plugins_1.ConnectionFilterInflectionPlugin,
+        plugins_1.ConnectionFilterTypesPlugin,
+        plugins_1.ConnectionFilterArgPlugin,
+        plugins_1.ConnectionFilterAttributesPlugin,
+        plugins_1.ConnectionFilterOperatorsPlugin,
+        plugins_1.ConnectionFilterCustomOperatorsPlugin,
+    ];
+    // Logical operators plugin always included — checks
+    // build.options.connectionFilterLogicalOperators at runtime
+    plugins.push(plugins_1.ConnectionFilterLogicalOperatorsPlugin);
+    // Computed columns are opt-in (disabled by default)
+    if (mergedOptions.connectionFilterComputedColumns) {
+        plugins.push(plugins_1.ConnectionFilterComputedAttributesPlugin);
+    }
+    // Relation filter plugins are always included but check
+    // build.options.connectionFilterRelations at runtime
+    plugins.push(plugins_1.ConnectionFilterForwardRelationsPlugin);
+    plugins.push(plugins_1.ConnectionFilterBackwardRelationsPlugin);
+    return {
+        plugins,
+        schema: mergedOptions,
+    };
+}
+exports.default = ConnectionFilterPreset;

package/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/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.$$filters = void 0;
+/**
+ * Symbol used to store the filter operator registry on the build object.
+ */
+exports.$$filters = Symbol('connectionFilters');