json-rest-api 1.0.28 → 2.0.0

package/plugins/core/lib/writing/relationship-processor.js

@@ -1,162 +1,91 @@
-import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 import { validateRelationshipDataCardinality } from '../querying-writing/relationship-contracts.js'
+import { RELATIONSHIP_WRITE_BATCH_SIZE } from '../querying-writing/knex-constants.js'
+import { applyDatabaseReadOptions, databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
+
+export const lockRelationshipParent = async ({ context, helpers, scopeName }) => {
+  if (!context.transaction) return
+  const adapter = helpers.getStorageAdapter(scopeName)
+  const idColumn = adapter.getIdColumn()
+  const parent = () => adapter.buildBaseQuery({ transaction: context.transaction })
+    .where(idColumn, adapter.translateFilterValue('id', context.id))
+  // A row version change also rejects stale PostgreSQL repeatable-read writers.
+  const matched = await parent().update({ [idColumn]: context.transaction.ref(idColumn) })
+  // MySQL can report changed rows rather than matched rows when FOUND_ROWS is disabled.
+  if (!matched && !await parent().select(idColumn).forUpdate().first()) {
+    throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })
+  }
+}
+
+export const lockRelationshipTargets = async (api, transaction, identifiers) => {
+  if (!transaction) return identifiers
+  const targets = []
+  const resolved = []
+  const resources = new Map()
+  for (const { type, id } of identifiers) {
+    if (!resources.has(type)) resources.set(type, { adapter: api.knex.helpers.getStorageAdapter(type), seen: new Set(), resolved: new Set() })
+    const { adapter, seen } = resources.get(type)
+    const value = adapter.translateFilterValue('id', id)
+    if (seen.has(String(value))) continue
+    seen.add(String(value))
+    targets.push({ type, id, value, adapter })
+  }
+  for (let offset = 0; offset < targets.length; offset += RELATIONSHIP_WRITE_BATCH_SIZE) {
+    const batch = targets.slice(offset, offset + RELATIONSHIP_WRITE_BATCH_SIZE)
+    const byType = new Map()
+    for (const target of batch) {
+      if (!byType.has(target.type)) byType.set(target.type, [])
+      byType.get(target.type).push(target)
+    }
+    const found = new Map()
+    for (const [type, group] of byType) {
+      const { adapter } = group[0]
+      const idColumn = adapter.getIdColumn()
+      const rows = await applyDatabaseReadOptions(adapter.buildBaseQuery({ transaction })
+        .whereIn(idColumn, group.map(target => target.value))
+        .orderBy(`${adapter.getTableName()}.${idColumn}`).forUpdate().select({ [idColumn]: databaseIdentityExpression(transaction, idColumn) }))
+      found.set(type, new Set(rows.map(row => String(row[idColumn]))))
+    }
+    for (const { type, id, value, adapter } of batch) {
+      let storedId = String(value)
+      // Let the database resolve alternate spellings under its column collation.
+      if (!found.get(type).has(storedId)) {
+        const record = await applyDatabaseReadOptions(adapter.buildBaseQuery({ transaction })
+          .where(adapter.getIdColumn(), value).forUpdate().first({ [adapter.getIdColumn()]: databaseIdentityExpression(transaction, adapter.getIdColumn()) }))
+        if (!record) {
+          throw new RestApiResourceError(`Related ${type} with id ${id} not found`, {
+            subtype: 'not_found', resourceType: type, resourceId: id
+          })
+        }
+        storedId = String(record[adapter.getIdColumn()])
+      }
+      const identities = resources.get(type).resolved
+      if (!identities.has(storedId)) {
+        identities.add(storedId)
+        resolved.push({ type, id })
+      }
+    }
+  }
+  // Return each database identity once, retaining its first submitted spelling.
+  return resolved
+}
 
 /**
- * Processes JSON:API relationship data and converts to database operations
- *
- * @param {Object} scope - The scope object containing schema info
- * @param {Object} deps - Dependencies object
- * @returns {Object} Object with belongsToUpdates and manyToManyRelationships arrays
- *
- * @example
- * // Input: Simple belongsTo relationship
- * const inputRecord = {
- *   data: {
- *     type: 'articles',
- *     attributes: { title: 'My Article' },
- *     relationships: {
- *       author: {
- *         data: { type: 'users', id: '123' }
- *       },
- *       category: {
- *         data: { type: 'categories', id: '5' }
- *       }
- *     }
- *   }
- * };
- *
- * // Schema has:
- * // author_id: { belongsTo: 'users', as: 'author' }
- * // category_id: { belongsTo: 'categories', as: 'category' }
- *
- * const result = processRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Foreign keys extracted
- * // {
- * //   belongsToUpdates: {
- * //     author_id: '123',
- * //     category_id: '5'
- * //   },
- * //   manyToManyRelationships: []
- * // }
- *
- * @example
- * // Input: Polymorphic relationship
- * const inputRecord = {
- *   data: {
- *     type: 'comments',
- *     relationships: {
- *       commentable: {
- *         data: { type: 'posts', id: '456' }
- *       }
- *     }
- *   }
- * };
- *
- * // Schema relationships has:
- * // commentable: {
- * //   belongsToPolymorphic: {
- * //     types: ['posts', 'videos'],
- * //     typeField: 'commentable_type',
- * //     idField: 'commentable_id'
- * //   }
- * // }
- *
- * const result = processRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Both type and id fields set
- * // {
- * //   belongsToUpdates: {
- * //     commentable_type: 'posts',
- * //     commentable_id: '456'
- * //   },
- * //   manyToManyRelationships: []
- * // }
- *
- * @example
- * // Input: Many-to-many relationship
- * const inputRecord = {
- *   data: {
- *     type: 'articles',
- *     relationships: {
- *       tags: {
- *         data: [
- *           { type: 'tags', id: '10' },
- *           { type: 'tags', id: '20' }
- *         ]
- *       }
- *     }
- *   }
- * };
- *
- * // Schema relationships has:
- * // tags: {
- * //   type: 'manyToMany',
- * //   through: 'article_tags',
- * //   foreignKey: 'article_id',
- * //   otherKey: 'tag_id'
- * // }
- *
- * const result = processRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Many-to-many data collected
- * // {
- * //   belongsToUpdates: {},
- * //   manyToManyRelationships: [{
- * //     relName: 'tags',
- * //     relDef: {
- * //       through: 'article_tags',
- * //       foreignKey: 'article_id',
- * //       otherKey: 'tag_id'
- * //     },
- * //     relData: [
- * //       { type: 'tags', id: '10' },
- * //       { type: 'tags', id: '20' }
- * //     ]
- * //   }]
- * // }
- *
+ * Classify normalized linkage for the resource write lifecycle.
+ * Validates cardinality and polymorphic target types, then separates owner
+ * columns, referenced targets, pivot writes and reverse child writes. This
+ * helper prepares work; it does not write storage or establish authorization.
+ *
+ * @param {Object} scope - Resource with compiled schemaInfo in vars
+ * @param {Object} deps
+ * @param {Object} deps.context
+ * @param {Object} deps.context.inputRecord - Normalized JSON:API write document
+ * @returns {import('../../rest-api-plugin-methods/lifecycle-types.js').RelationshipPlan} belongsToUpdates map plus belongsToTargets,
+ *   manyToManyRelationships and reverseRelationships arrays
  * @example
- * // Input: Clearing relationships
- * const inputRecord = {
- *   data: {
- *     relationships: {
- *       author: { data: null },      // Clear belongsTo
- *       tags: { data: [] }           // Clear many-to-many
- *     }
- *   }
- * };
- *
- * const result = processRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Null for belongsTo, empty array for many-to-many
- * // {
- * //   belongsToUpdates: { author_id: null },
- * //   manyToManyRelationships: [{
- * //     relName: 'tags',
- * //     relDef: { ... },
- * //     relData: []  // Will delete all pivot records
- * //   }]
- * // }
- *
- * @description
- * Used by:
- * - rest-api-knex-plugin's dataPut and dataPatch methods
- * - Called before database writes to prepare relationship updates
- *
- * Purpose:
- * - Converts JSON:API relationship format to database operations
- * - Handles all relationship types: belongsTo, polymorphic, many-to-many
- * - Validates polymorphic types against allowed values
- * - Separates concerns: foreign keys vs pivot table operations
- *
- * Data flow:
- * 1. Receives JSON:API document with relationships section
- * 2. Analyzes schema to determine relationship types
- * 3. For belongsTo: extracts foreign key values
- * 4. For polymorphic: extracts both type and id fields
- * 5. For many-to-many: collects data for pivot operations
- * 6. Returns structured data for database updates
+ * // An explicit author clear produces belongsToUpdates.author_id = null.
+ * // An explicit empty tags array produces a pivot operation with relData: [].
+ * // Omitting relationships produces empty work collections, not implicit clears.
  */
 export const processRelationships = (scope, deps) => {
   // Extract values from scope
@@ -170,10 +99,12 @@ export const processRelationships = (scope, deps) => {
   const { context } = deps
   const { inputRecord } = context
   const belongsToUpdates = {}
+  const belongsToTargets = []
   const manyToManyRelationships = []
+  const reverseRelationships = []
 
   if (!inputRecord.data.relationships) {
-    return { belongsToUpdates, manyToManyRelationships }
+    return { belongsToUpdates, belongsToTargets, manyToManyRelationships, reverseRelationships }
   }
 
   for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
@@ -201,6 +132,7 @@ export const processRelationships = (scope, deps) => {
           belongsToUpdates[fieldName] = null
         } else if (relData.data?.id) {
           belongsToUpdates[fieldName] = relData.data.id
+          belongsToTargets.push(relData.data)
         }
       }
     }
@@ -232,6 +164,7 @@ export const processRelationships = (scope, deps) => {
 
         belongsToUpdates[typeField] = type
         belongsToUpdates[idField] = id
+        belongsToTargets.push(relData.data)
       }
     }
 
@@ -240,6 +173,7 @@ export const processRelationships = (scope, deps) => {
       manyToManyRelationships.push({
         relName,
         relDef: {
+          target: relDef.target,
           through: relDef.through,
           foreignKey: relDef.foreignKey,
           otherKey: relDef.otherKey
@@ -247,8 +181,10 @@ export const processRelationships = (scope, deps) => {
         relData: relData.data
       })
     }
-    // Note: hasOne and hasMany don't need processing here as they don't update the current record
+    if ((relDef?.type === 'hasOne' || relDef?.type === 'hasMany') && relData.data !== undefined) {
+      reverseRelationships.push({ relName, relDef, relData: relData.data })
+    }
   }
 
-  return { belongsToUpdates, manyToManyRelationships }
+  return { belongsToUpdates, belongsToTargets, manyToManyRelationships, reverseRelationships }
 }

package/plugins/core/lib/writing/resource-version.js

@@ -0,0 +1,172 @@
+import { randomUUID } from 'node:crypto'
+import { RestApiResourceError, RestApiValidationError, RestApiVersionConflictError } from '../../../../lib/rest-api-errors.js'
+import { applyDatabaseReadOptions, databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
+import { RELATIONSHIP_WRITE_BATCH_SIZE } from '../querying-writing/knex-constants.js'
+
+export function hasVersionedInverse (api, relDef) {
+  const schemaInfo = api.resources[relDef.target]?.vars.schemaInfo
+  return Boolean(schemaInfo?.versionField && Object.values(schemaInfo.schemaRelationships).some(inverse =>
+    inverse.through === relDef.through && inverse.foreignKey === relDef.otherKey && inverse.otherKey === relDef.foreignKey))
+}
+
+export function assertVersionedRelationshipTransaction (api, relDef, transaction) {
+  if (hasVersionedInverse(api, relDef) && (!transaction?.isTransaction || transaction.isCompleted())) {
+    throw new RestApiValidationError('Versioned relationship writes require an active transaction', { fields: ['transaction'] })
+  }
+}
+
+export async function invalidateManyToManyVersions (api, relDef, ids, transaction) {
+  if (!hasVersionedInverse(api, relDef) || !ids.length) return
+  const adapter = api.knex.helpers.getStorageAdapter(relDef.target)
+  const idColumn = adapter.getIdColumn()
+  const versionColumn = adapter.translateColumn(api.resources[relDef.target].vars.schemaInfo.versionField)
+  const values = [...new Set(ids.map(id => adapter.translateFilterValue('id', id)))]
+  for (let offset = 0; offset < values.length; offset += RELATIONSHIP_WRITE_BATCH_SIZE) {
+    const batch = values.slice(offset, offset + RELATIONSHIP_WRITE_BATCH_SIZE)
+    const cases = []
+    const bindings = [idColumn]
+    for (const id of batch) {
+      cases.push('WHEN ? THEN ?')
+      bindings.push(id, randomUUID())
+    }
+    bindings.push(versionColumn)
+    const revisions = transaction.raw(`CASE ?? ${cases.join(' ')} ELSE ?? END`, bindings)
+    await adapter.buildBaseQuery({ transaction }).whereIn(idColumn, batch).update({ [versionColumn]: revisions })
+  }
+}
+
+async function readInverseReferences (state, context) {
+  const { adapter, fields } = state
+  const selectedFields = []
+  for (const field of fields) {
+    const column = adapter.translateColumn(field)
+    selectedFields.push([field, databaseIdentityExpression(context.transaction, column)])
+  }
+  const selection = Object.fromEntries(selectedFields)
+  return applyDatabaseReadOptions(adapter.buildBaseQuery({ transaction: context.transaction })
+    .where(adapter.getIdColumn(), adapter.translateFilterValue('id', context.id)).forUpdate().first(selection))
+}
+
+// Capture actual stored references after authorization; hooks/setters may change the input.
+export async function captureInverseVersions ({ api, helpers, context, scopeName, isCreate = false }) {
+  const references = []
+  for (const [parentType, parent] of Object.entries(api.resources)) {
+    const schemaInfo = parent.vars.schemaInfo
+    if (!schemaInfo?.versionField) continue
+    for (const relationship of Object.values(schemaInfo.schemaRelationships)) {
+      if (!api.anyapi && relationship.type === 'manyToMany' && relationship.through === scopeName) {
+        references.push({ parentType, idField: relationship.foreignKey, valueField: relationship.otherKey })
+        continue
+      }
+      if (!['hasMany', 'hasOne'].includes(relationship.type) || relationship.target !== scopeName) continue
+      if (relationship.via) {
+        const inverse = context.schemaInfo.schemaRelationships[relationship.via]?.belongsToPolymorphic
+        if (inverse?.types.includes(parentType)) references.push({ parentType, idField: inverse.idField, typeField: inverse.typeField })
+      } else if (relationship.foreignKey) references.push({ parentType, idField: relationship.foreignKey })
+    }
+  }
+  if (!references.length) return undefined
+  const fields = new Set()
+  for (const { idField, typeField, valueField } of references) {
+    if (idField) fields.add(idField)
+    if (typeField) fields.add(typeField)
+    if (valueField) fields.add(valueField)
+  }
+  const state = { references, fields: [...fields], adapter: helpers.getStorageAdapter(scopeName) }
+  state.before = isCreate ? undefined : await readInverseReferences(state, context)
+  return state
+}
+
+export async function invalidateInverseVersions ({ state, context, helpers, api, isDelete = false }) {
+  if (!state) return
+  const after = isDelete ? undefined : await readInverseReferences(state, context)
+  const targets = new Map()
+  for (const { parentType, idField, typeField, valueField } of state.references) {
+    const readParentId = record => {
+      if (!record) return null
+      if (typeField && record[typeField] !== parentType) return null
+      return record[idField]
+    }
+    const oldId = readParentId(state.before)
+    const newId = readParentId(after)
+    const valueUnchanged = !valueField || state.before?.[valueField] === after?.[valueField]
+    if (oldId === newId && valueUnchanged) continue
+    for (const id of [oldId, newId]) {
+      if (id !== null && id !== undefined) targets.set(JSON.stringify([parentType, id]), { parentType, id })
+    }
+  }
+  // Update parents in a stable order so concurrent writes acquire locks in the same order.
+  const orderedTargets = [...targets].sort(([left], [right]) => left.localeCompare(right))
+  for (const [, { parentType, id }] of orderedTargets) {
+    const adapter = helpers.getStorageAdapter(parentType)
+    const field = api.resources[parentType].vars.schemaInfo.versionField
+    // An old dangling reference or a parent deleted in this transaction needs no revision.
+    await adapter.buildBaseQuery({ transaction: context.transaction })
+      .where(adapter.getIdColumn(), adapter.translateFilterValue('id', id))
+      .update({ [adapter.translateColumn(field)]: randomUUID() })
+  }
+}
+
+// Called after resource authorization, within the transaction containing the write.
+export async function advanceResourceVersion ({ scopeName, context, helpers, expectedVersion, nextVersion = randomUUID() }) {
+  const field = context.schemaInfo.versionField
+  if (expectedVersion !== undefined && (!field || typeof expectedVersion !== 'string' || !expectedVersion.length || expectedVersion.length > 128)) {
+    throw new RestApiValidationError('expectedVersion requires a versioned resource and a non-empty token of at most 128 characters', { fields: ['expectedVersion'] })
+  }
+  if (!field) return undefined
+  if (!context.transaction) throw new Error('Versioned writes require a transaction')
+
+  const adapter = helpers.getStorageAdapter(scopeName)
+  const column = adapter.translateColumn(field)
+  const query = adapter.buildBaseQuery({ transaction: context.transaction })
+    .where(adapter.getIdColumn(), adapter.translateFilterValue('id', context.id))
+  if (expectedVersion !== undefined) {
+    // Revision tokens use byte equality, independent of column collation.
+    const client = context.transaction.client.config.client
+    if (client === 'pg') {
+      query.whereRaw("convert_to(??, 'UTF8') = convert_to(?, 'UTF8')", [column, expectedVersion])
+    } else if (client === 'mysql2' || client === 'mysql') {
+      query.whereRaw('CAST(?? AS BINARY) = CAST(? AS BINARY)', [column, expectedVersion])
+    } else if (client === 'better-sqlite3' || client === 'sqlite3') {
+      query.whereRaw('CAST(?? AS BLOB) = CAST(? AS BLOB)', [column, expectedVersion])
+    } else {
+      throw new Error(`Conditional revisions are not implemented for database client '${client}'`)
+    }
+  }
+  const matched = await query.update({ [column]: nextVersion })
+  if (!matched) {
+    throw new RestApiVersionConflictError({ resourceType: scopeName, resourceId: context.id })
+  }
+  return nextVersion
+}
+
+export function initializeResourceVersion ({ context, expectedVersion }) {
+  const field = context.schemaInfo.versionField
+  if (expectedVersion !== undefined && (!field || typeof expectedVersion !== 'string' || !expectedVersion.length || expectedVersion.length > 128 || context.method === 'post')) {
+    throw new RestApiValidationError('expectedVersion requires an existing versioned resource and a non-empty token of at most 128 characters', { fields: ['expectedVersion'] })
+  }
+  if (!field) return undefined
+  const attributes = context.inputRecord?.data?.attributes
+  if (context.method !== 'delete' && attributes && Object.hasOwn(attributes, field)) {
+    throw new RestApiValidationError('The version field is managed by the library; use expectedVersion', { fields: [`data.attributes.${field}`] })
+  }
+  const state = { field, expectedVersion, nextVersion: randomUUID() }
+  const data = context.inputRecord?.data
+  if (context.method !== 'delete' && data && typeof data === 'object' && !Array.isArray(data) &&
+    (attributes === undefined || (attributes && typeof attributes === 'object' && !Array.isArray(attributes)))) {
+    context.inputRecord = { ...context.inputRecord, data: { ...data, attributes: { ...attributes, [field]: state.nextVersion } } }
+  }
+  return state
+}
+
+export async function applyResourceVersion ({ state, context, helpers, scopeName, isCreate = false }) {
+  if (!state) return
+  if (isCreate) {
+    if (state.expectedVersion !== undefined) {
+      throw new RestApiResourceError(`Resource not found: ${scopeName}/${context.id}`, { subtype: 'not_found' })
+    }
+  } else {
+    await advanceResourceVersion({ scopeName, context, helpers, expectedVersion: state.expectedVersion, nextVersion: state.nextVersion })
+  }
+  if (context.method !== 'delete') context.inputRecord.data.attributes[state.field] = state.nextVersion
+}

package/plugins/core/lib/writing/reverse-relationship-manipulations.js

@@ -0,0 +1,110 @@
+import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
+import { applyDatabaseReadOptions, databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
+import { RELATIONSHIP_WRITE_BATCH_SIZE } from '../querying-writing/knex-constants.js'
+import { whereInIdentifiers } from '../querying/identifier-query.js'
+import { lockRelationshipTargets } from './relationship-processor.js'
+
+// Read membership in bounded batches; each actual child write still goes through PATCH.
+export async function updateReverseRelationship ({ api, helpers, context, scopeName, relDef, relData, operation = 'replace' }) {
+  const targetType = relDef.target
+  const targetScope = api.resources[targetType]
+  if (!targetScope) {
+    throw new RestApiResourceError(`Related resource type '${targetType}' not found`, { subtype: 'related_type_not_found' })
+  }
+  const schemaInfo = targetScope.vars.schemaInfo
+  let inverseName
+  let parentValues
+  if (relDef.via) {
+    const inverse = schemaInfo.schemaRelationships[relDef.via]?.belongsToPolymorphic
+    if (!inverse || !inverse.types.includes(scopeName)) {
+      throw new RestApiResourceError(`Invalid reverse polymorphic relationship '${relDef.via}' on '${targetType}'`, { subtype: 'invalid_via_relationship' })
+    }
+    inverseName = relDef.via
+    parentValues = { [inverse.typeField]: scopeName, [inverse.idField]: context.id }
+  } else {
+    const field = schemaInfo.schemaStructure[relDef.foreignKey]
+    if (!field) {
+      throw new RestApiResourceError(`Foreign key '${relDef.foreignKey}' not found on '${targetType}'`, { subtype: 'invalid_foreign_key' })
+    }
+    inverseName = field.belongsTo === scopeName ? field.as : undefined
+    parentValues = { [relDef.foreignKey]: context.id }
+  }
+
+  const adapter = helpers.getStorageAdapter(targetType)
+  const query = adapter.buildBaseQuery({ transaction: context.transaction })
+  for (const [field, value] of Object.entries(parentValues)) {
+    query.where(adapter.translateColumn(field), adapter.translateFilterValue(field, value))
+  }
+  if (context.transaction) query.forUpdate()
+  const idColumn = adapter.getIdColumn()
+  const selection = { [idColumn]: databaseIdentityExpression(context.db || api.knex.instance, idColumn) }
+  let identifiers = []
+  if (Array.isArray(relData)) {
+    identifiers = relData
+  } else if (relData !== null) {
+    identifiers = [relData]
+  }
+  const targets = operation === 'remove' ? identifiers : await lockRelationshipTargets(api, context.transaction, identifiers)
+  const requested = new Map()
+  for (const { id } of targets) {
+    const value = adapter.translateFilterValue('id', id)
+    if (!requested.has(String(value))) requested.set(String(value), { id: String(id), value })
+  }
+  const requestedIds = [...requested.values()]
+
+  const patchChild = async (id, linked) => {
+    const data = { type: targetType, id }
+    if (inverseName) {
+      data.relationships = { [inverseName]: { data: linked ? { type: scopeName, id: String(context.id) } : null } }
+    } else {
+      data.attributes = Object.fromEntries(Object.entries(parentValues).map(([field, value]) => [field, linked ? value : null]))
+    }
+    try {
+      await targetScope.patch({
+        id, document: { data }, transaction: context.transaction, format: 'jsonapi', returning: 'none'
+      }, { ...context })
+    } catch (error) {
+      if (!linked && operation === 'replace' && error.code === 'REST_API_RESOURCE' && ['not_found', 'forbidden'].includes(error.subtype)) {
+        const rejection = new RestApiResourceError('Cannot replace a relationship with inaccessible existing members', { subtype: 'forbidden' })
+        rejection.cause = error
+        throw rejection
+      }
+      throw error
+    }
+  }
+
+  if (operation === 'replace') {
+    // Exclude the whole keep-list once; independent exclusions would remove retained children.
+    const removals = query.clone().whereNot(builder => whereInIdentifiers(builder, idColumn, requestedIds.map(({ value }) => value)))
+    let afterId
+    while (true) {
+      const page = removals.clone().orderBy(`${adapter.getTableName()}.${idColumn}`).limit(RELATIONSHIP_WRITE_BATCH_SIZE + 1).select(selection)
+      if (afterId !== undefined) page.where(idColumn, '>', afterId)
+      const rows = await applyDatabaseReadOptions(page)
+      for (const row of rows) await patchChild(String(adapter.getFieldValue(row, 'id')), false)
+      if (rows.length <= RELATIONSHIP_WRITE_BATCH_SIZE) break
+      afterId = rows.at(-1)[idColumn]
+    }
+  }
+
+  // Free all removed hasOne slots before assigning replacements.
+  for (let offset = 0; offset < requestedIds.length; offset += RELATIONSHIP_WRITE_BATCH_SIZE) {
+    const batch = requestedIds.slice(offset, offset + RELATIONSHIP_WRITE_BATCH_SIZE)
+    const rows = await applyDatabaseReadOptions(query.clone().whereIn(idColumn, batch.map(({ value }) => value)).select(selection))
+    const existing = new Map(rows.map(row => [String(row[idColumn]), row]))
+    for (const { id, value } of batch) {
+      // Resolve alternate ID spellings using the database's equality rules.
+      let record = existing.get(String(value))
+      if (!record && existing.size) {
+        const lookup = query.clone().where(idColumn, value).first(selection)
+        record = await applyDatabaseReadOptions(lookup)
+      }
+      if (operation === 'remove') {
+        if (record) {
+          await patchChild(id, false)
+          existing.delete(String(record[idColumn]))
+        }
+      } else if (!record) await patchChild(id, true)
+    }
+  }
+}