@contember/bindx 0.1.46 → 0.1.48

package/src/handles/HasOneHandle.ts

@@ -1,6 +1,7 @@
 import { EntityRelatedHandle, embeddedDataMatchesSnapshot } from './BaseHandle.js'
 import type { ActionDispatcher } from '../core/ActionDispatcher.js'
 import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type { StoredRelationState } from '../store/RelationStore.js'
 import type { SchemaRegistry } from '../schema/SchemaRegistry.js'
 import type { SelectionMeta } from '../selection/types.js'
 import {
@@ -17,6 +18,7 @@ import {
 	type Unsubscribe,
 	type EntityAccessor,
 	type HasOneAccessor,
+	type HasOneRelationState,
 } from './types.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -63,6 +65,10 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		private readonly schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		private readonly selection?: SelectionMeta,
+		private readonly dataFieldName: string = fieldName,
+		// Segments from the query root down to this relation; also the entity path
+		// of whatever it resolves to. See FieldRefMeta.fullPath.
+		private readonly relationPath: readonly string[] = [fieldName],
 	) {
 		super(parentEntityType, parentEntityId, store, dispatcher)
 		this.__brands = brands
@@ -78,8 +84,10 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		dataFieldName?: string,
+		relationPath?: readonly string[],
 	): HasOneAccessor<TEntity, TSelected> {
-		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection), (target) => target.entityRaw.fields)
+		return HasOneHandle.wrapProxy(new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection, dataFieldName, relationPath))
 	}
 
 	static createRaw<TEntity extends object = object, TSelected = TEntity>(
@@ -92,12 +100,18 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		dataFieldName?: string,
+		relationPath?: readonly string[],
 	): HasOneHandle<TEntity, TSelected> {
-		return new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection)
+		return new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection, dataFieldName, relationPath)
 	}
 
 	static wrapProxy<TEntity extends object, TSelected>(handle: HasOneHandle<TEntity, TSelected>): HasOneAccessor<TEntity, TSelected> {
-		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(handle, (target) => target.entityRaw.fields)
+		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(
+			handle,
+			(target) => target.entityRaw.fields,
+			(target) => target.entityRaw.selectedFieldNames,
+		)
 	}
 
 	/**
@@ -113,6 +127,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			isArray: false,
 			isRelation: true,
 			targetType: this.targetType,
+			fullPath: this.relationPath,
 		}
 	}
 
@@ -137,51 +152,141 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 
 	/**
 	 * Gets the relation state.
-	 * Falls back to snapshot data when no explicit relation state exists,
-	 * so server-loaded has-one relations report 'connected' without
-	 * requiring a prior RelationStore entry.
+	 * Materializes the RelationStore entry from embedded snapshot data first, so a
+	 * server-loaded has-one reports 'connected' without a prior explicit entry.
 	 */
-	get state(): 'connected' | 'disconnected' | 'deleted' | 'creating' {
-		const relation = this.store.getRelation(
+	get state(): HasOneRelationState {
+		this.ensureEntry()
+		const relation = this.store.getPresentationRelation(
 			this.entityType,
 			this.entityId,
 			this.fieldName,
 		)
-		if (relation) {
-			return relation.state
-		}
-		// No explicit relation state — check if snapshot has embedded data
-		if (this.relatedId !== null) {
-			return 'connected'
-		}
-		return 'disconnected'
+		return relation?.state ?? 'disconnected'
 	}
 
 	/**
-	 * Gets the current related entity ID.
-	 * Falls back to entity data if relation state is not initialized.
+	 * Gets the current related entity ID — read exclusively from the RelationStore
+	 * after materializing the entry from embedded snapshot data.
 	 */
 	get relatedId(): string | null {
-		// First check relation state (for manual changes like connect/disconnect)
-		const relation = this.store.getRelation(
+		this.ensureEntry()
+		const relation = this.store.getPresentationRelation(
 			this.entityType,
 			this.entityId,
 			this.fieldName,
 		)
-		if (relation) {
-			return relation.currentId
+		return relation?.currentId ?? null
+	}
+
+	/**
+	 * Materializes this has-one's RelationStore entry from the parent's embedded
+	 * snapshot data, so the store is the single source of truth (symmetric with
+	 * {@link HasManyListHandle.materializeEmbeddedItems}).
+	 *
+	 * Only the relation entry is touched here — child-snapshot propagation stays in
+	 * {@link ensureRelatedEntitySnapshot}, which owns the per-relation propagation
+	 * slot so the two paths never double-consume it.
+	 *
+	 * - No entry yet + the parent embeds a related object with an id → create a
+	 *   `connected` entry (non-notifying) whose server baseline comes from the
+	 *   parent's serverData, so a freshly loaded relation is not dirty
+	 *   (currentId === serverId, state === serverState).
+	 * - Existing entry + parent re-fetch (embedded reference changed) that is NOT
+	 *   locally dirty → advance the server baseline to the new related id.
+	 * - A local connect/disconnect, a placeholder, or a `creating` entry is left
+	 *   untouched — it is detected as a locally-dirty relation.
+	 * - No embedded data and no entry → the relation stays unmaterialized (null).
+	 */
+	private ensureEntry(): void {
+		const existing = this.store.getRelation(this.entityType, this.entityId, this.fieldName)
+		const embeddedData = this.readEmbeddedRelatedData()
+		const embeddedReference = readEmbeddedRelatedReference(embeddedData)
+
+		if (!existing) {
+			if (embeddedReference.kind !== 'connected') return
+			const serverId = this.readServerRelatedId()
+			this.store.getOrCreateRelation(this.entityType, this.entityId, this.fieldName, {
+				currentId: embeddedReference.id,
+				serverId,
+				state: 'connected',
+				serverState: serverId !== null ? 'connected' : 'disconnected',
+				placeholderData: {},
+			})
+			return
 		}
 
-		// Fallback to entity snapshot data (for server-loaded data)
-		const parentSnapshot = this.store.getEntitySnapshot(this.entityType, this.entityId)
-		if (parentSnapshot?.data) {
-			const relatedData = (parentSnapshot.data as Record<string, unknown>)[this.fieldName]
-			if (relatedData && typeof relatedData === 'object' && 'id' in relatedData) {
-				return (relatedData as { id: string }).id
-			}
+		this.advanceServerBaselineOnRefetch(existing, embeddedReference, embeddedData)
+	}
+
+	/**
+	 * On a parent re-fetch (embedded reference changed) advances the relation's
+	 * server baseline to the embedded related id, but only when the relation is
+	 * not locally dirty — a local connect/disconnect/create must survive a re-fetch.
+	 *
+	 * Does NOT consume the propagation slot — {@link ensureRelatedEntitySnapshot}
+	 * owns it. The same reference-change signal drives both, so both run within the
+	 * one render that observes a new parent reference.
+	 *
+	 * The baseline write is NON-NOTIFYING: it runs during a render-phase read, and
+	 * the parent re-fetch that produced the new embedded reference already notified
+	 * subscribers. Notifying again here would mutate the store and synchronously call
+	 * subscribers mid-render, violating the external-store contract (cf.
+	 * {@link ensureRelatedEntitySnapshot}, which refreshes server data with skipNotify
+	 * for the same reason).
+	 */
+	private advanceServerBaselineOnRefetch(
+		existing: StoredRelationState,
+		embeddedReference: EmbeddedRelatedReference,
+		embeddedData: unknown,
+	): void {
+		if (embeddedReference.kind === 'absent') return
+		if (this.isLocallyDirty(existing)) return
+
+		if (embeddedReference.kind === 'null' && existing.serverId === null && existing.serverState === 'disconnected') {
+			return
 		}
+		if (embeddedReference.kind === 'connected' && existing.serverId === embeddedReference.id && existing.serverState === 'connected') {
+			return
+		}
+		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.dataFieldName, embeddedData)) {
+			return
+		}
+
+		if (embeddedReference.kind === 'null') {
+			this.store.setRelation(this.entityType, this.entityId, this.fieldName, {
+				currentId: null,
+				serverId: null,
+				state: 'disconnected',
+				serverState: 'disconnected',
+			}, true)
+			return
+		}
+
+		this.store.setRelation(this.entityType, this.entityId, this.fieldName, {
+			currentId: embeddedReference.id,
+			serverId: embeddedReference.id,
+			state: 'connected',
+			serverState: 'connected',
+		}, true)
+	}
 
-		return null
+	private isLocallyDirty(relation: StoredRelationState): boolean {
+		return (
+			relation.currentId !== relation.serverId ||
+			relation.state !== relation.serverState ||
+			Object.keys(relation.placeholderData).length > 0
+		)
+	}
+
+	/** Reads the embedded related object from the parent's canonical current data. */
+	private readEmbeddedRelatedData(): unknown {
+		return this.getEntityData()?.[this.dataFieldName]
+	}
+
+	/** Extracts the related id from the parent's embedded server data, or null. */
+	private readServerRelatedId(): string | null {
+		return extractRelatedId(this.getServerData()?.[this.dataFieldName])
 	}
 
 	/**
@@ -222,6 +327,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 					this.schema,
 					this.__brands,
 					this.selection,
+					this.relationPath,
 				)
 				this.entityHandleCacheProxy = EntityHandle.wrapProxy(this.entityHandleCacheRaw)
 			}
@@ -238,6 +344,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 				this.dispatcher,
 				this.schema,
 				this.__brands,
+				this.relationPath,
 			)
 			this.placeholderCacheProxy = PlaceholderHandle.wrapProxy(this.placeholderCacheRaw)
 		}
@@ -289,7 +396,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			return
 		}
 
-		const embeddedData = (parentSnapshot.data as Record<string, unknown>)[this.fieldName]
+		const embeddedData = (parentSnapshot.data as Record<string, unknown>)[this.dataFieldName]
 		if (!embeddedData || typeof embeddedData !== 'object') {
 			return
 		}
@@ -307,7 +414,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		// A new reference means the parent was re-fetched from the server.
 		// Same reference means the embedded data is stale and must not overwrite
 		// child state that may have been updated by a local commit.
-		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.fieldName, embeddedData)) {
+		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.dataFieldName, embeddedData)) {
 			return
 		}
 
@@ -316,7 +423,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		// (e.g. polling). A new reference with identical values means no actual change.
 		const existing = this.store.getEntitySnapshot(this.targetType, id)
 		if (existing?.serverData && embeddedDataMatchesSnapshot(embeddedData as Record<string, unknown>, existing.serverData as Record<string, unknown>)) {
-			this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.fieldName, embeddedData)
+			this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.dataFieldName, embeddedData)
 			return
 		}
 
@@ -331,7 +438,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			embeddedData as Record<string, unknown>,
 			true, // skipNotify - called during render, data already exists embedded in parent
 		)
-		this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.fieldName, embeddedData)
+		this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.dataFieldName, embeddedData)
 	}
 
 	/**
@@ -354,6 +461,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Checks if the relation is dirty.
 	 */
 	get isDirty(): boolean {
+		this.ensureEntry()
 		const relation = this.store.getRelation(
 			this.entityType,
 			this.entityId,
@@ -361,11 +469,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		)
 		if (!relation) return false
 
-		return (
-			relation.currentId !== relation.serverId ||
-			relation.state !== relation.serverState ||
-			Object.keys(relation.placeholderData).length > 0
-		)
+		return this.isLocallyDirty(relation)
 	}
 
 	/**
@@ -374,11 +478,15 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Accessible via proxy as `$create()`.
 	 */
 	create(data?: Partial<TEntity>): string {
-		const tempId = this.store.createEntity(this.targetType, data as Record<string, unknown>)
-		this.dispatcher.dispatch(
-			connectRelation(this.entityType, this.entityId, this.fieldName, tempId, this.targetType),
-		)
-		return tempId
+		// One gesture = one undo entry: the pre-create and the connect are journaled
+		// together so undo removes (and redo re-creates) the created target.
+		return this.store.transaction(() => {
+			const tempId = this.store.createEntity(this.targetType, data as Record<string, unknown>)
+			this.dispatcher.dispatch(
+				connectRelation(this.entityType, this.entityId, this.fieldName, tempId, this.targetType),
+			)
+			return tempId
+		})
 	}
 
 	/**
@@ -574,3 +682,28 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	}
 
 }
+
+type EmbeddedRelatedReference =
+	| { kind: 'absent' }
+	| { kind: 'null' }
+	| { kind: 'connected'; id: string }
+
+/**
+ * Reads an embedded has-one value while preserving explicit null.
+ */
+function readEmbeddedRelatedReference(embedded: unknown): EmbeddedRelatedReference {
+	if (embedded === undefined) return { kind: 'absent' }
+	if (embedded === null) return { kind: 'null' }
+	if (typeof embedded !== 'object' || !('id' in embedded)) return { kind: 'absent' }
+	const id = embedded.id
+	return typeof id === 'string' ? { kind: 'connected', id } : { kind: 'absent' }
+}
+
+/**
+ * Extracts the related entity id from an embedded has-one object, or null when
+ * the value is not an object with a string id.
+ */
+function extractRelatedId(embedded: unknown): string | null {
+	const reference = readEmbeddedRelatedReference(embedded)
+	return reference.kind === 'connected' ? reference.id : null
+}