graphile-bulk-mutations 0.2.0

package/esm/utils/relations.js

@@ -0,0 +1,83 @@
+/**
+ * Relation discovery utilities for bulk relational/nested inserts.
+ *
+ * Inspects the PostGraphile registry to find "has many" (isReferencee)
+ * relations for a given resource. For each qualifying relation, computes
+ * column metadata needed to build child INSERT statements.
+ */
+/**
+ * Discover "has many" relations for a resource that qualify for nested
+ * inserts. A relation qualifies when:
+ *
+ * 1. isReferencee is true (the remote table references the local table)
+ * 2. isUnique is false (one-to-many, not one-to-one)
+ * 3. The remote resource is a regular table (has attributes, uniques, etc.)
+ */
+export function discoverNestedRelations(resource, pgRegistry, inflection, sql) {
+    const codecName = resource.codec.name;
+    const relations = pgRegistry.pgRelations[codecName];
+    if (!relations)
+        return [];
+    const result = [];
+    for (const [relationName, relation] of Object.entries(relations)) {
+        // Only reverse relations (child references parent)
+        if (!relation.isReferencee)
+            continue;
+        // Only one-to-many (skip one-to-one)
+        if (relation.isUnique)
+            continue;
+        const remoteResource = relation.remoteResource;
+        if (!remoteResource?.codec?.attributes)
+            continue;
+        if (remoteResource.codec.polymorphism)
+            continue;
+        if (remoteResource.codec.isAnonymous)
+            continue;
+        if (!remoteResource.uniques?.length)
+            continue;
+        // Build child column metadata (all insertable columns)
+        const childFieldToAttr = {};
+        const childColumnSpecs = [];
+        for (const [attrName, attr] of Object.entries(remoteResource.codec.attributes)) {
+            if (attr.extensions?.isInsertable === false)
+                continue;
+            const gqlFieldName = inflection.attribute({
+                attributeName: attrName,
+                codec: remoteResource.codec
+            });
+            childFieldToAttr[gqlFieldName] = attrName;
+            childColumnSpecs.push({
+                name: attrName,
+                sqlType: sql.compile(attr.codec.sqlType).text
+            });
+        }
+        // Find PK columns for child
+        const childPrimaryUnique = remoteResource.uniques.find((u) => u.isPrimary) ??
+            remoteResource.uniques[0];
+        const childPkColumns = [...childPrimaryUnique.attributes];
+        const childCompiledFrom = sql.compile(remoteResource.from).text;
+        // Find the registry key of the remote resource
+        let remoteResourceName = '';
+        for (const [name, res] of Object.entries(pgRegistry.pgResources)) {
+            if (res === remoteResource) {
+                remoteResourceName = name;
+                break;
+            }
+        }
+        // Derive a clean GraphQL field name from the remote resource name
+        const fieldName = inflection.camelCase(remoteResourceName);
+        result.push({
+            relationName,
+            fieldName,
+            remoteResource,
+            remoteResourceName,
+            localAttributes: [...relation.localAttributes],
+            remoteAttributes: [...relation.remoteAttributes],
+            childFieldToAttr,
+            childColumnSpecs,
+            childCompiledFrom,
+            childPkColumns
+        });
+    }
+    return result;
+}

package/esm/utils/sql-builder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SQL builder utilities for bulk mutations.
+ *
+ * Provides parameterized SQL generation for VALUES clauses, ON CONFLICT
+ * clauses, and SET patches. Handles auto-batching when the parameter
+ * count would exceed PostgreSQL's 32K limit.
+ *
+ * IMPORTANT: All mutation queries use `RETURNING <pk_columns>` instead of
+ * `RETURNING *` to respect column-level SELECT grants. The caller is
+ * responsible for doing a follow-up SELECT using the returned PKs to
+ * resolve the full row through PostGraphile's grant-aware query pipeline.
+ * See: https://github.com/pyramation/graphile-column-privileges-mutations
+ */
+export interface ColumnSpec {
+    name: string;
+    sqlType: string;
+}
+export interface InsertBatch {
+    text: string;
+    values: unknown[];
+}
+/**
+ * Builds parameterized INSERT ... VALUES SQL with optional ON CONFLICT clause.
+ * Auto-splits into multiple batches when parameter count exceeds PG_MAX_PARAMS.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkInsertSQL(tableName: string, columns: ColumnSpec[], rows: Record<string, unknown>[], returningColumns: string[], onConflict?: {
+    conflictColumns?: string[];
+    action: 'IGNORE';
+} | {
+    conflictColumns: string[];
+    action: 'UPDATE';
+    updateColumns?: string[];
+}): InsertBatch[];
+/**
+ * Builds a parameterized UPDATE ... SET ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkUpdateSQL(tableName: string, patch: Record<string, unknown>, columns: ColumnSpec[], returningColumns: string[], whereClause: string, whereParams: unknown[]): {
+    text: string;
+    values: unknown[];
+};
+/**
+ * Builds a parameterized DELETE ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkDeleteSQL(tableName: string, returningColumns: string[], whereClause: string, whereParams: unknown[]): {
+    text: string;
+    values: unknown[];
+};

package/esm/utils/sql-builder.js

@@ -0,0 +1,121 @@
+/**
+ * SQL builder utilities for bulk mutations.
+ *
+ * Provides parameterized SQL generation for VALUES clauses, ON CONFLICT
+ * clauses, and SET patches. Handles auto-batching when the parameter
+ * count would exceed PostgreSQL's 32K limit.
+ *
+ * IMPORTANT: All mutation queries use `RETURNING <pk_columns>` instead of
+ * `RETURNING *` to respect column-level SELECT grants. The caller is
+ * responsible for doing a follow-up SELECT using the returned PKs to
+ * resolve the full row through PostGraphile's grant-aware query pipeline.
+ * See: https://github.com/pyramation/graphile-column-privileges-mutations
+ */
+import { PG_MAX_PARAMS } from '../types';
+/**
+ * Builds parameterized INSERT ... VALUES SQL with optional ON CONFLICT clause.
+ * Auto-splits into multiple batches when parameter count exceeds PG_MAX_PARAMS.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export function buildBulkInsertSQL(tableName, columns, rows, returningColumns, onConflict) {
+    const colNames = columns.map((c) => `"${c.name}"`);
+    const colsPerRow = columns.length;
+    const maxRowsPerBatch = Math.floor(PG_MAX_PARAMS / colsPerRow);
+    const returningClause = returningColumns.length > 0
+        ? returningColumns.map((c) => `"${c}"`).join(', ')
+        : '*';
+    const batches = [];
+    for (let offset = 0; offset < rows.length; offset += maxRowsPerBatch) {
+        const batchRows = rows.slice(offset, offset + maxRowsPerBatch);
+        const values = [];
+        const valuePlaceholders = [];
+        for (const row of batchRows) {
+            const placeholders = [];
+            for (const col of columns) {
+                const val = row[col.name];
+                if (val === undefined) {
+                    placeholders.push('DEFAULT');
+                }
+                else if (val === null) {
+                    placeholders.push('NULL');
+                }
+                else {
+                    values.push(val);
+                    placeholders.push(`$${values.length}::${col.sqlType}`);
+                }
+            }
+            valuePlaceholders.push(`(${placeholders.join(', ')})`);
+        }
+        let text = `INSERT INTO ${tableName} (${colNames.join(', ')})\nVALUES ${valuePlaceholders.join(',\n       ')}`;
+        if (onConflict) {
+            if (onConflict.conflictColumns && onConflict.conflictColumns.length > 0) {
+                const colList = onConflict.conflictColumns.map((c) => `"${c}"`).join(', ');
+                text += `\nON CONFLICT (${colList})`;
+            }
+            else {
+                text += '\nON CONFLICT';
+            }
+            if (onConflict.action === 'IGNORE') {
+                text += ' DO NOTHING';
+            }
+            else if (onConflict.action === 'UPDATE') {
+                const setCols = onConflict.updateColumns && onConflict.updateColumns.length > 0
+                    ? onConflict.updateColumns
+                    : columns.map((c) => c.name);
+                const setClause = setCols
+                    .map((c) => `"${c}" = EXCLUDED."${c}"`)
+                    .join(', ');
+                text += ` DO UPDATE SET ${setClause}`;
+            }
+        }
+        text += `\nRETURNING ${returningClause}`;
+        batches.push({ text, values });
+    }
+    return batches;
+}
+/**
+ * Builds a parameterized UPDATE ... SET ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export function buildBulkUpdateSQL(tableName, patch, columns, returningColumns, whereClause, whereParams) {
+    const values = [];
+    const setClauses = [];
+    for (const [fieldName, value] of Object.entries(patch)) {
+        const col = columns.find((c) => c.name === fieldName);
+        if (!col)
+            continue;
+        if (value === undefined)
+            continue;
+        values.push(value);
+        setClauses.push(`"${col.name}" = $${values.length}::${col.sqlType}`);
+    }
+    if (setClauses.length === 0) {
+        throw new Error('No columns to update in patch');
+    }
+    // Renumber where params to follow set params
+    const offset = values.length;
+    const renumberedWhere = whereClause.replace(/\$(\d+)/g, (_, n) => `$${parseInt(n) + offset}`);
+    values.push(...whereParams);
+    const returningClause = returningColumns.length > 0
+        ? returningColumns.map((c) => `"${c}"`).join(', ')
+        : '*';
+    const text = `UPDATE ${tableName}\nSET ${setClauses.join(', ')}\nWHERE ${renumberedWhere}\nRETURNING ${returningClause}`;
+    return { text, values };
+}
+/**
+ * Builds a parameterized DELETE ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export function buildBulkDeleteSQL(tableName, returningColumns, whereClause, whereParams) {
+    const returningClause = returningColumns.length > 0
+        ? returningColumns.map((c) => `"${c}"`).join(', ')
+        : '*';
+    const text = `DELETE FROM ${tableName}\nWHERE ${whereClause}\nRETURNING ${returningClause}`;
+    return { text, values: [...whereParams] };
+}

package/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * graphile-bulk-mutations
+ *
+ * A PostGraphile v5 plugin for bulk insert, upsert, update, and delete
+ * mutations with ON CONFLICT handling.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * Tables must opt in via smart tags:
+ * ```sql
+ * COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ * COMMENT ON TABLE orders IS E'@behavior +bulkInsert +bulkUpdate +bulkDelete';
+ * ```
+ */
+import './augmentations';
+export { BulkMutationPreset } from './preset';
+export { BulkDeletePlugin, BulkInflectionPlugin, BulkInsertPlugin, BulkRelationalPlugin, BulkTypesPlugin, BulkUpdatePlugin, BulkUpsertPlugin } from './plugins';
+export type { BulkMutationOptions, BulkNamingStrategy } from './types';
+export { PG_MAX_PARAMS } from './types';
+export type { ColumnSpec, InsertBatch } from './utils';
+export { buildBulkDeleteSQL, buildBulkInsertSQL, buildBulkUpdateSQL } from './utils';

package/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * graphile-bulk-mutations
+ *
+ * A PostGraphile v5 plugin for bulk insert, upsert, update, and delete
+ * mutations with ON CONFLICT handling.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * Tables must opt in via smart tags:
+ * ```sql
+ * COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ * COMMENT ON TABLE orders IS E'@behavior +bulkInsert +bulkUpdate +bulkDelete';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBulkUpdateSQL = exports.buildBulkInsertSQL = exports.buildBulkDeleteSQL = exports.PG_MAX_PARAMS = exports.BulkUpsertPlugin = exports.BulkUpdatePlugin = exports.BulkTypesPlugin = exports.BulkRelationalPlugin = exports.BulkInsertPlugin = exports.BulkInflectionPlugin = exports.BulkDeletePlugin = exports.BulkMutationPreset = void 0;
+require("./augmentations");
+var preset_1 = require("./preset");
+Object.defineProperty(exports, "BulkMutationPreset", { enumerable: true, get: function () { return preset_1.BulkMutationPreset; } });
+// Re-export all plugins for granular use
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "BulkDeletePlugin", { enumerable: true, get: function () { return plugins_1.BulkDeletePlugin; } });
+Object.defineProperty(exports, "BulkInflectionPlugin", { enumerable: true, get: function () { return plugins_1.BulkInflectionPlugin; } });
+Object.defineProperty(exports, "BulkInsertPlugin", { enumerable: true, get: function () { return plugins_1.BulkInsertPlugin; } });
+Object.defineProperty(exports, "BulkRelationalPlugin", { enumerable: true, get: function () { return plugins_1.BulkRelationalPlugin; } });
+Object.defineProperty(exports, "BulkTypesPlugin", { enumerable: true, get: function () { return plugins_1.BulkTypesPlugin; } });
+Object.defineProperty(exports, "BulkUpdatePlugin", { enumerable: true, get: function () { return plugins_1.BulkUpdatePlugin; } });
+Object.defineProperty(exports, "BulkUpsertPlugin", { enumerable: true, get: function () { return plugins_1.BulkUpsertPlugin; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "PG_MAX_PARAMS", { enumerable: true, get: function () { return types_1.PG_MAX_PARAMS; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "buildBulkDeleteSQL", { enumerable: true, get: function () { return utils_1.buildBulkDeleteSQL; } });
+Object.defineProperty(exports, "buildBulkInsertSQL", { enumerable: true, get: function () { return utils_1.buildBulkInsertSQL; } });
+Object.defineProperty(exports, "buildBulkUpdateSQL", { enumerable: true, get: function () { return utils_1.buildBulkUpdateSQL; } });

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "graphile-bulk-mutations",
+  "version": "0.2.0",
+  "description": "PostGraphile v5 plugin for bulk insert, upsert, update, and delete mutations with ON CONFLICT handling",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "graphql",
+    "bulk",
+    "mutations",
+    "upsert",
+    "on-conflict",
+    "v5"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "graphile-test": "^4.14.1",
+    "makage": "^0.3.0",
+    "pgsql-test": "^4.13.1"
+  },
+  "peerDependencies": {
+    "@dataplan/pg": "1.0.0",
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphql": "16.13.0",
+    "pg-sql2": "5.0.0",
+    "postgraphile": "5.0.0"
+  },
+  "gitHead": "a8badcda8c3aa551194622b866fc61d4ab3e4eda"
+}

package/plugins/BulkDeletePlugin.d.ts

@@ -0,0 +1,13 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkDeletePlugin
+ *
+ * Registers `bulkDeleteX` mutation fields for each resource with the
+ * `bulkDelete` behavior. Uses DELETE ... WHERE with conditions from
+ * graphile-connection-filter (or PostGraphile's built-in condition type).
+ *
+ * Uses `RETURNING <pk_columns>` (not `RETURNING *`) + follow-up SELECT
+ * to respect column-level SELECT grants.
+ */
+export declare const BulkDeletePlugin: GraphileConfig.Plugin;

package/plugins/BulkDeletePlugin.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkDeletePlugin = void 0;
+require("../augmentations");
+const pg_1 = require("@dataplan/pg");
+const version = '0.1.0';
+/**
+ * BulkDeletePlugin
+ *
+ * Registers `bulkDeleteX` mutation fields for each resource with the
+ * `bulkDelete` behavior. Uses DELETE ... WHERE with conditions from
+ * graphile-connection-filter (or PostGraphile's built-in condition type).
+ *
+ * Uses `RETURNING <pk_columns>` (not `RETURNING *`) + follow-up SELECT
+ * to respect column-level SELECT grants.
+ */
+exports.BulkDeletePlugin = {
+    name: 'BulkDeletePlugin',
+    version,
+    description: 'Adds bulk delete (bulkDeleteX) mutations',
+    after: ['BulkTypesPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields(fields, build, context) {
+                const { scope: { isRootMutation } } = context;
+                if (!isRootMutation)
+                    return fields;
+                const { inflection, sql, graphql: { GraphQLNonNull }, options: { bulkDelete: enableDelete = true, bulkRequireWhere = true } } = build;
+                if (!enableDelete)
+                    return fields;
+                const pgRegistry = build.input.pgRegistry;
+                for (const [resourceName, resource] of Object.entries(pgRegistry.pgResources)) {
+                    if (resource.parameters)
+                        continue;
+                    if (!resource.codec.attributes)
+                        continue;
+                    if (resource.codec.polymorphism)
+                        continue;
+                    if (resource.codec.isAnonymous)
+                        continue;
+                    if (!resource.uniques?.length)
+                        continue;
+                    if (!build.behavior.pgResourceMatches(resource, 'bulkDelete'))
+                        continue;
+                    const typeName = inflection.tableType(resource.codec);
+                    const fieldName = inflection.bulkDeleteField(resourceName);
+                    const inputTypeName = inflection.bulkDeleteInputType(typeName);
+                    const payloadTypeName = inflection.bulkDeletePayloadType(typeName);
+                    const inputType = build.getTypeByName(inputTypeName);
+                    const payloadType = build.getTypeByName(payloadTypeName);
+                    if (!inputType || !payloadType)
+                        continue;
+                    const fieldToAttr = {};
+                    const attrToSqlType = {};
+                    for (const [attrName, attr] of Object.entries(resource.codec.attributes)) {
+                        const gqlFieldName = inflection.attribute({
+                            attributeName: attrName,
+                            codec: resource.codec
+                        });
+                        fieldToAttr[gqlFieldName] = attrName;
+                        attrToSqlType[attrName] = sql.compile(attr.codec.sqlType).text;
+                    }
+                    // Extract primary key columns for RETURNING clause
+                    const primaryUnique = resource.uniques.find((u) => u.isPrimary) ?? resource.uniques[0];
+                    const pkColumns = primaryUnique.attributes;
+                    const pkReturning = pkColumns.map((c) => `"${c}"`).join(', ');
+                    const compiledFrom = sql.compile(resource.from).text;
+                    // Capture for plan closure
+                    const executor = resource.executor;
+                    const requireWhere = bulkRequireWhere;
+                    fields = build.extend(fields, {
+                        [fieldName]: context.fieldWithHooks({ fieldName }, {
+                            description: `Bulk delete ${typeName} rows matching the given condition.`,
+                            type: payloadType,
+                            args: {
+                                input: {
+                                    type: new GraphQLNonNull(inputType)
+                                }
+                            },
+                            plan(_$root, args) {
+                                const $input = args.getRaw('input');
+                                const $result = (0, pg_1.sideEffectWithPgClient)(executor, $input, async (pgClient, input) => {
+                                    if (requireWhere && (!input.where || Object.keys(input.where).length === 0)) {
+                                        throw new Error('Bulk delete requires a non-empty where condition. Set bulkRequireWhere: false to allow unrestricted deletes.');
+                                    }
+                                    // Build WHERE clause from condition
+                                    // Supports both simple equality (Condition type: { name: "X" })
+                                    // and operator-based (Filter type: { name: { equalTo: "X" } })
+                                    const values = [];
+                                    const whereClauses = [];
+                                    if (input.where) {
+                                        for (const [key, spec] of Object.entries(input.where)) {
+                                            const attrName = fieldToAttr[key];
+                                            if (!attrName)
+                                                continue;
+                                            const sqlType = attrToSqlType[attrName];
+                                            if (spec === null) {
+                                                whereClauses.push(`"${attrName}" IS NULL`);
+                                            }
+                                            else if (spec !== undefined && typeof spec !== 'object') {
+                                                // Simple equality (Condition type)
+                                                values.push(spec);
+                                                whereClauses.push(`"${attrName}" = $${values.length}::${sqlType}`);
+                                            }
+                                            else if (spec && typeof spec === 'object') {
+                                                // Operator-based (Filter type)
+                                                for (const [op, val] of Object.entries(spec)) {
+                                                    values.push(val);
+                                                    const paramRef = `$${values.length}::${sqlType}`;
+                                                    switch (op) {
+                                                        case 'equalTo':
+                                                            whereClauses.push(`"${attrName}" = ${paramRef}`);
+                                                            break;
+                                                        case 'notEqualTo':
+                                                            whereClauses.push(`"${attrName}" != ${paramRef}`);
+                                                            break;
+                                                        case 'greaterThan':
+                                                            whereClauses.push(`"${attrName}" > ${paramRef}`);
+                                                            break;
+                                                        case 'greaterThanOrEqualTo':
+                                                            whereClauses.push(`"${attrName}" >= ${paramRef}`);
+                                                            break;
+                                                        case 'lessThan':
+                                                            whereClauses.push(`"${attrName}" < ${paramRef}`);
+                                                            break;
+                                                        case 'lessThanOrEqualTo':
+                                                            whereClauses.push(`"${attrName}" <= ${paramRef}`);
+                                                            break;
+                                                        case 'in':
+                                                            if (Array.isArray(val)) {
+                                                                const placeholders = val.map((v) => {
+                                                                    values.push(v);
+                                                                    return `$${values.length}::${sqlType}`;
+                                                                });
+                                                                values.pop();
+                                                                whereClauses.push(`"${attrName}" IN (${placeholders.join(', ')})`);
+                                                            }
+                                                            break;
+                                                        case 'isNull':
+                                                            values.pop();
+                                                            if (val) {
+                                                                whereClauses.push(`"${attrName}" IS NULL`);
+                                                            }
+                                                            else {
+                                                                whereClauses.push(`"${attrName}" IS NOT NULL`);
+                                                            }
+                                                            break;
+                                                        default:
+                                                            values.pop();
+                                                            break;
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                    if (whereClauses.length === 0 && requireWhere) {
+                                        throw new Error('Bulk delete: no valid where conditions resolved. At least one condition is required.');
+                                    }
+                                    const whereStr = whereClauses.length > 0
+                                        ? whereClauses.join(' AND ')
+                                        : 'TRUE';
+                                    // Use RETURNING <pk_columns> instead of RETURNING *
+                                    // For delete, we capture PKs before rows are gone
+                                    const text = `DELETE FROM ${compiledFrom}\nWHERE ${whereStr}\nRETURNING ${pkReturning}`;
+                                    const mutationResult = await pgClient.query(text, values);
+                                    const affectedCount = mutationResult.rowCount ?? 0;
+                                    // For delete, rows no longer exist so we can't do a
+                                    // follow-up SELECT. Return the PK values directly.
+                                    const returning = mutationResult.rows || [];
+                                    return {
+                                        affectedCount,
+                                        returning
+                                    };
+                                });
+                                return $result;
+                            }
+                        })
+                    }, `Adding bulk delete field for ${typeName}`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/plugins/BulkInflectionPlugin.d.ts

@@ -0,0 +1,9 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkInflectionPlugin
+ *
+ * Adds inflection methods for naming bulk mutation types, fields, and enums.
+ * Naming is configurable via the `bulkNaming` schema option.
+ */
+export declare const BulkInflectionPlugin: GraphileConfig.Plugin;