@contember/bindx 0.1.46 → 0.1.47

package/src/store/HasOneStore.ts

@@ -0,0 +1,454 @@
+import type { HasOneRelationState } from '../handles/types.js'
+import type { EntitySnapshot } from './snapshots.js'
+import { parentKeyFromOwnerPrefix, parentKeyFromRelationKey } from './relationKey.js'
+import { RelationEdgeIndex } from './RelationEdgeIndex.js'
+
+/**
+ * Relation state stored in SnapshotStore
+ */
+export interface StoredRelationState {
+	currentId: string | null
+	serverId: string | null
+	state: HasOneRelationState
+	serverState: HasOneRelationState
+	placeholderData: Record<string, unknown>
+	version: number
+}
+
+type ReconciliationResult = 'applied' | 'conflict'
+
+export type SentHasOneTransition =
+	| { operation: 'connect'; targetId: string }
+	| { operation: 'create'; targetId: string }
+	| { operation: 'disconnect'; targetId: string }
+	| { operation: 'delete'; targetId: string }
+
+function cloneRelationState(state: StoredRelationState): StoredRelationState {
+	return {
+		...state,
+		placeholderData: { ...state.placeholderData },
+	}
+}
+
+/**
+ * Owns has-one relation state ("parentType:parentId:fieldName" → {@link StoredRelationState}).
+ *
+ * Has its own monotonic {@link mutationVersion} bumped on every actual write
+ * (funnelled through {@link writeRelation} plus the delete/clear paths); the
+ * facade sums this with the has-many counter for {@link ReachabilityAnalyzer}.
+ */
+export class HasOneStore {
+	/** Relation states keyed by "parentType:parentId:fieldName" */
+	private readonly relationStates = new Map<string, StoredRelationState>()
+
+	/**
+	 * Bidirectional live-edge index, maintained by {@link writeRelation} /
+	 * {@link deleteRelation} so the parent↔child queries are O(degree) and the two
+	 * directions stay consistent by construction.
+	 */
+	private readonly edges = new RelationEdgeIndex()
+
+	private mutationVersion = 0
+
+	/**
+	 * Monotonic counter bumped on EDITABLE-layer has-one writes (setRelation /
+	 * resetRelation) — the writes an undo gesture must first record. Materialization
+	 * (getOrCreateRelation), post-persist commit, import, replaceEntityId, rekey and
+	 * delete deliberately do NOT bump it. Read by the undo write-guard (see UndoJournal).
+	 */
+	private editableWriteVersion = 0
+
+	getMutationVersion(): number {
+		return this.mutationVersion
+	}
+
+	getEditableWriteVersion(): number {
+		return this.editableWriteVersion
+	}
+
+	/**
+	 * The single write chokepoint. Reconciles the edge index by diffing the live
+	 * child of the previous state against the next, so every state-changing path
+	 * (set/commit/reset/import/replaceEntityId/...) keeps the index correct without
+	 * tracking the reverse direction itself.
+	 */
+	private writeRelation(key: string, state: StoredRelationState): void {
+		const oldChild = liveHasOneChildId(this.relationStates.get(key))
+		const newChild = liveHasOneChildId(state)
+		this.relationStates.set(key, state)
+		if (oldChild !== newChild) {
+			const parentKey = parentKeyFromRelationKey(key)
+			if (oldChild !== null) this.edges.removeEdge(parentKey, oldChild)
+			if (newChild !== null) this.edges.addEdge(parentKey, newChild)
+		}
+		this.mutationVersion++
+	}
+
+	/**
+	 * The single delete chokepoint — removes an entry and its live edge. Used by
+	 * the bulk remove and rekey-owner paths so they don't leak edges.
+	 */
+	private deleteRelation(key: string): void {
+		const existing = this.relationStates.get(key)
+		if (!existing) return
+		const child = liveHasOneChildId(existing)
+		if (child !== null) this.edges.removeEdge(parentKeyFromRelationKey(key), child)
+		this.relationStates.delete(key)
+		this.mutationVersion++
+	}
+
+	/**
+	 * Gets or creates relation state.
+	 */
+	getOrCreateRelation(
+		key: string,
+		initial: Omit<StoredRelationState, 'version'>,
+	): StoredRelationState {
+		if (!this.relationStates.has(key)) {
+			this.writeRelation(key, { ...initial, version: 0 })
+		}
+
+		return cloneRelationState(this.relationStates.get(key)!)
+	}
+
+	/**
+	 * Gets relation state.
+	 */
+	getRelation(key: string): StoredRelationState | undefined {
+		const state = this.relationStates.get(key)
+		return state ? cloneRelationState(state) : undefined
+	}
+
+	/**
+	 * Updates relation state.
+	 * If the relation state doesn't exist, creates it using entity snapshot for server data.
+	 */
+	setRelation(
+		key: string,
+		updates: Partial<Omit<StoredRelationState, 'version'>>,
+		entitySnapshot: EntitySnapshot | undefined,
+		fieldName: string,
+	): void {
+		const existing = this.relationStates.get(key)
+
+		if (!existing) {
+			let serverId: string | null = null
+			let serverState: HasOneRelationState = 'disconnected'
+
+			if (entitySnapshot?.serverData) {
+				const relatedData = (entitySnapshot.serverData as Record<string, unknown>)[fieldName]
+				if (relatedData && typeof relatedData === 'object' && 'id' in relatedData) {
+					serverId = (relatedData as { id: string }).id
+					serverState = 'connected'
+				}
+			}
+
+			this.writeRelation(key, {
+				currentId: 'currentId' in updates ? updates.currentId! : serverId,
+				serverId,
+				state: 'state' in updates ? updates.state! : serverState,
+				serverState,
+				placeholderData: updates.placeholderData ?? {},
+				version: 0,
+			})
+		} else {
+			this.writeRelation(key, {
+				...existing,
+				...updates,
+				version: existing.version + 1,
+			})
+		}
+		this.editableWriteVersion++
+	}
+
+	/**
+	 * Commits relation state (server = current).
+	 */
+	commitRelation(key: string): void {
+		const existing = this.relationStates.get(key)
+		if (!existing) return
+
+		this.writeRelation(key, {
+			...existing,
+			serverId: existing.currentId,
+			serverState: existing.state === 'creating' ? 'connected' : existing.state,
+			placeholderData: {},
+			version: existing.version + 1,
+		})
+	}
+
+	/**
+	 * Advances the server baseline by one confirmed sent transition while keeping
+	 * edits made after the request started as pending local state.
+	 */
+	reconcileSentTransition(
+		key: string,
+		transition: SentHasOneTransition,
+	): ReconciliationResult {
+		const existing = this.relationStates.get(key)
+		if (!existing) return 'conflict'
+
+		const next = reconcileHasOneState(existing, transition)
+		this.writeRelation(key, next.state)
+		return next.result
+	}
+
+	/**
+	 * Resets relation to server state.
+	 */
+	resetRelation(key: string): void {
+		const existing = this.relationStates.get(key)
+		if (!existing) return
+
+		this.writeRelation(key, {
+			...existing,
+			currentId: existing.serverId,
+			state: existing.serverState,
+			placeholderData: {},
+			version: existing.version + 1,
+		})
+		this.editableWriteVersion++
+	}
+
+	/**
+	 * Collects the ids of child entities reachable through LIVE has-one edges
+	 * (key prefix "parentType:parentId:") — an O(degree) read of the edge index.
+	 */
+	collectLiveChildIds(keyPrefix: string, ids: Set<string>): void {
+		this.edges.collectChildren(parentKeyFromOwnerPrefix(keyPrefix), ids)
+	}
+
+	/**
+	 * Adds the composite parent keys of every LIVE has-one edge pointing at
+	 * {@link childId} — an O(degree) read of the edge index, the exact reverse of
+	 * {@link collectLiveChildIds}.
+	 */
+	collectParentKeysForChild(childId: string, parents: Set<string>): void {
+		this.edges.collectParents(childId, parents)
+	}
+
+	/**
+	 * Collects the keys of every has-one relation owned by an entity (keys under the
+	 * given owner prefix). Mirrors {@link removeOwnedRelations} but only enumerates.
+	 */
+	collectOwnedKeys(keyPrefix: string, keys: string[]): void {
+		for (const key of this.relationStates.keys()) {
+			if (key.startsWith(keyPrefix)) keys.push(key)
+		}
+	}
+
+	/**
+	 * Removes a single has-one relation state (and its live edge). Used by undo
+	 * restore to drop a relation that did not exist before the gesture.
+	 */
+	removeRelation(key: string): void {
+		this.deleteRelation(key)
+	}
+
+	/**
+	 * Removes all has-one state owned by an entity (keys under the given owner
+	 * prefix), dropping each entry's edge through {@link deleteRelation}.
+	 */
+	removeOwnedRelations(keyPrefix: string): void {
+		for (const key of [...this.relationStates.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.deleteRelation(key)
+			}
+		}
+	}
+
+	/**
+	 * Commits all has-one relations for an entity.
+	 *
+	 * A relation whose planned op targets an item in `pendingItems` (by relation key)
+	 * was not sent and is left uncommitted, so the op is retried on the next persist.
+	 */
+	commitAllRelations(keyPrefix: string, pendingItems?: ReadonlyMap<string, ReadonlySet<string>>): void {
+		for (const [key, state] of this.relationStates) {
+			if (!key.startsWith(keyPrefix)) continue
+			const pending = pendingItems?.get(key)
+			if (pending && ((state.currentId !== null && pending.has(state.currentId)) || (state.serverId !== null && pending.has(state.serverId)))) {
+				continue
+			}
+			this.commitRelation(key)
+		}
+	}
+
+	/**
+	 * Resets all has-one relations for an entity to server state.
+	 */
+	resetAllRelations(keyPrefix: string): void {
+		for (const key of this.relationStates.keys()) {
+			if (key.startsWith(keyPrefix)) {
+				this.resetRelation(key)
+			}
+		}
+	}
+
+	/**
+	 * Collects the field names of dirty has-one relations for an entity.
+	 */
+	collectDirtyRelations(keyPrefix: string, dirtyRelations: string[]): void {
+		for (const [key, state] of this.relationStates) {
+			if (!key.startsWith(keyPrefix)) continue
+			const fieldName = key.slice(keyPrefix.length)
+
+			if (
+				state.currentId !== state.serverId ||
+				state.state !== state.serverState ||
+				Object.keys(state.placeholderData).length > 0
+			) {
+				dirtyRelations.push(fieldName)
+			}
+		}
+	}
+
+	/**
+	 * Exports relation states for given keys.
+	 */
+	exportRelationStates(keys: string[]): Map<string, StoredRelationState> {
+		const result = new Map<string, StoredRelationState>()
+		for (const key of keys) {
+			const state = this.relationStates.get(key)
+			if (state) {
+				result.set(key, cloneRelationState(state))
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Imports relation states from a snapshot.
+	 * Returns the keys that were imported for notification.
+	 */
+	importRelationStates(states: Map<string, StoredRelationState>): string[] {
+		const keys: string[] = []
+		for (const [key, state] of states) {
+			this.writeRelation(key, {
+				...state,
+				placeholderData: { ...state.placeholderData },
+			})
+			keys.push(key)
+		}
+		return keys
+	}
+
+	/**
+	 * Replaces all occurrences of oldId with newId across has-one relation states
+	 * (currentId, serverId).
+	 */
+	replaceEntityId(oldId: string, newId: string): void {
+		for (const [key, state] of this.relationStates) {
+			let changed = false
+			let currentId = state.currentId
+			let serverId = state.serverId
+
+			if (currentId === oldId) { currentId = newId; changed = true }
+			if (serverId === oldId) { serverId = newId; changed = true }
+
+			if (changed) {
+				this.writeRelation(key, { ...state, currentId, serverId, version: state.version + 1 })
+			}
+		}
+	}
+
+	/**
+	 * Rekeys has-one entries owned by an entity (changes the parent ID in the key).
+	 * Routing through {@link deleteRelation} + {@link writeRelation} migrates the
+	 * edge index from the old parent key to the new one for free.
+	 */
+	rekeyOwner(oldKeyPrefix: string, newKeyPrefix: string): void {
+		const toMove: [string, StoredRelationState][] = []
+		for (const [key, value] of this.relationStates) {
+			if (key.startsWith(oldKeyPrefix)) {
+				toMove.push([key, value])
+			}
+		}
+		for (const [oldKey, value] of toMove) {
+			this.deleteRelation(oldKey)
+			this.writeRelation(newKeyPrefix + oldKey.slice(oldKeyPrefix.length), value)
+		}
+	}
+
+	/**
+	 * Clears all has-one relation data.
+	 */
+	clear(): void {
+		this.relationStates.clear()
+		this.edges.clear()
+		this.mutationVersion++
+	}
+}
+
+/**
+ * The single liveness predicate for a has-one edge: the related id is live when
+ * the relation is connected to it and not deleted. Defined once and consumed by
+ * the write chokepoint so the forward/reverse index can never drift from it.
+ */
+function liveHasOneChildId(state: StoredRelationState | undefined): string | null {
+	if (!state) return null
+	return state.currentId !== null && state.state !== 'deleted' ? state.currentId : null
+}
+
+interface HasOneReconciliation {
+	state: StoredRelationState
+	result: ReconciliationResult
+}
+
+function reconcileHasOneState(
+	existing: StoredRelationState,
+	transition: SentHasOneTransition,
+): HasOneReconciliation {
+	if (transition.operation === 'connect' || transition.operation === 'create') {
+		return reconcileHasOneAddition(existing, transition)
+	}
+	return reconcileHasOneRemoval(existing, transition)
+}
+
+function reconcileHasOneAddition(
+	existing: StoredRelationState,
+	transition: Extract<SentHasOneTransition, { operation: 'connect' | 'create' }>,
+): HasOneReconciliation {
+	const wasRemoved = existing.currentId !== transition.targetId || existing.state !== 'connected'
+	const removedCreatedTarget = transition.operation === 'create'
+		&& existing.currentId === null
+		&& existing.state === 'disconnected'
+
+	return {
+		state: {
+			...existing,
+			currentId: removedCreatedTarget ? transition.targetId : existing.currentId,
+			serverId: transition.targetId,
+			state: removedCreatedTarget ? 'deleted' : existing.state,
+			serverState: 'connected',
+			placeholderData: wasRemoved ? existing.placeholderData : {},
+			version: existing.version + 1,
+		},
+		result: 'applied',
+	}
+}
+
+function reconcileHasOneRemoval(
+	existing: StoredRelationState,
+	transition: Extract<SentHasOneTransition, { operation: 'disconnect' | 'delete' }>,
+): HasOneReconciliation {
+	const isCompletedDelete = transition.operation === 'delete'
+		&& existing.currentId === transition.targetId
+		&& existing.state === 'deleted'
+	const isDeleteReversal = transition.operation === 'delete'
+		&& existing.currentId === transition.targetId
+		&& existing.state !== 'deleted'
+
+	return {
+		state: {
+			...existing,
+			currentId: isCompletedDelete ? null : existing.currentId,
+			serverId: null,
+			state: isCompletedDelete ? 'disconnected' : existing.state,
+			serverState: 'disconnected',
+			placeholderData: isCompletedDelete ? {} : existing.placeholderData,
+			version: existing.version + 1,
+		},
+		result: isDeleteReversal ? 'conflict' : 'applied',
+	}
+}

package/src/store/ReachabilityAnalyzer.ts

@@ -18,6 +18,14 @@ import type { RootRegistry } from './RootRegistry.js'
  * The graph is read from {@link RelationStore} (the source of truth for live
  * relation membership), never from the subscription parent-child registry,
  * which is append-mostly for notifications and does not reflect disconnects.
+ *
+ * The walk is O(E+R) and runs on every dirty check and post-persist sweep, so
+ * its result is memoized. Each sub-store the walk reads exposes a monotonic
+ * `getMutationVersion()` that bumps only when graph-relevant state changes
+ * (entity key set, `existsOnServer`/`isPersisting`, roots, relation edges).
+ * Their sum is a cache key: it is strictly increasing, so an unchanged sum
+ * proves nothing relevant changed and the cached set can be returned. Pure
+ * field edits do not bump any counter, keeping the cache warm on the hot path.
  */
 export class ReachabilityAnalyzer {
 	constructor(
@@ -27,11 +35,40 @@ export class ReachabilityAnalyzer {
 		private readonly roots: RootRegistry,
 	) {}
 
+	private cache: { version: number; result: Set<string> } | null = null
+
 	/**
 	 * Returns the set of entity keys ("entityType:id") for created
 	 * (never-persisted) entities reachable from a root through live relations.
+	 *
+	 * The returned set is the cached instance and is owned by the analyzer —
+	 * callers must treat it as read-only (the current consumers only call
+	 * `.has(...)` on it).
 	 */
 	computeReachableCreated(): Set<string> {
+		const version = this.graphVersion()
+		const cached = this.cache
+		if (cached !== null && cached.version === version) {
+			return cached.result
+		}
+
+		const result = this.walk()
+		this.cache = { version, result }
+		return result
+	}
+
+	/**
+	 * Sum of the graph-relevant mutation counters across the sub-stores the walk
+	 * reads. Monotonic, so an unchanged value means no relevant mutation happened.
+	 */
+	private graphVersion(): number {
+		return this.entitySnapshots.getMutationVersion()
+			+ this.meta.getMutationVersion()
+			+ this.relations.getMutationVersion()
+			+ this.roots.getMutationVersion()
+	}
+
+	private walk(): Set<string> {
 		const reachableCreated = new Set<string>()
 		const visited = new Set<string>()
 		const stack: string[] = []

package/src/store/RekeyOrchestrator.ts

@@ -0,0 +1,123 @@
+import { isPersistedId, isPlaceholderId } from './entityId.js'
+
+/**
+ * Describes a single temp→persisted rekey in every shape the participating
+ * sub-stores need (full key, owner prefix, bare id).
+ */
+export interface RekeyContext {
+	/** Old composite key, "entityType:tempId". */
+	readonly oldKey: string
+	/** New composite key, "entityType:persistedId". */
+	readonly newKey: string
+	/** Old owner prefix, "entityType:tempId:". */
+	readonly oldKeyPrefix: string
+	/** New owner prefix, "entityType:persistedId:". */
+	readonly newKeyPrefix: string
+	/** The temp id being replaced. */
+	readonly oldId: string
+	/** The server-assigned id. */
+	readonly newId: string
+}
+
+/**
+ * A store that owns per-entity state keyed (directly or by prefix) on an entity
+ * id and can migrate it from a temp id to its persisted id.
+ */
+export interface Rekeyable {
+	rekey(ctx: RekeyContext): void
+}
+
+/**
+ * Single source of temp→persisted identity, and the one place the rekey fan-out
+ * is sequenced.
+ *
+ * Owns the only id-redirect map: "entityType:tempId" → persistedId. Both key
+ * resolution ({@link resolveKey}/{@link resolveId}) and persisted-id queries
+ * ({@link getPersistedId}/{@link isNewEntity}) derive from it, so there is no
+ * second copy to keep in sync — the former `SnapshotStore.rekeyedEntities` and
+ * `EntityMetaStore.tempToPersistedId` are both gone. `SubscriptionManager` keeps
+ * its own closure-redirect chain, which tracks relation-key prefixes and stale
+ * unsubscribe closures rather than entity identity, so it stays internal there.
+ */
+export class RekeyOrchestrator {
+	/** "entityType:tempId" → persistedId. The single identity-redirect map. */
+	private readonly tempToPersisted = new Map<string, string>()
+	private readonly participants: Rekeyable[] = []
+	private readonly participantSet = new Set<Rekeyable>()
+
+	/**
+	 * @param participants the sub-stores to migrate, in the exact order
+	 *   {@link rekey} must visit them (the order is load-bearing — see rekey()).
+	 */
+	constructor(participants: readonly Rekeyable[]) {
+		for (const participant of participants) this.registerParticipant(participant)
+	}
+
+	/** Adds a participant once, preserving registration order. */
+	registerParticipant(participant: Rekeyable): void {
+		if (this.participantSet.has(participant)) return
+		this.participantSet.add(participant)
+		this.participants.push(participant)
+	}
+
+	/** Resolves an entity key, following a temp→persisted redirect if present. */
+	resolveKey(entityType: string, id: string): string {
+		const persisted = this.tempToPersisted.get(`${entityType}:${id}`)
+		return persisted !== undefined ? `${entityType}:${persisted}` : `${entityType}:${id}`
+	}
+
+	/** Resolves an entity id to its persisted id if it has been rekeyed. */
+	resolveId(entityType: string, id: string): string {
+		return this.tempToPersisted.get(`${entityType}:${id}`) ?? id
+	}
+
+	/** The persisted id for an entity, or null if it has none yet. */
+	getPersistedId(entityType: string, id: string): string | null {
+		if (isPlaceholderId(id)) return null
+		if (isPersistedId(id)) return id
+		return this.tempToPersisted.get(`${entityType}:${id}`) ?? null
+	}
+
+	/** Whether an entity has never been persisted (no server-assigned id yet). */
+	isNewEntity(entityType: string, id: string): boolean {
+		if (isPlaceholderId(id)) return true
+		if (isPersistedId(id)) return false
+		return !this.tempToPersisted.has(`${entityType}:${id}`)
+	}
+
+	/**
+	 * Migrates an entity from its temp id to its server-assigned id across every
+	 * participating store.
+	 *
+	 * Ordering contract (do not reorder — each step relies on the previous):
+	 *   0. register the redirect, so any resolveKey/resolveId during the fan-out
+	 *      already sees the persisted key;
+	 *   1. roots — keep the root registry aligned;
+	 *   2. entity snapshot — move data, rewrite the id field and id index;
+	 *   3. meta — move metadata/load/persisting, then mark exists-on-server;
+	 *   4. subscriptions — move entity + relation subscribers and parent links;
+	 *   5. relations — rekey owned relation keys, then replace value references;
+	 *   6. errors / touched / propagation — move the remaining per-entity state.
+	 * The caller performs the final notification on the new key.
+	 */
+	rekey(entityType: string, tempId: string, persistedId: string): void {
+		const ctx: RekeyContext = {
+			oldKey: `${entityType}:${tempId}`,
+			newKey: `${entityType}:${persistedId}`,
+			oldKeyPrefix: `${entityType}:${tempId}:`,
+			newKeyPrefix: `${entityType}:${persistedId}:`,
+			oldId: tempId,
+			newId: persistedId,
+		}
+
+		this.tempToPersisted.set(ctx.oldKey, persistedId)
+
+		for (const participant of this.participants) {
+			participant.rekey(ctx)
+		}
+	}
+
+	clear(): void {
+		this.tempToPersisted.clear()
+	}
+}