Merge pull request #996 from constructive-io/feat/scrub-stale-filter-arg-comments

pyramation · web-flow · commit df0918aae3da · 2026-04-17T18:55:50.000-07:00
chore: scrub stale `filter` argument references in comments/errors
diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts
@@ -7,17 +7,18 @@ 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.
+ * Adds the `where` argument (name configurable via
+ * `connectionFilterArgumentName`, 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: GraphileConfig.Plugin = {
   name: 'ConnectionFilterArgPlugin',
   version,
-  description: 'Adds the filter argument to connection and list fields',
+  description: 'Adds the `where` argument to connection and list fields',
   before: ['PgConnectionArgOrderByPlugin'],
 
   schema: {
@@ -100,7 +101,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = {
                           fieldArg.apply(
                             $pgSelect,
                             (queryBuilder: any, value: any) => {
-                              // If filter is null/undefined or empty {}, treat as "no filter" — skip
+                              // If where is null/undefined or empty {}, treat as "no filter" — skip
                               if (value == null || isEmpty(value)) return;
                               const condition = new PgCondition(queryBuilder);
                               if (attributeCodec) {
@@ -126,7 +127,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = {
                           fieldArg.apply(
                             $pgSelect,
                             (queryBuilder: any, value: any) => {
-                              // If filter is null/undefined or empty {}, treat as "no filter" — skip
+                              // If where is null/undefined or empty {}, treat as "no filter" — skip
                               if (value == null || isEmpty(value)) return;
                               const condition = new PgCondition(queryBuilder);
                               if (attributeCodec) {
@@ -143,7 +144,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = {
                   }),
             },
           },
-          `Adding connection filter '${argName}' arg to field '${fieldName}' of '${Self.name}'`
+          `Adding connection where arg '${argName}' to field '${fieldName}' of '${Self.name}'`
         );
       },
     },
diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts
@@ -96,7 +96,7 @@ export const ConnectionFilterAttributesPlugin: GraphileConfig.Plugin = {
                         if (isEmpty(value)) {
                           throw Object.assign(
                             new Error(
-                              'Empty objects are forbidden in filter argument input.'
+                              'Empty objects are forbidden in where argument input.'
                             ),
                             {}
                           );
@@ -107,7 +107,7 @@ export const ConnectionFilterAttributesPlugin: GraphileConfig.Plugin = {
                         ) {
                           throw Object.assign(
                             new Error(
-                              'Null literals are forbidden in filter argument input.'
+                              'Null literals are forbidden in where argument input.'
                             ),
                             {}
                           );
diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts
@@ -15,15 +15,15 @@ const version = '1.0.0';
  *
  * For unique backward relations (one-to-one), a single filter field is added:
  * ```graphql
- * allClients(filter: {
+ * allClients(where: {
  *   profileByClientId: { bio: { includes: "engineer" } }
  * }) { ... }
  * ```
  *
  * For non-unique backward relations (one-to-many), a "many" filter type is added
  * with `some`, `every`, and `none` sub-fields:
  * ```graphql
- * allClients(filter: {
+ * allClients(where: {
  *   ordersByClientId: { some: { total: { greaterThan: 1000 } } }
  * }) { ... }
  * ```
diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts
@@ -18,7 +18,7 @@ const version = '1.0.0';
  *
  * This plugin adds a `fullName` filter field to `PersonFilter`, typed as `StringFilter`,
  * allowing queries like:
- *   { people(filter: { fullName: { startsWith: "John" } }) { ... } }
+ *   { people(where: { fullName: { startsWith: "John" } }) { ... } }
  *
  * Controlled by the `connectionFilterComputedColumns` schema option (default: true).
  * Requires the `filterBy` behavior on the pgResource to be enabled.
diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts
@@ -18,7 +18,7 @@ const version = '1.0.0';
  * allowing queries like:
  *
  * ```graphql
- * allOrders(filter: {
+ * allOrders(where: {
  *   clientByClientId: { name: { startsWith: "Acme" } }
  * }) { ... }
  * ```
diff --git a/graphile/graphile-connection-filter/src/plugins/operatorApply.ts b/graphile/graphile-connection-filter/src/plugins/operatorApply.ts
@@ -83,7 +83,7 @@ export function makeApplyFromOperatorSpec(
         }
         if (!connectionFilterAllowNullInput && value === null) {
           throw Object.assign(
-            new Error('Null literals are forbidden in filter argument input.'),
+            new Error('Null literals are forbidden in where argument input.'),
             {}
           );
         }
diff --git a/graphile/graphile-connection-filter/src/utils.ts b/graphile/graphile-connection-filter/src/utils.ts
@@ -116,11 +116,11 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' |
       isEmpty: (o: unknown) => boolean
     ) =>
       function (value: unknown, mode: 'object' | 'list') {
-        // Reject empty objects in nested filter contexts (and/or/not, relation filters)
+        // Reject empty objects in nested where contexts (and/or/not, relation filters)
         if (mode === 'object' && isEmpty(value)) {
           throw Object.assign(
             new Error(
-              'Empty objects are forbidden in filter argument input.'
+              'Empty objects are forbidden in where argument input.'
             ),
             {}
           );
@@ -134,7 +134,7 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' |
               if (isEmpty(arr[i])) {
                 throw Object.assign(
                   new Error(
-                    'Empty objects are forbidden in filter argument input.'
+                    'Empty objects are forbidden in where argument input.'
                   ),
                   {}
                 );
@@ -147,7 +147,7 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' |
         if (!connectionFilterAllowNullInput && value === null) {
           throw Object.assign(
             new Error(
-              'Null literals are forbidden in filter argument input.'
+              'Null literals are forbidden in where argument input.'
             ),
             {}
           );
diff --git a/graphile/graphile-postgis/src/plugins/spatial-relations.ts b/graphile/graphile-postgis/src/plugins/spatial-relations.ts
@@ -46,7 +46,7 @@ import type { PostgisExtensionInfo } from './detect-extension';
  * Generated GraphQL (for the `st_dwithin` case):
  *
  * ```graphql
- * telemedicineClinics(filter: {
+ * telemedicineClinics(where: {
  *   nearbyClinic: {
  *     distance: 5000,
  *     some: { specialty: { eq: "pediatrics" } }
diff --git a/graphile/graphile-settings/__tests__/preset-integration.test.ts b/graphile/graphile-settings/__tests__/preset-integration.test.ts
@@ -131,7 +131,7 @@ describe('Schema introspection', () => {
     expect(fieldNames).toContain('embedding');
   });
 
-  it('locations connection exists and has filter argument but no condition', async () => {
+  it('locations connection exists and has where argument but no condition', async () => {
     const result = await query<{ __type: { fields: { name: string; args: { name: string }[] }[] } | null }>({
       query: `
         query {
diff --git a/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts b/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts
@@ -39,7 +39,7 @@ import type { GraphileConfig } from 'graphile-config';
  * and adds `+attribute:filterBy` and `+attribute:orderBy` back to ALL columns, regardless of index status.
  *
  * This means:
- * - All columns will appear in the connection filter's filter argument
+ * - All columns will appear in the connection filter's `where` argument
  * - All columns will appear in the connection's orderBy enum
  * - Developers can filter and sort by any column
  * - It's the developer's/DBA's responsibility to add indexes for frequently filtered/sorted columns
diff --git a/graphile/graphile-settings/src/presets/constructive-preset.ts b/graphile/graphile-settings/src/presets/constructive-preset.ts
@@ -54,8 +54,8 @@ import { getBucketProvisionerConnection } from '../bucket-provisioner-resolver';
  *
  * RELATION FILTERS:
  * - Enabled via connectionFilterRelations: true
- * - Forward: filter child by parent (e.g. allOrders(filter: { clientByClientId: { name: { startsWith: "Acme" } } }))
- * - Backward: filter parent by children (e.g. allClients(filter: { ordersByClientId: { some: { total: { greaterThan: 1000 } } } }))
+ * - Forward: filter child by parent (e.g. allOrders(where: { clientByClientId: { name: { startsWith: "Acme" } } }))
+ * - Backward: filter parent by children (e.g. allClients(where: { ordersByClientId: { some: { total: { greaterThan: 1000 } } } }))
  *
  * USAGE:
  * ```typescript
@@ -105,9 +105,11 @@ export const ConstructivePreset: GraphileConfig.Preset = {
   ],
   /**
    * Disable PostGraphile core's condition argument entirely.
-   * All filtering now lives under the `filter` argument via our v5-native
-   * graphile-connection-filter plugin. Search, BM25, pgvector, and PostGIS
-   * filter fields all hook into `isPgConnectionFilter` instead of `isPgCondition`.
+   * All filtering now lives under the `where` argument via our v5-native
+   * graphile-connection-filter plugin (which renames the default `filter`
+   * argument to `where` via `connectionFilterArgumentName: 'where'`).
+   * Search, BM25, pgvector, and PostGIS filter fields all hook into
+   * `isPgConnectionFilter` instead of `isPgCondition`.
    */
   disablePlugins: [
     'PgConditionArgumentPlugin',
@@ -116,7 +118,7 @@ export const ConstructivePreset: GraphileConfig.Preset = {
   /**
    * Connection Filter Plugin Configuration
    *
-   * These options control what fields appear in the `filter` argument on connections.
+   * These options control what fields appear in the `where` argument on connections.
    * Our v5-native graphile-connection-filter plugin controls relation filters via the
    * `connectionFilterRelations` option passed to ConnectionFilterPreset().
    *
@@ -144,14 +146,14 @@ export const ConstructivePreset: GraphileConfig.Preset = {
     /**
      * connectionFilterLogicalOperators: true (default)
      * Keeps `and`, `or`, `not` operators for combining filter conditions.
-     * Example: filter: { or: [{ name: { eq: "foo" } }, { name: { eq: "bar" } }] }
+     * Example: where: { or: [{ name: { eq: "foo" } }, { name: { eq: "bar" } }] }
      */
     connectionFilterLogicalOperators: true,
 
     /**
      * connectionFilterArrays: true (default)
      * Allows filtering on PostgreSQL array columns.
-     * Example: filter: { tags: { contains: ["important"] } }
+     * Example: where: { tags: { contains: ["important"] } }
      */
     connectionFilterArrays: true,
 

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ const version = '1.0.0';`
`18`	`18`	`*`
`19`	`19`	* This plugin adds a `fullName` filter field to `PersonFilter`, typed as `StringFilter`,
`20`	`20`	`* allowing queries like:`
`21`		`- * { people(filter: { fullName: { startsWith: "John" } }) { ... } }`
	`21`	`+ * { people(where: { fullName: { startsWith: "John" } }) { ... } }`
`22`	`22`	`*`
`23`	`23`	* Controlled by the `connectionFilterComputedColumns` schema option (default: true).
`24`	`24`	* Requires the `filterBy` behavior on the pgResource to be enabled.
Original file line number	Diff line number	Diff line change
`@@ -83,7 +83,7 @@ export function makeApplyFromOperatorSpec(`
`83`	`83`	`}`
`84`	`84`	`if (!connectionFilterAllowNullInput && value === null) {`
`85`	`85`	`throw Object.assign(`
`86`		`- new Error('Null literals are forbidden in filter argument input.'),`
	`86`	`+ new Error('Null literals are forbidden in where argument input.'),`
`87`	`87`	`{}`
`88`	`88`	`);`
`89`	`89`	`}`
Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,7 @@ import type { PostgisExtensionInfo } from './detect-extension';`
`46`	`46`	* Generated GraphQL (for the `st_dwithin` case):
`47`	`47`	`*`
`48`	`48`	* ```graphql
`49`		`- * telemedicineClinics(filter: {`
	`49`	`+ * telemedicineClinics(where: {`
`50`	`50`	`* nearbyClinic: {`
`51`	`51`	`* distance: 5000,`
`52`	`52`	`* some: { specialty: { eq: "pediatrics" } }`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@ import type { GraphileConfig } from 'graphile-config';`
`39`	`39`	* and adds `+attribute:filterBy` and `+attribute:orderBy` back to ALL columns, regardless of index status.
`40`	`40`	`*`
`41`	`41`	`* This means:`
`42`		`- * - All columns will appear in the connection filter's filter argument`
	`42`	+ * - All columns will appear in the connection filter's `where` argument
`43`	`43`	`* - All columns will appear in the connection's orderBy enum`
`44`	`44`	`* - Developers can filter and sort by any column`
`45`	`45`	`* - It's the developer's/DBA's responsibility to add indexes for frequently filtered/sorted columns`