graphile-bulk-mutations 0.2.0

package/esm/plugins/BulkUpdatePlugin.js

@@ -0,0 +1,211 @@
+import '../augmentations';
+import { sideEffectWithPgClient } from '@dataplan/pg';
+const version = '0.1.0';
+/**
+ * BulkUpdatePlugin
+ *
+ * Registers `bulkUpdateX` mutation fields for each resource with the
+ * `bulkUpdate` behavior. Uses UPDATE ... SET ... 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 BulkUpdatePlugin = {
+    name: 'BulkUpdatePlugin',
+    version,
+    description: 'Adds bulk update (bulkUpdateX) mutations',
+    after: ['BulkTypesPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields(fields, build, context) {
+                const { scope: { isRootMutation } } = context;
+                if (!isRootMutation)
+                    return fields;
+                const { inflection, sql, graphql: { GraphQLNonNull }, options: { bulkUpdate: enableUpdate = true, bulkRequireWhere = true } } = build;
+                if (!enableUpdate)
+                    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, 'bulkUpdate'))
+                        continue;
+                    const typeName = inflection.tableType(resource.codec);
+                    const fieldName = inflection.bulkUpdateField(resourceName);
+                    const inputTypeName = inflection.bulkUpdateInputType(typeName);
+                    const payloadTypeName = inflection.bulkUpdatePayloadType(typeName);
+                    const inputType = build.getTypeByName(inputTypeName);
+                    const payloadType = build.getTypeByName(payloadTypeName);
+                    if (!inputType || !payloadType)
+                        continue;
+                    // Build field-to-attribute mapping for patch resolution
+                    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 update ${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 update requires a non-empty where condition. Set bulkRequireWhere: false to allow unrestricted updates.');
+                                    }
+                                    if (!input.patch || Object.keys(input.patch).length === 0) {
+                                        throw new Error('Bulk update requires a non-empty patch.');
+                                    }
+                                    // Build SET clause from patch
+                                    const setClauses = [];
+                                    const values = [];
+                                    for (const [key, val] of Object.entries(input.patch)) {
+                                        if (val === undefined)
+                                            continue;
+                                        const attrName = fieldToAttr[key];
+                                        if (!attrName)
+                                            continue;
+                                        const sqlType = attrToSqlType[attrName];
+                                        values.push(val);
+                                        setClauses.push(`"${attrName}" = $${values.length}::${sqlType}`);
+                                    }
+                                    if (setClauses.length === 0) {
+                                        return { affectedCount: 0, returning: [] };
+                                    }
+                                    // Build WHERE clause from condition
+                                    // Supports both simple equality (Condition type: { name: "X" })
+                                    // and operator-based (Filter type: { name: { equalTo: "X" } })
+                                    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 update: 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 *
+                                    const text = `UPDATE ${compiledFrom}\nSET ${setClauses.join(', ')}\nWHERE ${whereStr}\nRETURNING ${pkReturning}`;
+                                    const mutationResult = await pgClient.query(text, values);
+                                    const affectedCount = mutationResult.rowCount ?? 0;
+                                    // Follow-up SELECT using PKs to respect column-level grants
+                                    let returning = [];
+                                    if (mutationResult.rows && mutationResult.rows.length > 0) {
+                                        const pkRows = mutationResult.rows;
+                                        const pkConditions = pkRows.map((pkRow, rowIdx) => {
+                                            return pkColumns.map((col, colIdx) => {
+                                                const paramIdx = rowIdx * pkColumns.length + colIdx + 1;
+                                                return `"${col}" = $${paramIdx}`;
+                                            }).join(' AND ');
+                                        });
+                                        const selectWhere = pkConditions.map((c) => `(${c})`).join(' OR ');
+                                        const selectParams = pkRows.flatMap((pkRow) => pkColumns.map((col) => pkRow[col]));
+                                        const selectResult = await pgClient.query(`SELECT * FROM ${compiledFrom} WHERE ${selectWhere}`, selectParams);
+                                        returning = selectResult.rows || [];
+                                    }
+                                    return {
+                                        affectedCount,
+                                        returning
+                                    };
+                                });
+                                return $result;
+                            }
+                        })
+                    }, `Adding bulk update field for ${typeName}`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/esm/plugins/BulkUpsertPlugin.d.ts

@@ -0,0 +1,12 @@
+import '../augmentations';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * BulkUpsertPlugin
+ *
+ * Registers `bulkUpsertX` mutation fields for each resource with the
+ * `bulkUpsert` behavior. Uses INSERT ... ON CONFLICT DO UPDATE SET.
+ *
+ * Uses `RETURNING <pk_columns>` (not `RETURNING *`) + follow-up SELECT
+ * to respect column-level SELECT grants.
+ */
+export declare const BulkUpsertPlugin: GraphileConfig.Plugin;

package/esm/plugins/BulkUpsertPlugin.js

@@ -0,0 +1,165 @@
+import '../augmentations';
+import { sideEffectWithPgClient } from '@dataplan/pg';
+import { buildBulkInsertSQL } from '../utils/sql-builder';
+const version = '0.1.0';
+/**
+ * BulkUpsertPlugin
+ *
+ * Registers `bulkUpsertX` mutation fields for each resource with the
+ * `bulkUpsert` behavior. Uses INSERT ... ON CONFLICT DO UPDATE SET.
+ *
+ * Uses `RETURNING <pk_columns>` (not `RETURNING *`) + follow-up SELECT
+ * to respect column-level SELECT grants.
+ */
+export const BulkUpsertPlugin = {
+    name: 'BulkUpsertPlugin',
+    version,
+    description: 'Adds bulk upsert (bulkUpsertX) mutations',
+    after: ['BulkTypesPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields(fields, build, context) {
+                const { scope: { isRootMutation } } = context;
+                if (!isRootMutation)
+                    return fields;
+                const { inflection, sql, graphql: { GraphQLNonNull }, options: { bulkUpsert: enableUpsert = true, bulkMaxRows = 1000 } } = build;
+                if (!enableUpsert)
+                    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, 'bulkUpsert'))
+                        continue;
+                    const typeName = inflection.tableType(resource.codec);
+                    const fieldName = inflection.bulkUpsertField(resourceName);
+                    const inputTypeName = inflection.bulkUpsertInputType(typeName);
+                    const payloadTypeName = inflection.bulkUpsertPayloadType(typeName);
+                    const inputType = build.getTypeByName(inputTypeName);
+                    const payloadType = build.getTypeByName(payloadTypeName);
+                    if (!inputType || !payloadType)
+                        continue;
+                    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
+                        });
+                    }
+                    // Collect unique constraint attributes for excluding from updateColumns
+                    const uniqueAttrs = new Set();
+                    for (const unique of resource.uniques) {
+                        for (const attr of unique.attributes) {
+                            uniqueAttrs.add(attr);
+                        }
+                    }
+                    // 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;
+                    // Capture for plan closure
+                    const executor = resource.executor;
+                    const maxRows = bulkMaxRows;
+                    fields = build.extend(fields, {
+                        [fieldName]: context.fieldWithHooks({ fieldName }, {
+                            description: `Bulk upsert rows into ${typeName}. Requires an ON CONFLICT constraint.`,
+                            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 upsert exceeds maximum of ${maxRows} rows (got ${values.length})`);
+                                    }
+                                    if (!input.onConflict?.constraint) {
+                                        throw new Error('bulkUpsert requires onConflict.constraint');
+                                    }
+                                    const rows = values.map((row) => {
+                                        const mapped = {};
+                                        for (const [key, val] of Object.entries(row)) {
+                                            const attrName = fieldToAttr[key];
+                                            if (attrName) {
+                                                mapped[attrName] = val;
+                                            }
+                                        }
+                                        return mapped;
+                                    });
+                                    // Determine which columns to update
+                                    let updateColumns;
+                                    if (input.onConflict.updateColumns &&
+                                        input.onConflict.updateColumns.length > 0) {
+                                        updateColumns = input.onConflict.updateColumns;
+                                    }
+                                    else {
+                                        // Default: all non-key columns
+                                        updateColumns = columnSpecs
+                                            .map((c) => c.name)
+                                            .filter((n) => !uniqueAttrs.has(n));
+                                    }
+                                    const batches = buildBulkInsertSQL(compiledFrom, columnSpecs, rows, pkColumns, {
+                                        conflictColumns: input.onConflict.constraint.split(','),
+                                        action: 'UPDATE',
+                                        updateColumns
+                                    });
+                                    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);
+                                        }
+                                    }
+                                    // 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 upsert field for ${typeName}`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/esm/plugins/index.d.ts

@@ -0,0 +1,7 @@
+export { BulkDeletePlugin } from './BulkDeletePlugin';
+export { BulkInflectionPlugin } from './BulkInflectionPlugin';
+export { BulkInsertPlugin } from './BulkInsertPlugin';
+export { BulkRelationalPlugin } from './BulkRelationalPlugin';
+export { BulkTypesPlugin } from './BulkTypesPlugin';
+export { BulkUpdatePlugin } from './BulkUpdatePlugin';
+export { BulkUpsertPlugin } from './BulkUpsertPlugin';

package/esm/plugins/index.js

@@ -0,0 +1,7 @@
+export { BulkDeletePlugin } from './BulkDeletePlugin';
+export { BulkInflectionPlugin } from './BulkInflectionPlugin';
+export { BulkInsertPlugin } from './BulkInsertPlugin';
+export { BulkRelationalPlugin } from './BulkRelationalPlugin';
+export { BulkTypesPlugin } from './BulkTypesPlugin';
+export { BulkUpdatePlugin } from './BulkUpdatePlugin';
+export { BulkUpsertPlugin } from './BulkUpsertPlugin';

package/esm/preset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bulk Mutations Preset
+ *
+ * Provides a convenient preset factory for including bulk mutations
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *     // or with options:
+ *     BulkMutationPreset({
+ *       bulkNaming: 'pluralized',
+ *       bulkRelational: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import './augmentations';
+import type { GraphileConfig } from 'graphile-config';
+import type { BulkMutationOptions } from './types';
+/**
+ * Creates a preset that includes the bulk mutation plugins with the given options.
+ *
+ * Behavior is OFF by default for all tables. Tables must opt in via smart tags:
+ *   COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ *
+ * The `enable_bulk` database setting must also be true for the plugin to load.
+ */
+export declare function BulkMutationPreset(options?: BulkMutationOptions): GraphileConfig.Preset;
+export default BulkMutationPreset;

package/esm/preset.js

@@ -0,0 +1,74 @@
+/**
+ * Bulk Mutations Preset
+ *
+ * Provides a convenient preset factory for including bulk mutations
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *     // or with options:
+ *     BulkMutationPreset({
+ *       bulkNaming: 'pluralized',
+ *       bulkRelational: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import './augmentations';
+import { BulkDeletePlugin, BulkInflectionPlugin, BulkInsertPlugin, BulkRelationalPlugin, BulkTypesPlugin, BulkUpdatePlugin, BulkUpsertPlugin } from './plugins';
+/**
+ * Default schema options for bulk mutations.
+ */
+const defaultSchemaOptions = {
+    bulkNaming: 'bulk',
+    bulkInsert: true,
+    bulkUpsert: true,
+    bulkUpdate: true,
+    bulkDelete: true,
+    bulkRelational: false,
+    bulkReturning: true,
+    bulkMaxRows: 1000,
+    bulkMaxNestingDepth: 3,
+    bulkRequireWhere: true
+};
+/**
+ * Creates a preset that includes the bulk mutation plugins with the given options.
+ *
+ * Behavior is OFF by default for all tables. Tables must opt in via smart tags:
+ *   COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ *
+ * The `enable_bulk` database setting must also be true for the plugin to load.
+ */
+export function BulkMutationPreset(options = {}) {
+    const mergedOptions = { ...defaultSchemaOptions, ...options };
+    const plugins = [
+        BulkInflectionPlugin,
+        BulkTypesPlugin
+    ];
+    if (mergedOptions.bulkInsert) {
+        plugins.push(BulkInsertPlugin);
+    }
+    if (mergedOptions.bulkUpsert) {
+        plugins.push(BulkUpsertPlugin);
+    }
+    if (mergedOptions.bulkUpdate) {
+        plugins.push(BulkUpdatePlugin);
+    }
+    if (mergedOptions.bulkDelete) {
+        plugins.push(BulkDeletePlugin);
+    }
+    if (mergedOptions.bulkRelational) {
+        plugins.push(BulkRelationalPlugin);
+    }
+    return {
+        plugins,
+        schema: mergedOptions
+    };
+}
+export default BulkMutationPreset;

package/esm/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration options and shared types for graphile-bulk-mutations.
+ */
+/**
+ * Naming strategy for bulk mutation fields.
+ *
+ * - 'bulk': bulkCreateUser, bulkUpsertUser, bulkUpdateUser, bulkDeleteUser
+ * - 'pluralized': createUsers, upsertUsers, updateUsers, deleteUsers
+ * - 'many': createManyUsers, upsertManyUsers, updateManyUsers, deleteManyUsers
+ */
+export type BulkNamingStrategy = 'bulk' | 'pluralized' | 'many';
+/**
+ * Configuration options for the bulk mutations preset.
+ */
+export interface BulkMutationOptions {
+    /** Naming strategy for bulk mutation fields. Default: 'bulk' */
+    bulkNaming?: BulkNamingStrategy;
+    /** Enable bulk insert mutations. Default: true */
+    bulkInsert?: boolean;
+    /** Enable bulk upsert mutations. Default: true */
+    bulkUpsert?: boolean;
+    /** Enable bulk update mutations. Default: true */
+    bulkUpdate?: boolean;
+    /** Enable bulk delete mutations. Default: true */
+    bulkDelete?: boolean;
+    /** Enable relational/nested inserts on bulk create. Default: false */
+    bulkRelational?: boolean;
+    /** Include returning rows in payload. Default: true */
+    bulkReturning?: boolean;
+    /** Max items in values array (insert/upsert). Default: 1000 */
+    bulkMaxRows?: number;
+    /** Max nesting depth for relational inserts. Default: 3 */
+    bulkMaxNestingDepth?: number;
+    /** Require non-empty where on bulk update/delete. Default: true */
+    bulkRequireWhere?: boolean;
+}
+/**
+ * Max PostgreSQL parameters per query. Auto-batch splits at this limit.
+ */
+export declare const PG_MAX_PARAMS = 32000;

package/esm/types.js

@@ -0,0 +1,7 @@
+/**
+ * Configuration options and shared types for graphile-bulk-mutations.
+ */
+/**
+ * Max PostgreSQL parameters per query. Auto-batch splits at this limit.
+ */
+export const PG_MAX_PARAMS = 32_000;

package/esm/utils/index.d.ts

@@ -0,0 +1,4 @@
+export type { NestedRelationInfo } from './relations';
+export { discoverNestedRelations } from './relations';
+export type { ColumnSpec, InsertBatch } from './sql-builder';
+export { buildBulkDeleteSQL, buildBulkInsertSQL, buildBulkUpdateSQL } from './sql-builder';

package/esm/utils/index.js

@@ -0,0 +1,2 @@
+export { discoverNestedRelations } from './relations';
+export { buildBulkDeleteSQL, buildBulkInsertSQL, buildBulkUpdateSQL } from './sql-builder';

package/esm/utils/relations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+import type { ColumnSpec } from './sql-builder';
+/**
+ * Metadata for a single "has many" relation eligible for nested inserts.
+ */
+export interface NestedRelationInfo {
+    /** Registry key of the relation (e.g. "productsByCategoryId") */
+    relationName: string;
+    /** GraphQL field name on the parent values item type */
+    fieldName: string;
+    /** The remote (child) PgResource */
+    remoteResource: any;
+    /** Registry key of the remote resource */
+    remoteResourceName: string;
+    /** PK columns on the parent that the FK references */
+    localAttributes: string[];
+    /** FK columns on the child table */
+    remoteAttributes: string[];
+    /** GraphQL field name → SQL column name for child */
+    childFieldToAttr: Record<string, string>;
+    /** Column specs for building child INSERT SQL */
+    childColumnSpecs: ColumnSpec[];
+    /** Compiled SQL table name for the child */
+    childCompiledFrom: string;
+    /** PK columns on the child table */
+    childPkColumns: string[];
+}
+/**
+ * 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 declare function discoverNestedRelations(resource: any, pgRegistry: any, inflection: any, sql: any): NestedRelationInfo[];