graphile-bulk-mutations 0.2.0

package/plugins/BulkInflectionPlugin.js

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

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkInsertPlugin = void 0;
+require("../augmentations");
+const pg_1 = require("@dataplan/pg");
+const relations_1 = require("../utils/relations");
+const sql_builder_1 = require("../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
+ */
+exports.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
+                        ? (0, relations_1.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 = (0, pg_1.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 = (0, sql_builder_1.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 = (0, sql_builder_1.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/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;

package/plugins/BulkRelationalPlugin.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkRelationalPlugin = void 0;
+require("../augmentations");
+const relations_1 = require("../utils/relations");
+const version = '0.1.0';
+/**
+ * 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
+ */
+exports.BulkRelationalPlugin = {
+    name: 'BulkRelationalPlugin',
+    version,
+    description: 'Adds relational/nested insert support to bulk mutations',
+    after: ['BulkTypesPlugin', 'BulkInsertPlugin'],
+    schema: {
+        hooks: {
+            init(_, build) {
+                const { inflection, sql, options: { bulkRelational: enableRelational = false } } = build;
+                if (!enableRelational)
+                    return _;
+                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 parentTypeName = inflection.tableType(resource.codec);
+                    const nestedRelations = (0, relations_1.discoverNestedRelations)(resource, pgRegistry, inflection, sql);
+                    for (const rel of nestedRelations) {
+                        const childTypeName = inflection.tableType(rel.remoteResource.codec);
+                        const nestedInputTypeName = inflection.bulkNestedValuesItemType(parentTypeName, childTypeName);
+                        // FK columns to exclude from nested input type
+                        const fkAttrSet = new Set(rel.remoteAttributes);
+                        build.registerInputObjectType(nestedInputTypeName, { isBulkRelationalNestedInput: true }, () => ({
+                            description: `A row to nest-create for ${childTypeName} when bulk creating ${parentTypeName}. FK columns are auto-populated from the parent.`,
+                            fields: () => {
+                                const result = {};
+                                for (const [attrName, attr] of Object.entries(rel.remoteResource.codec.attributes)) {
+                                    if (attr.extensions?.isInsertable === false)
+                                        continue;
+                                    // Exclude FK columns — they are auto-filled from parent PK
+                                    if (fkAttrSet.has(attrName))
+                                        continue;
+                                    const fieldName = inflection.attribute({
+                                        attributeName: attrName,
+                                        codec: rel.remoteResource.codec
+                                    });
+                                    const inputType = build.getGraphQLTypeByPgCodec(attr.codec, 'input');
+                                    if (!inputType)
+                                        continue;
+                                    const isRequired = !!attr.notNull && !attr.hasDefault;
+                                    result[fieldName] = {
+                                        description: `Value for ${attrName}`,
+                                        type: isRequired
+                                            ? new build.graphql.GraphQLNonNull(inputType)
+                                            : inputType
+                                    };
+                                }
+                                return result;
+                            }
+                        }), `Nested input for ${childTypeName} in ${parentTypeName}`);
+                    }
+                }
+                return _;
+            },
+            // Add nested relation fields to existing values item input types
+            GraphQLInputObjectType_fields(fields, build, context) {
+                const { scope: { isBulkMutationValuesItem, bulkMutationResourceName } } = context;
+                if (!isBulkMutationValuesItem || !bulkMutationResourceName)
+                    return fields;
+                const { inflection, sql, options: { bulkRelational: enableRelational = false } } = build;
+                if (!enableRelational)
+                    return fields;
+                const pgRegistry = build.input.pgRegistry;
+                const resource = pgRegistry.pgResources[bulkMutationResourceName];
+                if (!resource)
+                    return fields;
+                const parentTypeName = inflection.tableType(resource.codec);
+                const nestedRelations = (0, relations_1.discoverNestedRelations)(resource, pgRegistry, inflection, sql);
+                for (const rel of nestedRelations) {
+                    const childTypeName = inflection.tableType(rel.remoteResource.codec);
+                    const nestedInputTypeName = inflection.bulkNestedValuesItemType(parentTypeName, childTypeName);
+                    const nestedInputType = build.getTypeByName(nestedInputTypeName);
+                    if (!nestedInputType)
+                        continue;
+                    fields = build.extend(fields, {
+                        [rel.fieldName]: {
+                            description: `Nested ${childTypeName} rows to create for this ${parentTypeName}.`,
+                            type: new build.graphql.GraphQLList(new build.graphql.GraphQLNonNull(nestedInputType))
+                        }
+                    }, `Adding nested field ${rel.fieldName} to ${parentTypeName} values item`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/plugins/BulkTypesPlugin.d.ts

@@ -0,0 +1,18 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkTypesPlugin
+ *
+ * Registers all shared types for bulk mutations:
+ * 1. ConflictAction enum (IGNORE)
+ * 2. Per-table unique constraint enums (e.g. UserUniqueConstraint)
+ * 3. Per-table column enums (e.g. UserColumn)
+ * 4. Per-table ON CONFLICT input types
+ * 5. Per-table values item input types
+ * 6. Per-table input types (wrapping values + onConflict)
+ * 7. Per-table payload types (affectedCount + returning)
+ *
+ * Behavior: OFF by default. Tables must opt in via smart tags:
+ *   @behavior +bulkInsert +bulkUpsert +bulkUpdate +bulkDelete
+ */
+export declare const BulkTypesPlugin: GraphileConfig.Plugin;