graphile-bulk-mutations 0.2.0

package/esm/plugins/BulkDeletePlugin.js

@@ -0,0 +1,181 @@
+import '../augmentations';
+import { sideEffectWithPgClient } from '@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.
+ */
+export const 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 = 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/esm/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;

package/esm/plugins/BulkInflectionPlugin.js

@@ -0,0 +1,103 @@
+import '../augmentations';
+/**
+ * Builds a mutation field name based on the naming strategy.
+ *
+ * - 'bulk': bulkCreateUser
+ * - 'pluralized': createUsers
+ * - 'many': createManyUsers
+ */
+function buildFieldName(inflection, verb, resourceName, naming) {
+    const typeName = inflection.upperCamelCase(resourceName);
+    switch (naming) {
+        case 'pluralized':
+            return inflection.camelCase(`${verb}_${inflection.pluralize(resourceName)}`);
+        case 'many':
+            return inflection.camelCase(`${verb}_many_${inflection.pluralize(resourceName)}`);
+        case 'bulk':
+        default:
+            return inflection.camelCase(`bulk_${verb}_${typeName}`);
+    }
+}
+/**
+ * BulkInflectionPlugin
+ *
+ * Adds inflection methods for naming bulk mutation types, fields, and enums.
+ * Naming is configurable via the `bulkNaming` schema option.
+ */
+export const BulkInflectionPlugin = {
+    name: 'BulkInflectionPlugin',
+    version: '0.1.0',
+    description: 'Adds inflection methods for bulk mutation type naming',
+    inflection: {
+        add: {
+            // Mutation field names — read naming from preset schema options
+            bulkInsertField(_preset, resourceName) {
+                const naming = (_preset?.schema?.bulkNaming ?? 'bulk');
+                return buildFieldName(this, 'create', resourceName, naming);
+            },
+            bulkUpsertField(_preset, resourceName) {
+                const naming = (_preset?.schema?.bulkNaming ?? 'bulk');
+                return buildFieldName(this, 'upsert', resourceName, naming);
+            },
+            bulkUpdateField(_preset, resourceName) {
+                const naming = (_preset?.schema?.bulkNaming ?? 'bulk');
+                return buildFieldName(this, 'update', resourceName, naming);
+            },
+            bulkDeleteField(_preset, resourceName) {
+                const naming = (_preset?.schema?.bulkNaming ?? 'bulk');
+                return buildFieldName(this, 'delete', resourceName, naming);
+            },
+            // Payload type names
+            bulkInsertPayloadType(_preset, typeName) {
+                return `BulkCreate${typeName}Payload`;
+            },
+            bulkUpsertPayloadType(_preset, typeName) {
+                return `BulkUpsert${typeName}Payload`;
+            },
+            bulkUpdatePayloadType(_preset, typeName) {
+                return `BulkUpdate${typeName}Payload`;
+            },
+            bulkDeletePayloadType(_preset, typeName) {
+                return `BulkDelete${typeName}Payload`;
+            },
+            // Input type names
+            bulkInsertInputType(_preset, typeName) {
+                return `BulkCreate${typeName}Input`;
+            },
+            bulkUpsertInputType(_preset, typeName) {
+                return `BulkUpsert${typeName}Input`;
+            },
+            bulkUpdateInputType(_preset, typeName) {
+                return `BulkUpdate${typeName}Input`;
+            },
+            bulkDeleteInputType(_preset, typeName) {
+                return `BulkDelete${typeName}Input`;
+            },
+            // Per-table enum types
+            uniqueConstraintEnumType(_preset, typeName) {
+                return `${typeName}UniqueConstraint`;
+            },
+            columnEnumType(_preset, typeName) {
+                return `${typeName}Column`;
+            },
+            // ON CONFLICT input types
+            bulkInsertOnConflictInputType(_preset, typeName) {
+                return `BulkCreate${typeName}OnConflictInput`;
+            },
+            bulkUpsertOnConflictInputType(_preset, typeName) {
+                return `BulkUpsert${typeName}OnConflictInput`;
+            },
+            // Values item types
+            bulkInsertValuesItemType(_preset, typeName) {
+                return `${typeName}BulkCreateItem`;
+            },
+            bulkUpsertValuesItemType(_preset, typeName) {
+                return `${typeName}BulkUpsertItem`;
+            },
+            // Relational nested input type names
+            bulkNestedValuesItemType(_preset, parentTypeName, childTypeName) {
+                return `${childTypeName}BulkNestedIn${parentTypeName}Input`;
+            }
+        }
+    }
+};

package/esm/plugins/BulkInsertPlugin.d.ts

@@ -0,0 +1,21 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkInsertPlugin
+ *
+ * Registers `bulkCreateX` mutation fields on the root mutation type for
+ * each resource that has the `bulkInsert` behavior.
+ *
+ * Uses `sideEffectWithPgClient` for raw SQL execution. The mutation
+ * SQL uses `RETURNING <pk_columns>` (not `RETURNING *`) to respect
+ * column-level SELECT grants. A follow-up SELECT retrieves the full
+ * rows using only the returned PKs, ensuring the query runs through
+ * the normal grant-aware pipeline.
+ *
+ * When `bulkRelational` is enabled, nested child records are detected
+ * in the input and inserted in a layered fashion: parent rows first,
+ * then child rows with FK values auto-populated from the parent PKs.
+ *
+ * Pattern from: https://github.com/pyramation/graphile-column-privileges-mutations
+ */
+export declare const BulkInsertPlugin: GraphileConfig.Plugin;

package/esm/plugins/BulkInsertPlugin.js

@@ -0,0 +1,214 @@
+import '../augmentations';
+import { sideEffectWithPgClient } from '@dataplan/pg';
+import { discoverNestedRelations } from '../utils/relations';
+import { buildBulkInsertSQL } from '../utils/sql-builder';
+const version = '0.1.0';
+/**
+ * BulkInsertPlugin
+ *
+ * Registers `bulkCreateX` mutation fields on the root mutation type for
+ * each resource that has the `bulkInsert` behavior.
+ *
+ * Uses `sideEffectWithPgClient` for raw SQL execution. The mutation
+ * SQL uses `RETURNING <pk_columns>` (not `RETURNING *`) to respect
+ * column-level SELECT grants. A follow-up SELECT retrieves the full
+ * rows using only the returned PKs, ensuring the query runs through
+ * the normal grant-aware pipeline.
+ *
+ * When `bulkRelational` is enabled, nested child records are detected
+ * in the input and inserted in a layered fashion: parent rows first,
+ * then child rows with FK values auto-populated from the parent PKs.
+ *
+ * Pattern from: https://github.com/pyramation/graphile-column-privileges-mutations
+ */
+export const BulkInsertPlugin = {
+    name: 'BulkInsertPlugin',
+    version,
+    description: 'Adds bulk insert (bulkCreateX) mutations',
+    after: ['BulkTypesPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields(fields, build, context) {
+                const { scope: { isRootMutation } } = context;
+                if (!isRootMutation)
+                    return fields;
+                const { inflection, sql, graphql: { GraphQLNonNull }, options: { bulkInsert: enableInsert = true, bulkRelational: enableRelational = false, bulkMaxRows = 1000 } } = build;
+                if (!enableInsert)
+                    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, 'bulkInsert'))
+                        continue;
+                    const typeName = inflection.tableType(resource.codec);
+                    const fieldName = inflection.bulkInsertField(resourceName);
+                    const inputTypeName = inflection.bulkInsertInputType(typeName);
+                    const payloadTypeName = inflection.bulkInsertPayloadType(typeName);
+                    const inputType = build.getTypeByName(inputTypeName);
+                    const payloadType = build.getTypeByName(payloadTypeName);
+                    if (!inputType || !payloadType)
+                        continue;
+                    // Pre-compute column specs for SQL generation
+                    const columnSpecs = [];
+                    const fieldToAttr = {};
+                    for (const [attrName, attr] of Object.entries(resource.codec.attributes)) {
+                        if (attr.extensions?.isInsertable === false)
+                            continue;
+                        const gqlFieldName = inflection.attribute({
+                            attributeName: attrName,
+                            codec: resource.codec
+                        });
+                        fieldToAttr[gqlFieldName] = attrName;
+                        columnSpecs.push({
+                            name: attrName,
+                            sqlType: 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 compiledFrom = sql.compile(resource.from).text;
+                    // Discover nested relations at schema build time
+                    const nestedRelations = enableRelational
+                        ? discoverNestedRelations(resource, pgRegistry, inflection, sql)
+                        : [];
+                    const nestedFieldNames = new Set(nestedRelations.map((r) => r.fieldName));
+                    // Capture executor for plan closure
+                    const executor = resource.executor;
+                    const maxRows = bulkMaxRows;
+                    fields = build.extend(fields, {
+                        [fieldName]: context.fieldWithHooks({ fieldName }, {
+                            description: `Bulk insert rows into ${typeName}.`,
+                            type: payloadType,
+                            args: {
+                                input: {
+                                    type: new GraphQLNonNull(inputType)
+                                }
+                            },
+                            plan(_$root, args) {
+                                const $input = args.getRaw('input');
+                                const $result = sideEffectWithPgClient(executor, $input, async (pgClient, input) => {
+                                    const values = input.values;
+                                    if (!values || !Array.isArray(values) || values.length === 0) {
+                                        return { affectedCount: 0, returning: [] };
+                                    }
+                                    if (values.length > maxRows) {
+                                        throw new Error(`Bulk insert exceeds maximum of ${maxRows} rows (got ${values.length})`);
+                                    }
+                                    // Check for nested data
+                                    const hasNestedData = nestedRelations.length > 0 &&
+                                        values.some((row) => nestedRelations.some((rel) => Array.isArray(row[rel.fieldName]) &&
+                                            row[rel.fieldName].length > 0));
+                                    // Validate: ON CONFLICT not allowed with nested inserts
+                                    if (hasNestedData && input.onConflict) {
+                                        throw new Error('ON CONFLICT cannot be used with nested/relational inserts. ' +
+                                            'Remove the onConflict option or remove nested records from values.');
+                                    }
+                                    // Map GraphQL field names to SQL column names,
+                                    // separating parent data from nested data
+                                    const rows = values.map((row) => {
+                                        const mapped = {};
+                                        for (const [key, val] of Object.entries(row)) {
+                                            if (nestedFieldNames.has(key))
+                                                continue;
+                                            const attrName = fieldToAttr[key];
+                                            if (attrName) {
+                                                mapped[attrName] = val;
+                                            }
+                                        }
+                                        return mapped;
+                                    });
+                                    // Build ON CONFLICT clause
+                                    let onConflict;
+                                    if (input.onConflict) {
+                                        const conflictColumns = input.onConflict.constraint
+                                            ? input.onConflict.constraint.split(',')
+                                            : undefined;
+                                        onConflict = {
+                                            conflictColumns,
+                                            action: input.onConflict.action
+                                        };
+                                    }
+                                    const batches = buildBulkInsertSQL(compiledFrom, columnSpecs, rows, pkColumns, onConflict);
+                                    let totalAffected = 0;
+                                    const allPkRows = [];
+                                    for (const batch of batches) {
+                                        const result = await pgClient.query(batch.text, batch.values);
+                                        totalAffected += result.rowCount ?? 0;
+                                        if (result.rows) {
+                                            allPkRows.push(...result.rows);
+                                        }
+                                    }
+                                    // Layered nested inserts: insert child rows with FK
+                                    // values auto-populated from parent PKs
+                                    if (hasNestedData) {
+                                        for (let i = 0; i < values.length && i < allPkRows.length; i++) {
+                                            const row = values[i];
+                                            const parentPk = allPkRows[i];
+                                            for (const rel of nestedRelations) {
+                                                const childInputRows = row[rel.fieldName];
+                                                if (!childInputRows?.length)
+                                                    continue;
+                                                // Map child GraphQL fields to SQL columns
+                                                // and inject FK values from parent PK
+                                                const childRows = childInputRows.map((childRow) => {
+                                                    const mapped = {};
+                                                    for (const [key, val] of Object.entries(childRow)) {
+                                                        const attrName = rel.childFieldToAttr[key];
+                                                        if (attrName) {
+                                                            mapped[attrName] = val;
+                                                        }
+                                                    }
+                                                    // Fill FK columns from parent PK
+                                                    for (let j = 0; j < rel.localAttributes.length; j++) {
+                                                        mapped[rel.remoteAttributes[j]] =
+                                                            parentPk[rel.localAttributes[j]];
+                                                    }
+                                                    return mapped;
+                                                });
+                                                const childBatches = buildBulkInsertSQL(rel.childCompiledFrom, rel.childColumnSpecs, childRows, rel.childPkColumns);
+                                                for (const batch of childBatches) {
+                                                    const result = await pgClient.query(batch.text, batch.values);
+                                                    totalAffected += result.rowCount ?? 0;
+                                                }
+                                            }
+                                        }
+                                    }
+                                    // Follow-up SELECT using PKs to respect column-level grants
+                                    let returning = [];
+                                    if (allPkRows.length > 0) {
+                                        const pkConditions = allPkRows.map((pkRow, rowIdx) => {
+                                            return pkColumns.map((col, colIdx) => {
+                                                const paramIdx = rowIdx * pkColumns.length + colIdx + 1;
+                                                return `"${col}" = $${paramIdx}`;
+                                            }).join(' AND ');
+                                        });
+                                        const whereClause = pkConditions.map((c) => `(${c})`).join(' OR ');
+                                        const selectParams = allPkRows.flatMap((pkRow) => pkColumns.map((col) => pkRow[col]));
+                                        const selectResult = await pgClient.query(`SELECT * FROM ${compiledFrom} WHERE ${whereClause}`, selectParams);
+                                        returning = selectResult.rows || [];
+                                    }
+                                    return {
+                                        affectedCount: totalAffected,
+                                        returning
+                                    };
+                                });
+                                return $result;
+                            }
+                        })
+                    }, `Adding bulk insert field for ${typeName}`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/esm/plugins/BulkRelationalPlugin.d.ts

@@ -0,0 +1,31 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkRelationalPlugin
+ *
+ * Adds relational/nested insert support to bulk mutations. When enabled
+ * via `bulkRelational: true`, parent values item input types gain optional
+ * fields for each "has many" relation, allowing creation of parent and
+ * child rows in a single mutation.
+ *
+ * Example:
+ *   mutation {
+ *     bulkCreateCategories(input: {
+ *       values: [{
+ *         name: "Electronics"
+ *         products: [
+ *           { name: "Laptop", price: "999.99" }
+ *         ]
+ *       }]
+ *     }) { affectedCount }
+ *   }
+ *
+ * The FK column on the child table (e.g. category_id) is automatically
+ * populated from the parent's returned primary key. Nested input types
+ * exclude FK columns so the user does not need to provide them.
+ *
+ * Limitations:
+ * - ON CONFLICT cannot be used with nested inserts (throws an error)
+ * - Only one level of nesting is supported in the initial implementation
+ */
+export declare const BulkRelationalPlugin: GraphileConfig.Plugin;