@contember/bindx 0.1.30 → 0.1.32

package/src/persistence/BatchPersister.ts

@@ -12,6 +12,7 @@ import type {
 	PersistenceResult,
 	PersistScope,
 	TransactionMutation,
+	TransactionMutationResult,
 	TransactionResult,
 	UpdateMode,
 } from './types.js'
@@ -603,11 +604,15 @@ export class BatchPersister {
 					if (this.adapter.create && mutation.data) {
 						const result = await this.adapter.create(mutation.entityType, mutation.data)
 						const persistedId = result.data?.['id'] as string | undefined
+						const nestedResults = result.ok && result.data && mutation.data
+							? this.extractNestedResultsFromNode(mutation.data, result.data, mutation.entityType, mutation.entityId)
+							: undefined
 						results.push({
 							entityType: mutation.entityType,
 							entityId: mutation.entityId,
 							ok: result.ok,
 							persistedId,
+							nestedResults,
 							errorMessage: result.errorMessage,
 							mutationResult: result.mutationResult,
 						})
@@ -621,10 +626,14 @@ export class BatchPersister {
 							mutation.entityId,
 							mutation.data,
 						)
+						const nestedResults = result.ok && result.data && mutation.data
+							? this.extractNestedResultsFromNode(mutation.data, result.data, mutation.entityType, mutation.entityId)
+							: undefined
 						results.push({
 							entityType: mutation.entityType,
 							entityId: mutation.entityId,
 							ok: result.ok,
+							nestedResults,
 							errorMessage: result.errorMessage,
 							mutationResult: result.mutationResult,
 						})
@@ -700,6 +709,11 @@ export class BatchPersister {
 						)
 					}
 
+					// Process nested results (inline-created entities within this mutation)
+					if (mutationResult.nestedResults) {
+						this.commitNestedResults(mutationResult.nestedResults)
+					}
+
 					results.push({
 						entityType: entity.entityType,
 						entityId: entity.entityId,
@@ -710,6 +724,11 @@ export class BatchPersister {
 					successCount++
 				}
 			}
+
+			// Commit nested entities that don't have explicit results from the adapter.
+			// These entities were nested inside a parent mutation's data and exist on the server,
+			// but the adapter may not provide individual results for them.
+			this.commitUnresolvedNestedEntities(entities)
 		} else {
 			// Transaction failed - map errors and optionally rollback
 			// For pessimistic mode, entities are already at server state, no rollback needed
@@ -919,6 +938,224 @@ export class BatchPersister {
 		}
 	}
 
+	/**
+	 * Recursively commits nested entity results and maps their server IDs.
+	 * Called when the adapter provides nestedResults in the transaction response.
+	 * Uses the MutationCollector's nestedEntityTypes map to resolve entity types,
+	 * since the adapter may not know the correct entity type for nested entities.
+	 */
+	private commitNestedResults(nestedResults: readonly TransactionMutationResult[]): void {
+		const nestedTypes = this.mutationCollector instanceof MutationCollector
+			? this.mutationCollector.getNestedEntityTypes()
+			: null
+
+		for (const nested of nestedResults) {
+			if (!nested.ok) continue
+
+			// Resolve entity type from collector's tracking (adapter may report 'Unknown')
+			const entityType = nestedTypes?.get(nested.entityId) ?? nested.entityType
+			const snapshot = this.store.getEntitySnapshot(entityType, nested.entityId)
+			if (!snapshot) continue
+
+			// Commit the nested entity
+			this.dispatcher.dispatch(commitEntity(entityType, nested.entityId))
+			this.store.commitAllRelations(entityType, nested.entityId)
+			this.store.setExistsOnServer(entityType, nested.entityId, true)
+
+			// Map temp ID to server-assigned ID
+			if (nested.persistedId) {
+				this.store.mapTempIdToPersistedId(
+					entityType,
+					nested.entityId,
+					nested.persistedId,
+				)
+			}
+
+			// Recurse for deeper nesting
+			if (nested.nestedResults) {
+				this.commitNestedResults(nested.nestedResults)
+			}
+		}
+	}
+
+	/**
+	 * Commits nested entities that were part of the transaction but don't have
+	 * explicit results from the adapter. These entities were created inline
+	 * inside a parent mutation and exist on the server after a successful persist.
+	 */
+	private commitUnresolvedNestedEntities(entities: DirtyEntity[]): void {
+		if (!(this.mutationCollector instanceof MutationCollector)) return
+
+		const nestedTypes = this.mutationCollector.getNestedEntityTypes()
+		if (nestedTypes.size === 0) return
+
+		// Find nested entities that are in the entities list but weren't committed
+		// by the main result processing (they had no matching result from the adapter)
+		for (const entity of entities) {
+			if (entity.changeType !== 'create') continue
+			if (!nestedTypes.has(entity.entityId)) continue
+
+			// Check if this entity was already committed (has server data)
+			if (this.store.existsOnServer(entity.entityType, entity.entityId)) continue
+
+			// Commit it — the parent mutation succeeded, so this entity exists on the server
+			this.dispatcher.dispatch(commitEntity(entity.entityType, entity.entityId))
+			this.store.commitAllRelations(entity.entityType, entity.entityId)
+			this.store.setExistsOnServer(entity.entityType, entity.entityId, true)
+		}
+
+		// Also commit materialized entities that may not be in the entities list
+		// (they were created during mutation building by materializeEmbeddedHasMany/HasOne)
+		for (const [tempId, entityType] of nestedTypes) {
+			if (this.store.existsOnServer(entityType, tempId)) continue
+
+			const snapshot = this.store.getEntitySnapshot(entityType, tempId)
+			if (!snapshot) continue
+
+			this.dispatcher.dispatch(commitEntity(entityType, tempId))
+			this.store.commitAllRelations(entityType, tempId)
+			this.store.setExistsOnServer(entityType, tempId, true)
+		}
+	}
+
+	/**
+	 * Extracts nested entity results from a mutation's node response data.
+	 * Walks the mutation data structure to find inline create operations,
+	 * then matches them against the node response to extract server-assigned IDs.
+	 *
+	 * For hasOne creates: looks up the temp ID from the store's relation state
+	 * for the parent entity, then gets the server ID from the response node field.
+	 * For hasMany creates: filters new IDs from the response array by excluding
+	 * known pre-existing IDs, matching to temp IDs (aliases) by position.
+	 */
+	private extractNestedResultsFromNode(
+		mutationData: Record<string, unknown>,
+		nodeData: Record<string, unknown>,
+		parentEntityType: string,
+		parentEntityId: string,
+	): TransactionMutationResult[] {
+		const results: TransactionMutationResult[] = []
+		const nestedTypes = this.mutationCollector instanceof MutationCollector
+			? this.mutationCollector.getNestedEntityTypes()
+			: null
+
+		const makeResult = (
+			tempId: string,
+			createData: Record<string, unknown>,
+			nodeItem: Record<string, unknown>,
+		): TransactionMutationResult => {
+			const childResults = this.extractNestedResultsFromNode(
+				createData, nodeItem,
+				nestedTypes?.get(tempId) ?? 'Unknown', tempId,
+			)
+			return {
+				entityType: nestedTypes?.get(tempId) ?? 'Unknown',
+				entityId: tempId,
+				ok: true,
+				persistedId: nodeItem['id'] as string,
+				nestedResults: childResults.length > 0 ? childResults : undefined,
+			}
+		}
+
+		for (const [fieldName, fieldValue] of Object.entries(mutationData)) {
+			if (fieldValue === null || fieldValue === undefined) continue
+
+			if (Array.isArray(fieldValue)) {
+				const nodeItems = nodeData[fieldName]
+				if (!Array.isArray(nodeItems)) continue
+
+				// Separate create ops from known IDs (connect/update)
+				const knownIds = new Set<string>()
+				const createOps: Array<{ alias: string; createData: Record<string, unknown> }> = []
+
+				for (const op of fieldValue) {
+					if (typeof op !== 'object' || op === null) continue
+					const opObj = op as Record<string, unknown>
+
+					if ('connect' in opObj) {
+						const connectBy = opObj['connect'] as Record<string, unknown>
+						if (connectBy['id']) knownIds.add(connectBy['id'] as string)
+					} else if ('update' in opObj) {
+						const by = (opObj['update'] as Record<string, unknown>)['by'] as Record<string, unknown> | undefined
+						if (by?.['id']) knownIds.add(by['id'] as string)
+					} else if ('create' in opObj && opObj['alias']) {
+						createOps.push({
+							alias: opObj['alias'] as string,
+							createData: opObj['create'] as Record<string, unknown>,
+						})
+					}
+				}
+
+				// Include pre-existing server IDs
+				const hasManyState = this.store.getHasMany(parentEntityType, parentEntityId, fieldName)
+				if (hasManyState) {
+					for (const id of hasManyState.serverIds) knownIds.add(id)
+				}
+
+				// Filter response to new items only, then content-match to create ops.
+				// Contember API does not guarantee hasMany ordering in node response,
+				// so we match by scalar field values instead of position.
+				// Unmatched creates keep their temp IDs until the next fetch.
+				const unmatchedItems = (nodeItems as Record<string, unknown>[])
+					.filter(it => typeof it === 'object' && it !== null && !knownIds.has(it['id'] as string))
+
+				for (const createOp of createOps) {
+					const idx = unmatchedItems.findIndex(it => this.isCreateDataMatchingNode(createOp.createData, it))
+					if (idx < 0) continue
+					results.push(makeResult(createOp.alias, createOp.createData, unmatchedItems.splice(idx, 1)[0]!))
+				}
+			} else if (typeof fieldValue === 'object') {
+				const opObj = fieldValue as Record<string, unknown>
+				const nodeField = nodeData[fieldName]
+
+				if ('create' in opObj && typeof nodeField === 'object' && nodeField !== null) {
+					const serverId = (nodeField as Record<string, unknown>)['id'] as string | undefined
+					if (!serverId) continue
+
+					const relationState = this.store.getRelation(parentEntityType, parentEntityId, fieldName)
+					if (!relationState?.currentId) continue
+
+					results.push(makeResult(
+						relationState.currentId,
+						opObj['create'] as Record<string, unknown>,
+						nodeField as Record<string, unknown>,
+					))
+				}
+			}
+		}
+
+		return results
+	}
+
+	/**
+	 * Content-based matching: checks whether create data matches a response node
+	 * by comparing scalars and hasOne relation IDs. Same approach as the legacy
+	 * binding's TreeAugmenter.isEntityMatching.
+	 */
+	private isCreateDataMatchingNode(
+		createData: Record<string, unknown>,
+		nodeItem: Record<string, unknown>,
+	): boolean {
+		for (const [key, value] of Object.entries(createData)) {
+			if (value === null || value === undefined) continue
+
+			if (typeof value !== 'object') {
+				if (nodeItem[key] !== value) return false
+			} else if (!Array.isArray(value)) {
+				const op = value as Record<string, unknown>
+				const nodeField = nodeItem[key]
+				if (!nodeField || typeof nodeField !== 'object') continue
+
+				if ('connect' in op) {
+					if ((op['connect'] as Record<string, unknown>)['id'] !== (nodeField as Record<string, unknown>)['id']) return false
+				} else if ('create' in op) {
+					if (!this.isCreateDataMatchingNode(op['create'] as Record<string, unknown>, nodeField as Record<string, unknown>)) return false
+				}
+			}
+		}
+		return true
+	}
+
 	/**
 	 * Cancels all in-flight operations.
 	 */

package/src/persistence/MutationCollector.ts

@@ -32,6 +32,8 @@ export interface EntityMutationResult {
 export class MutationCollector implements MutationDataCollector {
 	private excludedEntityIds: ReadonlySet<string> = new Set()
 	private readonly _nestedEntityIds: Set<string> = new Set()
+	/** Maps nested entity temp IDs to their entity types for post-persist processing */
+	private readonly _nestedEntityTypes: Map<string, string> = new Map()
 
 	constructor(
 		private readonly store: SnapshotStore,
@@ -46,6 +48,7 @@ export class MutationCollector implements MutationDataCollector {
 	setExcludedEntities(ids: ReadonlySet<string>): void {
 		this.excludedEntityIds = ids
 		this._nestedEntityIds.clear()
+		this._nestedEntityTypes.clear()
 	}
 
 	/**
@@ -57,6 +60,14 @@ export class MutationCollector implements MutationDataCollector {
 		return this._nestedEntityIds
 	}
 
+	/**
+	 * Returns a map of nested entity temp IDs to their entity types.
+	 * Used by BatchPersister to commit and map IDs for nested entities after persist.
+	 */
+	getNestedEntityTypes(): ReadonlyMap<string, string> {
+		return this._nestedEntityTypes
+	}
+
 	// ==================== Main Collection Methods ====================
 
 	/**
@@ -175,23 +186,22 @@ export class MutationCollector implements MutationDataCollector {
 			}
 		}
 
-		// Collect relation values
+		// Materialize embedded relation data into store entities,
+		// then collect from store for consistent tracking and post-persist ID mapping
+		this.materializeEntityRelations(entityType, entityId)
+
+		// Collect relation values from store
 		const relationFields = this.schemaProvider.getRelationFields(entityType)
 		for (const fieldName of relationFields) {
-			const value = data[fieldName]
 			const relationType = this.schemaProvider.getRelationType(entityType, fieldName)
 
 			if (relationType === 'hasOne') {
-				// Check embedded data first, then fall back to RelationStore
-				const relationOp = this.collectCreateOneRelation(value)
-					?? this.collectHasOneOperation(entityType, entityId, fieldName)
+				const relationOp = this.collectHasOneOperation(entityType, entityId, fieldName)
 				if (relationOp !== null) {
 					createData[fieldName] = relationOp
 				}
 			} else if (relationType === 'hasMany') {
-				// Try embedded data first, then fall back to RelationStore
-				const relationOps = this.collectCreateManyRelation(value)
-					?? this.collectHasManyOperations(entityType, entityId, fieldName)
+				const relationOps = this.collectHasManyOperations(entityType, entityId, fieldName)
 				if (relationOps !== null && relationOps.length > 0) {
 					createData[fieldName] = relationOps
 				}
@@ -332,6 +342,7 @@ export class MutationCollector implements MutationDataCollector {
 						this._nestedEntityIds.add(currentId)
 						const targetType = this.schemaProvider.getRelationTarget(entityType, fieldName)
 						if (targetType) {
+							this._nestedEntityTypes.set(currentId, targetType)
 							const createData = this.collectCreateData(targetType, currentId)
 							return { create: createData ?? {} }
 						}
@@ -437,20 +448,13 @@ export class MutationCollector implements MutationDataCollector {
 			}
 		}
 
-		// Created entities -> create (using entity snapshot data)
+		// Created entities -> create (using collectCreateData for full recursive collection)
 		if (targetType) {
 			for (const tempId of hasManyState.createdEntities) {
 				this._nestedEntityIds.add(tempId)
-				const itemSnapshot = this.store.getEntitySnapshot(targetType, tempId)
-				if (itemSnapshot) {
-					const createData = { ...itemSnapshot.data as Record<string, unknown> }
-					delete createData['id']
-					if (Object.keys(createData).length > 0) {
-						operations.push({ create: this.processNestedData(createData), alias: tempId })
-					} else {
-						operations.push({ create: {}, alias: tempId })
-					}
-				}
+				this._nestedEntityTypes.set(tempId, targetType)
+				const createData = this.collectCreateData(targetType, tempId)
+				operations.push({ create: createData ?? {}, alias: tempId })
 			}
 		}
 
@@ -587,4 +591,148 @@ export class MutationCollector implements MutationDataCollector {
 	private isExistingEntity(id: string): boolean {
 		return isPersistedId(id)
 	}
+
+	// ==================== Embedded Data Materialization ====================
+
+	/**
+	 * Materializes embedded relation data in an entity's snapshot into proper
+	 * store entities and relations. This normalizes inline objects (e.g.
+	 * `reviews: [{ reviewType: 'expert' }]`) into tracked entities with temp IDs,
+	 * enabling proper post-persist ID mapping and commit.
+	 */
+	private materializeEntityRelations(entityType: string, entityId: string): void {
+		if (!this.schemaProvider.hasEntity(entityType)) return
+
+		const snapshot = this.store.getEntitySnapshot(entityType, entityId)
+		if (!snapshot) return
+
+		const data = snapshot.data as Record<string, unknown>
+		const relationFields = this.schemaProvider.getRelationFields(entityType)
+
+		for (const fieldName of relationFields) {
+			const value = data[fieldName]
+			if (value === null || value === undefined) continue
+
+			const relationType = this.schemaProvider.getRelationType(entityType, fieldName)
+
+			if (relationType === 'hasOne' && typeof value === 'object' && !Array.isArray(value)) {
+				this.materializeEmbeddedHasOne(entityType, entityId, fieldName, value as Record<string, unknown>)
+			} else if (relationType === 'hasMany' && Array.isArray(value) && value.length > 0) {
+				this.materializeEmbeddedHasMany(entityType, entityId, fieldName, value)
+			}
+		}
+	}
+
+	/**
+	 * Materializes an embedded hasMany array into store entities.
+	 * Skips if the hasMany state already has store-managed entities.
+	 */
+	private materializeEmbeddedHasMany(
+		entityType: string,
+		entityId: string,
+		fieldName: string,
+		items: unknown[],
+	): void {
+		const targetType = this.schemaProvider.getRelationTarget(entityType, fieldName)
+		if (!targetType) return
+
+		// Skip if store already has managed entities for this relation
+		const existing = this.store.getHasMany(entityType, entityId, fieldName)
+		if (existing && (existing.createdEntities.size > 0 || existing.plannedConnections.size > 0)) {
+			return
+		}
+
+		this.store.getOrCreateHasMany(entityType, entityId, fieldName, [])
+
+		for (const item of items) {
+			if (typeof item !== 'object' || item === null) continue
+			const obj = item as Record<string, unknown>
+			const id = obj['id'] as string | undefined
+
+			if (id && !isTempId(id) && isPersistedId(id)) {
+				// Existing entity — add as a planned connection (not created)
+				this.store.connectExistingToHasMany(entityType, entityId, fieldName, id)
+				continue
+			}
+
+			// Create store entity from embedded data
+			const entityData = { ...obj }
+			delete entityData['id']
+			const tempId = this.store.createEntity(targetType, entityData)
+			this.store.addToHasMany(entityType, entityId, fieldName, tempId)
+
+			// Recursively materialize nested relations in the new entity
+			this.materializeEntityRelations(targetType, tempId)
+		}
+
+		// Clear embedded array from parent snapshot
+		this.clearEmbeddedField(entityType, entityId, fieldName, [])
+	}
+
+	/**
+	 * Materializes an embedded hasOne object into a store entity and relation.
+	 * Skips if a relation already exists in the store for this field.
+	 */
+	private materializeEmbeddedHasOne(
+		entityType: string,
+		entityId: string,
+		fieldName: string,
+		obj: Record<string, unknown>,
+	): void {
+		// Skip if relation already exists in store
+		const existingRelation = this.store.getRelation(entityType, entityId, fieldName)
+		if (existingRelation) return
+
+		const targetType = this.schemaProvider.getRelationTarget(entityType, fieldName)
+		if (!targetType) return
+
+		const id = obj['id'] as string | undefined
+
+		if (id && !isTempId(id) && isPersistedId(id)) {
+			// Existing entity — create a connect relation
+			this.store.getOrCreateRelation(entityType, entityId, fieldName, {
+				currentId: id,
+				serverId: null,
+				state: 'connected',
+				serverState: 'disconnected',
+				placeholderData: {},
+			})
+		} else {
+			// New entity — create store entity and connect
+			const entityData = { ...obj }
+			delete entityData['id']
+			const tempId = this.store.createEntity(targetType, entityData)
+
+			this.store.getOrCreateRelation(entityType, entityId, fieldName, {
+				currentId: tempId,
+				serverId: null,
+				state: 'connected',
+				serverState: 'disconnected',
+				placeholderData: {},
+			})
+
+			// Recursively materialize nested relations
+			this.materializeEntityRelations(targetType, tempId)
+		}
+
+		// Clear embedded data from parent snapshot
+		this.clearEmbeddedField(entityType, entityId, fieldName, null)
+	}
+
+	/**
+	 * Clears an embedded field value from an entity's snapshot data.
+	 */
+	private clearEmbeddedField(
+		entityType: string,
+		entityId: string,
+		fieldName: string,
+		emptyValue: unknown,
+	): void {
+		const snapshot = this.store.getEntitySnapshot(entityType, entityId)
+		if (!snapshot) return
+
+		const data = { ...(snapshot.data as Record<string, unknown>) }
+		data[fieldName] = emptyValue
+		this.store.setEntityData(entityType, entityId, data, false)
+	}
 }

package/src/persistence/types.ts

@@ -150,6 +150,12 @@ export interface TransactionMutationResult {
 	readonly persistedId?: string
 	readonly errorMessage?: string
 	readonly mutationResult?: ContemberMutationResult
+	/**
+	 * Results for entities created inline within this mutation's data.
+	 * Each entry maps a nested entity's temp ID (used as alias in the mutation)
+	 * to its server-assigned ID. Recursive for deeply nested creates.
+	 */
+	readonly nestedResults?: readonly TransactionMutationResult[]
 }
 
 /**

package/src/store/EntityMetaStore.ts

@@ -115,6 +115,35 @@ export class EntityMetaStore {
 		return !this.tempToPersistedId.has(key)
 	}
 
+	/**
+	 * Moves all metadata from oldKey to newKey.
+	 */
+	rekey(oldKey: string, newKey: string): void {
+		const meta = this.entityMetas.get(oldKey)
+		if (meta) {
+			this.entityMetas.delete(oldKey)
+			this.entityMetas.set(newKey, meta)
+		}
+
+		const loadState = this.loadStates.get(oldKey)
+		if (loadState) {
+			this.loadStates.delete(oldKey)
+			this.loadStates.set(newKey, loadState)
+		}
+
+		if (this.persistingEntities.has(oldKey)) {
+			this.persistingEntities.delete(oldKey)
+			this.persistingEntities.add(newKey)
+		}
+
+		// Move temp ID mapping
+		const persistedId = this.tempToPersistedId.get(oldKey)
+		if (persistedId !== undefined) {
+			this.tempToPersistedId.delete(oldKey)
+			this.tempToPersistedId.set(newKey, persistedId)
+		}
+	}
+
 	// ==================== Bulk Operations ====================
 
 	exportMetas(keys: string[]): Map<string, EntityMeta> {

package/src/store/EntitySnapshotStore.ts

@@ -218,6 +218,29 @@ export class EntitySnapshotStore {
 		return keys
 	}
 
+	/**
+	 * Moves a snapshot from oldKey to newKey, updating the id in the snapshot data.
+	 */
+	rekey(oldKey: string, newKey: string, newId: string): void {
+		const snapshot = this.snapshots.get(oldKey)
+		if (!snapshot) return
+
+		// Update id field in data and serverData
+		const data = { ...snapshot.data as Record<string, unknown>, id: newId }
+		const serverData = { ...snapshot.serverData as Record<string, unknown>, id: newId }
+
+		const newSnapshot = createEntitySnapshot(
+			newId,
+			snapshot.entityType,
+			data,
+			serverData,
+			snapshot.version + 1,
+		)
+
+		this.snapshots.delete(oldKey)
+		this.snapshots.set(newKey, newSnapshot)
+	}
+
 	keys(): IterableIterator<string> {
 		return this.snapshots.keys()
 	}

package/src/store/ErrorStore.ts

@@ -248,4 +248,34 @@ export class ErrorStore {
 		this.entityErrors.clear()
 		this.relationErrors.clear()
 	}
+
+	/**
+	 * Rekeys all errors from oldKeyPrefix to newKeyPrefix.
+	 */
+	rekey(oldEntityKey: string, newEntityKey: string, oldKeyPrefix: string, newKeyPrefix: string): void {
+		this.rekeyMap(this.entityErrors, oldEntityKey, newEntityKey)
+		this.rekeyByPrefix(this.fieldErrors, oldKeyPrefix, newKeyPrefix)
+		this.rekeyByPrefix(this.relationErrors, oldKeyPrefix, newKeyPrefix)
+	}
+
+	private rekeyMap(map: Map<string, ErrorState>, oldKey: string, newKey: string): void {
+		const value = map.get(oldKey)
+		if (value) {
+			map.delete(oldKey)
+			map.set(newKey, value)
+		}
+	}
+
+	private rekeyByPrefix(map: Map<string, ErrorState>, oldPrefix: string, newPrefix: string): void {
+		const toMove: [string, ErrorState][] = []
+		for (const [key, value] of map) {
+			if (key.startsWith(oldPrefix)) {
+				toMove.push([key, value])
+			}
+		}
+		for (const [oldKey, value] of toMove) {
+			map.delete(oldKey)
+			map.set(newPrefix + oldKey.slice(oldPrefix.length), value)
+		}
+	}
 }