@contember/bindx 0.1.51 → 0.1.53

package/src/store/SnapshotStore.ts

@@ -1,11 +1,15 @@
 import type { EntitySnapshot, LoadStatus } from './snapshots.js'
 import { createEntitySnapshot } from './snapshots.js'
 import type { FieldError, FieldErrorFilter } from '../errors/types.js'
-import { SubscriptionManager, type SnapshotVersionBumper } from './SubscriptionManager.js'
+import type { SelectionMeta } from '../selection/types.js'
+import { SubscriptionManager, type SnapshotVersionBumper, type SynchronousResult } from './SubscriptionManager.js'
 import { ErrorStore } from './ErrorStore.js'
 import {
 	RelationStore,
+	type HasManyRelationProjection,
 	type HasManyRemovalType,
+	type HasManyViewMembership,
+	type HasManyViewProjection,
 	type RelationReconciliationResult,
 	type SentHasManyDelta,
 	type SentHasOneTransition,
@@ -18,6 +22,7 @@ import { generateTempId } from './entityId.js'
 import { DirtyTracker } from './DirtyTracker.js'
 import { EntitySnapshotStore } from './EntitySnapshotStore.js'
 import { RootRegistry } from './RootRegistry.js'
+import { ResponseOccurrenceIndex, type RelationTargetResolver } from './ResponseOccurrenceIndex.js'
 import { ReachabilityAnalyzer } from './ReachabilityAnalyzer.js'
 import { RekeyOrchestrator } from './RekeyOrchestrator.js'
 import type { RekeyContext, Rekeyable } from './RekeyOrchestrator.js'
@@ -32,7 +37,13 @@ import type {
 } from '../undo/UndoJournal.js'
 
 export type {
+	HasManyAdditionKind,
+	HasManyRelationProjection,
 	HasManyRemovalType,
+	HasManyView,
+	HasManyViewMembership,
+	HasManyViewProjection,
+	PlannedHasManyAddition,
 	RelationReconciliationResult,
 	SentHasManyAddition,
 	SentHasManyDelta,
@@ -83,6 +94,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 	 */
 	private readonly lastPropagatedData = new Map<string, unknown>()
 
+	private readonly responseOccurrences = new ResponseOccurrenceIndex()
+
 	/**
 	 * Optional write-journal. When set (by an attached UndoManager), mutating
 	 * methods record editable-layer pre-images of the cells they touch so a gesture
@@ -176,6 +189,11 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		}
 	}
 
+	/** Coalesces synchronous notifications, even on failure, without changing undo boundaries. */
+	batchNotifications<T>(fn: () => SynchronousResult<T>): T {
+		return this.subscriptions.batchNotifications(fn)
+	}
+
 	// ==================== Key Generation ====================
 
 	private getEntityKey(entityType: string, id: string): string {
@@ -304,6 +322,23 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		return newSnapshot as EntitySnapshot<T>
 	}
 
+	/**
+	 * Unites the occurrences of each entity within one server response, so the
+	 * narrower of two occurrences cannot replace fields the wider one carried.
+	 * Call it before any of the response is written. See {@link ResponseOccurrenceIndex}.
+	 */
+	indexServerResponse(entityType: string, data: unknown, selection: SelectionMeta, schema: RelationTargetResolver): void {
+		this.responseOccurrences.index(entityType, data, selection, schema)
+	}
+
+	/**
+	 * What to write for an entity occurrence of a server response: the union of
+	 * its occurrences in that response, or the occurrence itself.
+	 */
+	resolveServerOccurrence(occurrence: Record<string, unknown>): Record<string, unknown> {
+		return this.responseOccurrences.resolve(occurrence)
+	}
+
 	/**
 	 * Refreshes server data from a revalidation read while preserving the user's
 	 * local dirty edits. See {@link EntitySnapshotStore.refreshServerData}.
@@ -525,25 +560,74 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 
 	// ==================== Has-Many State (delegated to RelationStore) ====================
 
+	/**
+	 * Declares what a view read under {@link alias} can leave out, so the store can tell
+	 * a filtered view from one that merely orders or renames. Only the caller that
+	 * selected the relation knows the params; the alias is a hash of them.
+	 */
+	declareHasManyViewMembership(
+		entityType: string,
+		fieldName: string,
+		alias: string,
+		membership: HasManyViewMembership,
+	): void {
+		this.relations.declareHasManyViewMembership(entityType, fieldName, alias, membership)
+	}
+
+	/**
+	 * Materializes the relation and one args-view of it, refreshing that view's
+	 * server baseline when one is supplied.
+	 *
+	 * `alias` addresses a VIEW inside the relation state, never a key of its own:
+	 * the state is always keyed by the schema field name, so everything that names
+	 * the relation the way the schema and the server do finds it.
+	 */
 	getOrCreateHasMany(
 		parentType: string,
 		parentId: string,
 		fieldName: string,
 		serverIds?: string[],
 		alias?: string,
-	): StoredHasManyState {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		return this.relations.getOrCreateHasMany(key, serverIds)
+	): void {
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		this.relations.getOrCreateHasMany(key, alias ?? fieldName, serverIds)
 	}
 
+	/** The relation as persistence and dirty tracking see it — server baseline unioned across views. */
 	getHasMany(
 		parentType: string,
 		parentId: string,
 		fieldName: string,
+	): HasManyRelationProjection | undefined {
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.getHasManyRelation(key)
+	}
+
+	/** Whether the relation carries writes the next persist would send. */
+	hasPendingHasManyWrites(parentType: string, parentId: string, fieldName: string): boolean {
+		return this.relations.hasPendingHasManyWrites(this.getRelationKey(parentType, parentId, fieldName))
+	}
+
+	/** Whether one view carries an order its user arranged rather than the default one. */
+	hasExplicitHasManyOrder(
+		parentType: string,
+		parentId: string,
+		fieldName: string,
 		alias?: string,
-	): StoredHasManyState | undefined {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		return this.relations.getHasMany(key)
+	): boolean {
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.hasExplicitHasManyOrder(key, alias ?? fieldName)
+	}
+
+	/** The relation as ONE mounted has-many handle sees it. */
+	getHasManyView(
+		parentType: string,
+		parentId: string,
+		fieldName: string,
+		alias?: string,
+	): HasManyViewProjection {
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.getHasManyView(key, alias ?? fieldName)
 	}
 
 	setHasManyServerIds(
@@ -553,8 +637,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		serverIds: string[],
 		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		this.relations.setHasManyServerIds(key, serverIds)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		this.relations.setHasManyServerIds(key, alias ?? fieldName, serverIds)
 		this.notifyRelationSubscribers(key)
 	}
 
@@ -564,9 +648,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		fieldName: string,
 		itemId: string,
 		type: HasManyRemovalType,
-		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
 		this.relations.planHasManyRemoval(key, itemId, type)
 		this.notifyRelationSubscribers(key)
@@ -576,10 +659,9 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		parentType: string,
 		parentId: string,
 		fieldName: string,
-		alias?: string,
 	): Map<string, HasManyRemovalType> | undefined {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		return this.relations.getHasMany(key)?.plannedRemovals
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.getHasManyRelation(key)?.plannedRemovals
 	}
 
 	/**
@@ -598,34 +680,22 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		itemId: string,
 		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
-		this.relations.planHasManyConnection(key, itemId)
+		this.relations.planHasManyConnection(key, alias ?? fieldName, itemId)
 		this.notifyRelationSubscribers(key)
 	}
 
+	/** The connections the next persist will send — relation-level, not per view. */
 	getHasManyPlannedConnections(
 		parentType: string,
 		parentId: string,
 		fieldName: string,
-		alias?: string,
 	): Set<string> | undefined {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		const state = this.relations.getHasMany(key)
-		if (!state) return undefined
-		return new Set(state.plannedAdditions.keys())
-	}
-
-	commitHasMany(
-		parentType: string,
-		parentId: string,
-		fieldName: string,
-		newServerIds: string[],
-		alias?: string,
-	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		this.relations.commitHasMany(key, newServerIds)
-		this.notifyRelationSubscribers(key)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		const relation = this.relations.getHasManyRelation(key)
+		if (!relation) return undefined
+		return new Set(relation.plannedAdditions.keys())
 	}
 
 	reconcileSentHasMany(
@@ -633,9 +703,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		parentId: string,
 		fieldName: string,
 		delta: SentHasManyDelta,
-		alias?: string,
 	): RelationReconciliationResult {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		const result = this.relations.reconcileSentHasMany(key, delta)
 		this.notifyRelationSubscribers(key)
 		return result
@@ -645,9 +714,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		parentType: string,
 		parentId: string,
 		fieldName: string,
-		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
 		this.relations.resetHasMany(key)
 		this.notifyRelationSubscribers(key)
@@ -660,9 +728,9 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		itemId: string,
 		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
-		this.relations.addToHasMany(key, itemId)
+		this.relations.addToHasMany(key, alias ?? fieldName, itemId)
 		this.notifyRelationSubscribers(key)
 	}
 
@@ -674,7 +742,7 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 	): void {
 		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
-		this.relations.connectExistingToHasMany(key, itemId)
+		this.relations.connectExistingToHasMany(key, fieldName, itemId)
 		this.notifyRelationSubscribers(key)
 	}
 
@@ -684,9 +752,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		fieldName: string,
 		itemId: string,
 		removalType: HasManyRemovalType,
-		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
 		// Cancelling the add of a never-persisted child just removes it from the
 		// list; its now-unreachable snapshot is no longer reported as a `create` and
@@ -704,9 +771,9 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		toIndex: number,
 		alias?: string,
 	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
 		this.journal?.recordHasMany(key)
-		this.relations.moveInHasMany(key, fromIndex, toIndex)
+		this.relations.moveInHasMany(key, alias ?? fieldName, fromIndex, toIndex)
 		this.notifyRelationSubscribers(key)
 	}
 
@@ -716,8 +783,8 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		fieldName: string,
 		alias?: string,
 	): string[] {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		return this.relations.getHasManyOrderedIds(key)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.getHasManyOrderedIds(key, alias ?? fieldName)
 	}
 
 	getPresentationHasManyOrderedIds(
@@ -726,13 +793,13 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		fieldName: string,
 		alias?: string,
 	): string[] {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		const view = alias ?? fieldName
 		if (!this.meta.isPessimisticInFlight(this.getEntityKey(parentType, parentId))) {
-			return this.relations.getHasManyOrderedIds(key)
+			return this.relations.getHasManyOrderedIds(key, view)
 		}
 
-		const state = this.relations.getHasMany(key)
-		return state ? [...state.serverIds] : []
+		return [...this.relations.getHasManyView(key, view).serverIds]
 	}
 
 	isHasManyItemCreated(
@@ -740,24 +807,21 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		parentId: string,
 		fieldName: string,
 		itemId: string,
-		alias?: string,
 	): boolean {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		const state = this.relations.getHasMany(key)
-		return state?.plannedAdditions.get(itemId) === 'created'
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		return this.relations.getHasManyRelation(key)?.plannedAdditions.get(itemId) === 'created'
 	}
 
 	getHasManyCreatedEntities(
 		parentType: string,
 		parentId: string,
 		fieldName: string,
-		alias?: string,
 	): Set<string> | undefined {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		const state = this.relations.getHasMany(key)
-		if (!state) return undefined
+		const key = this.getRelationKey(parentType, parentId, fieldName)
+		const relation = this.relations.getHasManyRelation(key)
+		if (!relation) return undefined
 		const created = new Set<string>()
-		for (const [id, kind] of state.plannedAdditions) {
+		for (const [id, kind] of relation.plannedAdditions) {
 			if (kind === 'created') created.add(id)
 		}
 		return created
@@ -1105,23 +1169,16 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 		hasManyStates: Map<string, StoredHasManyState>
 		entityMetas: Map<string, EntityMeta>
 	}): void {
-		const notifiedEntityKeys = this.entitySnapshots.importSnapshots(snapshot.entitySnapshots)
-
-		this.meta.importMetas(snapshot.entityMetas)
+		this.subscriptions.batchNotifications(() => {
+			const entityKeys = this.entitySnapshots.importSnapshots(snapshot.entitySnapshots)
+			this.meta.importMetas(snapshot.entityMetas)
+			const relationKeys = this.relations.importRelationStates(snapshot.relationStates)
+			const hasManyKeys = this.relations.importHasManyStates(snapshot.hasManyStates)
 
-		const relationKeys = this.relations.importRelationStates(snapshot.relationStates)
-		const hasManyKeys = this.relations.importHasManyStates(snapshot.hasManyStates)
-		const notifiedRelationKeys = new Set([...relationKeys, ...hasManyKeys])
-
-		this.subscriptions.notifyGlobal()
-
-		for (const key of notifiedEntityKeys) {
-			this.subscriptions.notifyEntityDirect(key)
-		}
-
-		for (const key of notifiedRelationKeys) {
-			this.subscriptions.notifyRelationDirect(key)
-		}
+			this.subscriptions.notify()
+			for (const key of entityKeys) this.subscriptions.notifyEntityDirect(key)
+			for (const key of [...relationKeys, ...hasManyKeys]) this.subscriptions.notifyRelationDirect(key)
+		})
 	}
 
 	// ==================== Undo Journal Target (cell capture / restore) ====================
@@ -1163,25 +1220,19 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 	 * journal's rekey to rebase a pre-image when a just-persisted create became a
 	 * permanent member of the list (membership rebase for sealed creates).
 	 */
-	getLiveHasManyServerIds(relationKey: string): Set<string> {
-		const state = this.relations.getHasMany(relationKey)
-		return new Set(state?.serverIds ?? [])
+	getLiveHasManyServerIds(relationKey: string): ReadonlyMap<string, ReadonlySet<string>> {
+		return this.relations.collectHasManyViewServerIds(relationKey)
 	}
 
 	exportHasManyCell(key: string): HasManyCellImage {
-		const state = this.relations.getHasMany(key)
+		const state = this.relations.getHasManyState(key)
 		if (!state) return { kind: 'hasMany', key, present: false }
 		return {
 			kind: 'hasMany',
 			key,
 			present: true,
-			state: {
-				serverIds: new Set(state.serverIds),
-				orderedIds: state.orderedIds ? [...state.orderedIds] : null,
-				plannedRemovals: new Map(state.plannedRemovals),
-				plannedAdditions: new Map(state.plannedAdditions),
-				version: state.version,
-			},
+			// getHasMany already returns a deep copy; the image owns it outright.
+			state,
 		}
 	}
 
@@ -1220,7 +1271,9 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 				const image = this.exportHasManyCell(hasManyKey)
 				images.push(image)
 				if (image.state) {
-					if (image.state.orderedIds) worklist.push(...image.state.orderedIds)
+					for (const view of image.state.views.values()) {
+						if (view.orderedIds) worklist.push(...view.orderedIds)
+					}
 					for (const additionId of image.state.plannedAdditions.keys()) worklist.push(additionId)
 				}
 			}
@@ -1236,9 +1289,6 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 	 * then present relations, then un-creates, then dropped relations.
 	 */
 	applyJournalImages(images: JournalCellImage[]): void {
-		const notifyEntities = new Set<string>()
-		const notifyRelations = new Set<string>()
-
 		const presentEntities: EntityCellImage[] = []
 		const presentRelations: Array<RelationCellImage | HasManyCellImage> = []
 		const absentEntities: EntityCellImage[] = []
@@ -1246,29 +1296,37 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 
 		for (const img of images) {
 			if (img.kind === 'entity') {
-				notifyEntities.add(img.key)
 				;(img.present ? presentEntities : absentEntities).push(img)
 			} else {
-				notifyRelations.add(img.key)
-				notifyEntities.add(entityKeyOfRelationKey(img.key))
 				;(img.present ? presentRelations : absentRelations).push(img)
 			}
 		}
 
-		for (const img of presentEntities) this.applyEntityImage(img)
-		for (const img of presentRelations) this.applyRelationImage(img)
-		for (const img of absentEntities) {
-			const [type, id] = splitEntityKey(img.key)
-			this.removeEntity(type, id)
-		}
-		for (const img of absentRelations) {
-			if (img.kind === 'relation') this.relations.removeRelationState(img.key)
-			else this.relations.removeHasManyState(img.key)
-		}
+		// removeEntity notifies; the batch holds that back until the restore is complete.
+		this.subscriptions.batchNotifications(() => {
+			for (const img of presentEntities) this.applyEntityImage(img)
+			for (const img of presentRelations) this.applyRelationImage(img)
+			for (const img of absentEntities) {
+				const [type, id] = splitEntityKey(img.key)
+				this.removeEntity(type, id)
+			}
+			for (const img of absentRelations) {
+				if (img.kind === 'relation') this.relations.removeRelationState(img.key)
+				else this.relations.removeHasManyState(img.key)
+			}
 
-		this.subscriptions.notifyGlobal()
-		for (const key of notifyEntities) this.subscriptions.notifyEntityDirect(key)
-		for (const key of notifyRelations) this.subscriptions.notifyRelationDirect(key)
+			this.subscriptions.notify()
+			for (const img of images) this.notifyRestoredCell(img)
+		})
+	}
+
+	private notifyRestoredCell(img: JournalCellImage): void {
+		if (img.kind === 'entity') {
+			this.subscriptions.notifyEntityDirect(img.key)
+			return
+		}
+		this.subscriptions.notifyRelationDirect(img.key)
+		this.subscriptions.notifyEntityDirect(entityKeyOfRelationKey(img.key))
 	}
 
 	private applyEntityImage(img: EntityCellImage): void {
@@ -1315,10 +1373,26 @@ export class SnapshotStore implements SnapshotVersionBumper, JournalTarget {
 			}]]))
 		} else {
 			const s = img.state!
-			const live = this.relations.getHasMany(img.key)
+			const live = this.relations.getHasManyState(img.key)
+			// The editable layer (planned writes, manual ordering) comes from the image;
+			// the server baseline always from the live state, which may have advanced
+			// since the gesture. A view the image does not know did not exist before the
+			// gesture — the gesture itself may have created it — so it had no arranged
+			// order to restore and falls back to the default order of the restored writes.
+			const views = new Map(live?.views ?? [])
+			for (const [alias, view] of views) {
+				const recorded = s.views.get(alias)
+				views.set(alias, {
+					serverIds: new Set(view.serverIds),
+					orderedIds: recorded?.orderedIds ? [...recorded.orderedIds] : null,
+					membership: view.membership,
+				})
+			}
+			for (const [alias, recorded] of s.views) {
+				if (!views.has(alias)) views.set(alias, recorded)
+			}
 			this.relations.importHasManyStates(new Map([[img.key, {
-				serverIds: new Set(live ? live.serverIds : s.serverIds),
-				orderedIds: s.orderedIds ? [...s.orderedIds] : null,
+				views,
 				plannedRemovals: new Map(s.plannedRemovals),
 				plannedAdditions: new Map(s.plannedAdditions),
 				version: (live?.version ?? s.version) + 1,