graphile-connection-filter 1.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# graphile-connection-filter
+
+A PostGraphile v5 native connection filter plugin for the Constructive monorepo.
+
+Adds advanced filtering capabilities to connection and list fields, including:
+
+- Per-table filter types (e.g. `UserFilter`)
+- Per-scalar operator types (e.g. `StringFilter`, `IntFilter`)
+- Standard operators: `equalTo`, `notEqualTo`, `isNull`, `in`, `notIn`, etc.
+- Sort operators: `lessThan`, `greaterThan`, etc.
+- Pattern matching: `includes`, `startsWith`, `endsWith`, `like` + case-insensitive variants
+- Type-specific operators: JSONB, hstore, inet, array, range
+- Logical operators: `and`, `or`, `not`
+- Declarative custom operator API: `connectionFilterOperatorFactories` for satellite plugins
+
+## Usage
+
+```typescript
+import { ConnectionFilterPreset } from 'graphile-connection-filter';
+
+const preset: GraphileConfig.Preset = {
+  extends: [
+    ConnectionFilterPreset(),
+  ],
+};
+```
+
+## Custom Operators
+
+Satellite plugins declare custom operators via `connectionFilterOperatorFactories` in their preset's schema options. Each factory is a function that receives the `build` object and returns an array of operator registrations:
+
+```typescript
+import type { ConnectionFilterOperatorFactory } from 'graphile-connection-filter';
+
+const myOperatorFactory: ConnectionFilterOperatorFactory = (build) => [{
+  typeNames: 'MyType',
+  operatorName: 'myOperator',
+  spec: {
+    description: 'My custom operator',
+    resolve: (sqlIdentifier, sqlValue) => build.sql`${sqlIdentifier} OP ${sqlValue}`,
+  },
+}];
+
+const MyPreset: GraphileConfig.Preset = {
+  schema: {
+    connectionFilterOperatorFactories: [myOperatorFactory],
+  },
+};
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/augmentations.d.ts

@@ -0,0 +1,104 @@
+/**
+ * TypeScript namespace augmentations for graphile-connection-filter.
+ *
+ * These extend the Graphile type system so that our custom inflection methods,
+ * build properties, scope properties, schema options, and behaviors are
+ * recognized by the TypeScript compiler.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { ConnectionFilterOperatorFactory, ConnectionFilterOperatorsDigest, PgConnectionFilterOperatorsScope } from './types';
+declare global {
+    namespace GraphileBuild {
+        interface Inflection {
+            /** Filter type name for a table, e.g. "UserFilter" */
+            filterType(this: Inflection, typeName: string): string;
+            /** Filter field type name for a scalar, e.g. "StringFilter" */
+            filterFieldType(this: Inflection, typeName: string): string;
+            /** Filter field list type name for an array scalar, e.g. "StringListFilter" */
+            filterFieldListType(this: Inflection, typeName: string): string;
+            /** Forward relation field name (passthrough) */
+            filterSingleRelationFieldName(this: Inflection, fieldName: string): string;
+            /** Forward relation exists field name, e.g. "clientByClientIdExists" */
+            filterForwardRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Backward single relation field name (passthrough) */
+            filterSingleRelationByKeysBackwardsFieldName(this: Inflection, fieldName: string): string;
+            /** Backward single relation exists field name */
+            filterBackwardSingleRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Backward many relation field name (passthrough) */
+            filterManyRelationByKeysFieldName(this: Inflection, fieldName: string): string;
+            /** Backward many relation exists field name */
+            filterBackwardManyRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Many filter type name, e.g. "ClientToManyOrderFilter" */
+            filterManyType(this: Inflection, table: any, foreignTable: any): string;
+        }
+        interface Build {
+            /** Returns the operator digest for a given codec, or null if not filterable */
+            connectionFilterOperatorsDigest(codec: any): ConnectionFilterOperatorsDigest | null;
+            /** Escapes LIKE wildcard characters (% and _) */
+            escapeLikeWildcards(input: unknown): string;
+            /** Internal filter operator registry keyed by filter type name */
+            [key: symbol]: any;
+        }
+        interface ScopeInputObject {
+            /** True if this is a table-level connection filter type (e.g. UserFilter) */
+            isPgConnectionFilter?: boolean;
+            /** Operator type scope data (present on scalar filter types like StringFilter) */
+            pgConnectionFilterOperators?: PgConnectionFilterOperatorsScope;
+            /** Foreign table resource (used by many filter types) */
+            foreignTable?: any;
+            /** True if this is a many-relation filter type (e.g. ClientToManyOrderFilter) */
+            isPgConnectionFilterMany?: boolean;
+        }
+        interface ScopeInputObjectFieldsField {
+            /** True if this field is an attribute-based filter field */
+            isPgConnectionFilterField?: boolean;
+            /** True if this field is a filter operator (e.g. equalTo, lessThan) */
+            isPgConnectionFilterOperator?: boolean;
+            /** True if this field is a logical operator (and/or/not) */
+            isPgConnectionFilterOperatorLogical?: boolean;
+            /** True if this is a many-relation filter field */
+            isPgConnectionFilterManyField?: boolean;
+        }
+        interface BehaviorStrings {
+            filter: true;
+            filterProc: true;
+            'attribute:filterBy': true;
+        }
+        interface SchemaOptions {
+            connectionFilterArgumentName?: string;
+            connectionFilterArrays?: boolean;
+            connectionFilterLogicalOperators?: boolean;
+            connectionFilterAllowNullInput?: boolean;
+            connectionFilterAllowedFieldTypes?: string[];
+            connectionFilterAllowedOperators?: string[];
+            connectionFilterOperatorNames?: Record<string, string>;
+            connectionFilterSetofFunctions?: boolean;
+            connectionFilterComputedColumns?: boolean;
+            connectionFilterRelations?: boolean;
+            /** If true (default), relation filter fields are only added for FKs with supporting indexes.
+             * This prevents generating EXISTS subqueries that would cause sequential scans on large tables.
+             * Set to false to allow relation filters on all FKs regardless of index status. */
+            connectionFilterRelationsRequireIndex?: boolean;
+            /**
+             * Declarative operator factories. Each factory receives the build object
+             * and returns operator registrations. Replaces addConnectionFilterOperator.
+             */
+            connectionFilterOperatorFactories?: ConnectionFilterOperatorFactory[];
+        }
+    }
+    namespace GraphileConfig {
+        interface Plugins {
+            ConnectionFilterInflectionPlugin: true;
+            ConnectionFilterTypesPlugin: true;
+            ConnectionFilterArgPlugin: true;
+            ConnectionFilterAttributesPlugin: true;
+            ConnectionFilterOperatorsPlugin: true;
+            ConnectionFilterCustomOperatorsPlugin: true;
+            ConnectionFilterLogicalOperatorsPlugin: true;
+            ConnectionFilterComputedAttributesPlugin: true;
+            ConnectionFilterForwardRelationsPlugin: true;
+            ConnectionFilterBackwardRelationsPlugin: true;
+        }
+    }
+}

package/augmentations.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * TypeScript namespace augmentations for graphile-connection-filter.
+ *
+ * These extend the Graphile type system so that our custom inflection methods,
+ * build properties, scope properties, schema options, and behaviors are
+ * recognized by the TypeScript compiler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("graphile-build");
+require("graphile-build-pg");

package/esm/augmentations.d.ts

@@ -0,0 +1,104 @@
+/**
+ * TypeScript namespace augmentations for graphile-connection-filter.
+ *
+ * These extend the Graphile type system so that our custom inflection methods,
+ * build properties, scope properties, schema options, and behaviors are
+ * recognized by the TypeScript compiler.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { ConnectionFilterOperatorFactory, ConnectionFilterOperatorsDigest, PgConnectionFilterOperatorsScope } from './types';
+declare global {
+    namespace GraphileBuild {
+        interface Inflection {
+            /** Filter type name for a table, e.g. "UserFilter" */
+            filterType(this: Inflection, typeName: string): string;
+            /** Filter field type name for a scalar, e.g. "StringFilter" */
+            filterFieldType(this: Inflection, typeName: string): string;
+            /** Filter field list type name for an array scalar, e.g. "StringListFilter" */
+            filterFieldListType(this: Inflection, typeName: string): string;
+            /** Forward relation field name (passthrough) */
+            filterSingleRelationFieldName(this: Inflection, fieldName: string): string;
+            /** Forward relation exists field name, e.g. "clientByClientIdExists" */
+            filterForwardRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Backward single relation field name (passthrough) */
+            filterSingleRelationByKeysBackwardsFieldName(this: Inflection, fieldName: string): string;
+            /** Backward single relation exists field name */
+            filterBackwardSingleRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Backward many relation field name (passthrough) */
+            filterManyRelationByKeysFieldName(this: Inflection, fieldName: string): string;
+            /** Backward many relation exists field name */
+            filterBackwardManyRelationExistsFieldName(this: Inflection, relationFieldName: string): string;
+            /** Many filter type name, e.g. "ClientToManyOrderFilter" */
+            filterManyType(this: Inflection, table: any, foreignTable: any): string;
+        }
+        interface Build {
+            /** Returns the operator digest for a given codec, or null if not filterable */
+            connectionFilterOperatorsDigest(codec: any): ConnectionFilterOperatorsDigest | null;
+            /** Escapes LIKE wildcard characters (% and _) */
+            escapeLikeWildcards(input: unknown): string;
+            /** Internal filter operator registry keyed by filter type name */
+            [key: symbol]: any;
+        }
+        interface ScopeInputObject {
+            /** True if this is a table-level connection filter type (e.g. UserFilter) */
+            isPgConnectionFilter?: boolean;
+            /** Operator type scope data (present on scalar filter types like StringFilter) */
+            pgConnectionFilterOperators?: PgConnectionFilterOperatorsScope;
+            /** Foreign table resource (used by many filter types) */
+            foreignTable?: any;
+            /** True if this is a many-relation filter type (e.g. ClientToManyOrderFilter) */
+            isPgConnectionFilterMany?: boolean;
+        }
+        interface ScopeInputObjectFieldsField {
+            /** True if this field is an attribute-based filter field */
+            isPgConnectionFilterField?: boolean;
+            /** True if this field is a filter operator (e.g. equalTo, lessThan) */
+            isPgConnectionFilterOperator?: boolean;
+            /** True if this field is a logical operator (and/or/not) */
+            isPgConnectionFilterOperatorLogical?: boolean;
+            /** True if this is a many-relation filter field */
+            isPgConnectionFilterManyField?: boolean;
+        }
+        interface BehaviorStrings {
+            filter: true;
+            filterProc: true;
+            'attribute:filterBy': true;
+        }
+        interface SchemaOptions {
+            connectionFilterArgumentName?: string;
+            connectionFilterArrays?: boolean;
+            connectionFilterLogicalOperators?: boolean;
+            connectionFilterAllowNullInput?: boolean;
+            connectionFilterAllowedFieldTypes?: string[];
+            connectionFilterAllowedOperators?: string[];
+            connectionFilterOperatorNames?: Record<string, string>;
+            connectionFilterSetofFunctions?: boolean;
+            connectionFilterComputedColumns?: boolean;
+            connectionFilterRelations?: boolean;
+            /** If true (default), relation filter fields are only added for FKs with supporting indexes.
+             * This prevents generating EXISTS subqueries that would cause sequential scans on large tables.
+             * Set to false to allow relation filters on all FKs regardless of index status. */
+            connectionFilterRelationsRequireIndex?: boolean;
+            /**
+             * Declarative operator factories. Each factory receives the build object
+             * and returns operator registrations. Replaces addConnectionFilterOperator.
+             */
+            connectionFilterOperatorFactories?: ConnectionFilterOperatorFactory[];
+        }
+    }
+    namespace GraphileConfig {
+        interface Plugins {
+            ConnectionFilterInflectionPlugin: true;
+            ConnectionFilterTypesPlugin: true;
+            ConnectionFilterArgPlugin: true;
+            ConnectionFilterAttributesPlugin: true;
+            ConnectionFilterOperatorsPlugin: true;
+            ConnectionFilterCustomOperatorsPlugin: true;
+            ConnectionFilterLogicalOperatorsPlugin: true;
+            ConnectionFilterComputedAttributesPlugin: true;
+            ConnectionFilterForwardRelationsPlugin: true;
+            ConnectionFilterBackwardRelationsPlugin: true;
+        }
+    }
+}

package/esm/augmentations.js

@@ -0,0 +1,9 @@
+/**
+ * TypeScript namespace augmentations for graphile-connection-filter.
+ *
+ * These extend the Graphile type system so that our custom inflection methods,
+ * build properties, scope properties, schema options, and behaviors are
+ * recognized by the TypeScript compiler.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';

package/esm/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * graphile-connection-filter
+ *
+ * A PostGraphile v5 native connection filter plugin.
+ * Adds advanced filtering capabilities to connection and list fields.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectionFilterPreset } from 'graphile-connection-filter';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConnectionFilterPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * For satellite plugins that need to register custom operators, declare them
+ * as factories in the preset's `connectionFilterOperatorFactories` option:
+ * ```typescript
+ * import type { ConnectionFilterOperatorFactory } from 'graphile-connection-filter';
+ *
+ * const myOperatorFactory: ConnectionFilterOperatorFactory = (build) => [{
+ *   typeNames: 'MyType',
+ *   operatorName: 'myOperator',
+ *   spec: {
+ *     description: 'My custom operator',
+ *     resolve: (sqlIdentifier, sqlValue) => build.sql`${sqlIdentifier} OP ${sqlValue}`,
+ *   },
+ * }];
+ *
+ * export const MyPreset = {
+ *   schema: {
+ *     connectionFilterOperatorFactories: [myOperatorFactory],
+ *   },
+ *   plugins: [MyPlugin],
+ * };
+ * ```
+ *
+ * For satellite plugins that need to access the query builder from a filter apply:
+ * ```typescript
+ * import { getQueryBuilder } from 'graphile-connection-filter';
+ * // In your filter field's apply callback:
+ * const qb = getQueryBuilder(build, $condition);
+ * if (qb) {
+ *   const idx = qb.selectAndReturnIndex(sql`...`);
+ *   qb.setMeta('key', { selectIndex: idx });
+ * }
+ * ```
+ */
+export { ConnectionFilterPreset } from './preset';
+export { ConnectionFilterInflectionPlugin, ConnectionFilterTypesPlugin, ConnectionFilterArgPlugin, ConnectionFilterAttributesPlugin, ConnectionFilterOperatorsPlugin, ConnectionFilterCustomOperatorsPlugin, ConnectionFilterLogicalOperatorsPlugin, ConnectionFilterComputedAttributesPlugin, ConnectionFilterForwardRelationsPlugin, ConnectionFilterBackwardRelationsPlugin, makeApplyFromOperatorSpec, } from './plugins';
+export type { ConnectionFilterOperatorSpec, ConnectionFilterOperatorRegistration, ConnectionFilterOperatorFactory, ConnectionFilterOptions, ConnectionFilterOperatorsDigest, PgConnectionFilterOperatorsScope, } from './types';
+export { $$filters } from './types';
+export { isEmpty, makeAssertAllowed, getQueryBuilder, isComputedScalarAttributeResource, getComputedAttributeResources, } from './utils';

package/esm/index.js

@@ -0,0 +1,56 @@
+/**
+ * graphile-connection-filter
+ *
+ * A PostGraphile v5 native connection filter plugin.
+ * Adds advanced filtering capabilities to connection and list fields.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectionFilterPreset } from 'graphile-connection-filter';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConnectionFilterPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * For satellite plugins that need to register custom operators, declare them
+ * as factories in the preset's `connectionFilterOperatorFactories` option:
+ * ```typescript
+ * import type { ConnectionFilterOperatorFactory } from 'graphile-connection-filter';
+ *
+ * const myOperatorFactory: ConnectionFilterOperatorFactory = (build) => [{
+ *   typeNames: 'MyType',
+ *   operatorName: 'myOperator',
+ *   spec: {
+ *     description: 'My custom operator',
+ *     resolve: (sqlIdentifier, sqlValue) => build.sql`${sqlIdentifier} OP ${sqlValue}`,
+ *   },
+ * }];
+ *
+ * export const MyPreset = {
+ *   schema: {
+ *     connectionFilterOperatorFactories: [myOperatorFactory],
+ *   },
+ *   plugins: [MyPlugin],
+ * };
+ * ```
+ *
+ * For satellite plugins that need to access the query builder from a filter apply:
+ * ```typescript
+ * import { getQueryBuilder } from 'graphile-connection-filter';
+ * // In your filter field's apply callback:
+ * const qb = getQueryBuilder(build, $condition);
+ * if (qb) {
+ *   const idx = qb.selectAndReturnIndex(sql`...`);
+ *   qb.setMeta('key', { selectIndex: idx });
+ * }
+ * ```
+ */
+export { ConnectionFilterPreset } from './preset';
+// Re-export all plugins for granular use
+export { ConnectionFilterInflectionPlugin, ConnectionFilterTypesPlugin, ConnectionFilterArgPlugin, ConnectionFilterAttributesPlugin, ConnectionFilterOperatorsPlugin, ConnectionFilterCustomOperatorsPlugin, ConnectionFilterLogicalOperatorsPlugin, ConnectionFilterComputedAttributesPlugin, ConnectionFilterForwardRelationsPlugin, ConnectionFilterBackwardRelationsPlugin, makeApplyFromOperatorSpec, } from './plugins';
+export { $$filters } from './types';
+// Re-export utilities
+export { isEmpty, makeAssertAllowed, getQueryBuilder, isComputedScalarAttributeResource, getComputedAttributeResources, } from './utils';

package/esm/plugins/ConnectionFilterArgPlugin.d.ts

@@ -0,0 +1,13 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterArgPlugin
+ *
+ * Adds the filter argument (configurable name, default 'where') to connection
+ * and simple collection fields. Uses `applyPlan` to create a PgCondition that
+ * child filter fields can add WHERE clauses to.
+ *
+ * This runs before PgConnectionArgOrderByPlugin so that filters are applied
+ * before ordering (important for e.g. full-text search rank ordering).
+ */
+export declare const ConnectionFilterArgPlugin: GraphileConfig.Plugin;

package/esm/plugins/ConnectionFilterArgPlugin.js

@@ -0,0 +1,96 @@
+import '../augmentations';
+import { isEmpty } from '../utils';
+const version = '1.0.0';
+/**
+ * ConnectionFilterArgPlugin
+ *
+ * Adds the filter argument (configurable name, default 'where') to connection
+ * and simple collection fields. Uses `applyPlan` to create a PgCondition that
+ * child filter fields can add WHERE clauses to.
+ *
+ * This runs before PgConnectionArgOrderByPlugin so that filters are applied
+ * before ordering (important for e.g. full-text search rank ordering).
+ */
+export const ConnectionFilterArgPlugin = {
+    name: 'ConnectionFilterArgPlugin',
+    version,
+    description: 'Adds the filter argument to connection and list fields',
+    before: ['PgConnectionArgOrderByPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields_field_args(args, build, context) {
+                const { extend, inflection, EXPORTABLE, dataplanPg: { PgCondition }, } = build;
+                const { scope: { isPgFieldConnection, isPgFieldSimpleCollection, pgFieldResource: resource, pgFieldCodec, fieldName, }, Self, } = context;
+                const shouldAddFilter = isPgFieldConnection || isPgFieldSimpleCollection;
+                if (!shouldAddFilter)
+                    return args;
+                const codec = pgFieldCodec ?? resource?.codec;
+                if (!codec)
+                    return args;
+                // Check behavior: procedures use "filterProc", tables use "filter"
+                const desiredBehavior = resource?.parameters
+                    ? 'filterProc'
+                    : 'filter';
+                if (resource
+                    ? !build.behavior.pgResourceMatches(resource, desiredBehavior)
+                    : !build.behavior.pgCodecMatches(codec, desiredBehavior)) {
+                    return args;
+                }
+                const returnCodec = codec;
+                const nodeType = build.getGraphQLTypeByPgCodec(returnCodec, 'output');
+                if (!nodeType)
+                    return args;
+                const nodeTypeName = nodeType.name;
+                const filterTypeName = inflection.filterType(nodeTypeName);
+                const FilterType = build.getTypeByName(filterTypeName);
+                if (!FilterType)
+                    return args;
+                // For setof functions returning scalars, track the codec
+                const attributeCodec = resource?.parameters && !resource?.codec.attributes
+                    ? resource.codec
+                    : null;
+                const argName = build.options.connectionFilterArgumentName || 'where';
+                return extend(args, {
+                    [argName]: {
+                        description: 'A filter to be used in determining which values should be returned by the collection.',
+                        type: FilterType,
+                        ...(isPgFieldConnection
+                            ? {
+                                applyPlan: EXPORTABLE((PgCondition, isEmpty, attributeCodec) => function (_, $connection, fieldArg) {
+                                    const $pgSelect = $connection.getSubplan();
+                                    fieldArg.apply($pgSelect, (queryBuilder, value) => {
+                                        // If filter is null/undefined or empty {}, treat as "no filter" — skip
+                                        if (value == null || isEmpty(value))
+                                            return;
+                                        const condition = new PgCondition(queryBuilder);
+                                        if (attributeCodec) {
+                                            condition.extensions.pgFilterAttribute = {
+                                                codec: attributeCodec,
+                                            };
+                                        }
+                                        return condition;
+                                    });
+                                }, [PgCondition, isEmpty, attributeCodec]),
+                            }
+                            : {
+                                applyPlan: EXPORTABLE((PgCondition, isEmpty, attributeCodec) => function (_, $pgSelect, fieldArg) {
+                                    fieldArg.apply($pgSelect, (queryBuilder, value) => {
+                                        // If filter is null/undefined or empty {}, treat as "no filter" — skip
+                                        if (value == null || isEmpty(value))
+                                            return;
+                                        const condition = new PgCondition(queryBuilder);
+                                        if (attributeCodec) {
+                                            condition.extensions.pgFilterAttribute = {
+                                                codec: attributeCodec,
+                                            };
+                                        }
+                                        return condition;
+                                    });
+                                }, [PgCondition, isEmpty, attributeCodec]),
+                            }),
+                    },
+                }, `Adding connection filter '${argName}' arg to field '${fieldName}' of '${Self.name}'`);
+            },
+        },
+    },
+};

package/esm/plugins/ConnectionFilterAttributesPlugin.d.ts

@@ -0,0 +1,14 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * ConnectionFilterAttributesPlugin
+ *
+ * Adds per-column filter fields to the table filter types.
+ * For example, on `UserFilter`, adds fields like `name` (type: StringFilter),
+ * `age` (type: IntFilter), etc.
+ *
+ * Each field's `apply` function creates a new PgCondition with the
+ * `pgFilterAttribute` extension set, so downstream operator fields know
+ * which column they are operating on.
+ */
+export declare const ConnectionFilterAttributesPlugin: GraphileConfig.Plugin;