@contember/bindx 0.1.46 → 0.1.48

package/src/handles/PlaceholderHandle.ts

@@ -44,21 +44,76 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	 * (the first time a child is added to one of its has-many relations). Lazily minted.
 	 */
 	private materializedId: string | null = null
+	private readonly pendingEventSubscriptions = new Set<(entityId: string) => void>()
+	private pendingRelationUnsubscribe: Unsubscribe | null = null
 
 	private constructor(
 		private readonly parentEntityType: string,
-		private readonly parentEntityId: string,
+		private readonly sourceParentEntityId: string,
 		private readonly fieldName: string,
 		private readonly targetType: string,
 		private readonly store: SnapshotStore,
 		private readonly dispatcher: ActionDispatcher,
 		private readonly schema: SchemaRegistry | null,
 		brands?: Set<symbol>,
+		// Segments from the query root down to the relation this placeholder stands in
+		// for, so its field refs carry the same `fullPath` a connected entity would.
+		private readonly relationPath: readonly string[] = [fieldName],
 	) {
 		this.__brands = brands
 		this.placeholderId = generatePlaceholderId()
 	}
 
+	private get parentEntityId(): string {
+		return this.store.resolveEntityId(this.parentEntityType, this.sourceParentEntityId)
+	}
+
+	private get currentEntityId(): string | null {
+		const id = this.findCurrentEntityId()
+		if (id) this.activatePendingEventSubscriptions(id)
+		return id
+	}
+
+	private findCurrentEntityId(): string | null {
+		const relationId = this.store.getRelation(
+			this.parentEntityType,
+			this.parentEntityId,
+			this.fieldName,
+		)?.currentId
+		const sourceId = relationId ?? this.materializedId
+		if (!sourceId) return null
+		const id = this.store.resolveEntityId(this.targetType, sourceId)
+		return this.store.getEntitySnapshot(this.targetType, id) ? id : null
+	}
+
+	private watchPendingMaterialization(): void {
+		if (this.pendingRelationUnsubscribe) return
+		this.pendingRelationUnsubscribe = this.store.subscribeToRelation(
+			this.parentEntityType,
+			this.parentEntityId,
+			this.fieldName,
+			() => {
+				const id = this.findCurrentEntityId()
+				if (id) this.activatePendingEventSubscriptions(id)
+			},
+		)
+	}
+
+	private activatePendingEventSubscriptions(entityId: string): void {
+		if (this.pendingEventSubscriptions.size === 0) return
+		const subscriptions = [...this.pendingEventSubscriptions]
+		this.pendingEventSubscriptions.clear()
+		this.pendingRelationUnsubscribe?.()
+		this.pendingRelationUnsubscribe = null
+		for (const subscribe of subscriptions) subscribe(entityId)
+	}
+
+	private stopWatchingMaterializationWhenIdle(): void {
+		if (this.pendingEventSubscriptions.size > 0) return
+		this.pendingRelationUnsubscribe?.()
+		this.pendingRelationUnsubscribe = null
+	}
+
 	static create<TEntity extends object = object, TSelected = TEntity>(
 		parentEntityType: string,
 		parentEntityId: string,
@@ -68,8 +123,9 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		dispatcher: ActionDispatcher,
 		schema?: SchemaRegistry | null,
 		brands?: Set<symbol>,
+		relationPath?: readonly string[],
 	): EntityAccessor<TEntity, TSelected> {
-		return PlaceholderHandle.wrapProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands))
+		return PlaceholderHandle.wrapProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands, relationPath))
 	}
 
 	static createRaw<TEntity extends object = object, TSelected = TEntity>(
@@ -81,40 +137,63 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		dispatcher: ActionDispatcher,
 		schema?: SchemaRegistry | null,
 		brands?: Set<symbol>,
+		relationPath?: readonly string[],
 	): PlaceholderHandle<TEntity, TSelected> {
-		return new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands)
+		return new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema ?? null, brands, relationPath)
 	}
 
 	static wrapProxy<TEntity extends object, TSelected>(handle: PlaceholderHandle<TEntity, TSelected>): EntityAccessor<TEntity, TSelected> {
 		return createHandleProxy<PlaceholderHandle<TEntity, TSelected>, EntityAccessor<TEntity, TSelected>>(handle, (target) => target.fields)
 	}
 
+	/** A placeholder carries no selection, so enumeration lists nothing beyond `id`. */
+	get selectedFieldNames(): readonly string[] {
+		return []
+	}
+
+	get [FIELD_REF_META](): FieldRefMeta {
+		return {
+			entityType: this.targetType,
+			entityId: this.id,
+			path: [],
+			fieldName: '',
+			isArray: false,
+			isRelation: false,
+		}
+	}
+
 	/**
 	 * Gets the placeholder ID.
 	 */
 	get id(): string {
-		return this.placeholderId
+		return this.currentEntityId ?? this.placeholderId
 	}
 
 	/**
 	 * Gets placeholder data from the relation state.
 	 */
 	get data(): TSelected | null {
-		const relation = this.store.getRelation(
-			this.parentEntityType,
-			this.parentEntityId,
-			this.fieldName,
-		)
-		if (!relation || Object.keys(relation.placeholderData).length === 0) {
-			return null
-		}
-		return relation.placeholderData as TSelected
+		const entityId = this.currentEntityId
+		const data = entityId
+			? this.store.getPresentationSnapshot<TEntity>(this.targetType, entityId)?.data ?? null
+			: this.store.getRelation(
+				this.parentEntityType,
+				this.parentEntityId,
+				this.fieldName,
+			)?.placeholderData ?? null
+		if (data && Object.keys(data).length === 0) return null
+		return data as TSelected | null
 	}
 
 	/**
 	 * Placeholder is dirty if it has any data.
 	 */
 	get isDirty(): boolean {
+		const entityId = this.currentEntityId
+		if (entityId) {
+			return this.store.getDirtyFields(this.targetType, entityId).length > 0 ||
+				this.store.getDirtyRelations(this.targetType, entityId).length > 0
+		}
 		const relation = this.store.getRelation(
 			this.parentEntityType,
 			this.parentEntityId,
@@ -127,21 +206,24 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	 * Placeholder entities are never being persisted.
 	 */
 	get isPersisting(): boolean {
-		return false
+		const entityId = this.currentEntityId
+		return entityId ? this.store.isPersisting(this.targetType, entityId) : false
 	}
 
 	/**
 	 * Placeholder entities are always new (not yet persisted).
 	 */
-	get persistedId(): null {
-		return null
+	get persistedId(): string | null {
+		const entityId = this.currentEntityId
+		return entityId ? this.store.getPersistedId(this.targetType, entityId) : null
 	}
 
 	/**
 	 * Placeholder entities are always new.
 	 */
 	get isNew(): boolean {
-		return true
+		const entityId = this.currentEntityId
+		return entityId ? this.store.isNewEntity(this.targetType, entityId) : true
 	}
 
 	/**
@@ -160,7 +242,7 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	 */
 	private getMaterializedId(): string {
 		if (!this.materializedId) this.materializedId = generateTempId()
-		return this.materializedId
+		return this.store.resolveEntityId(this.targetType, this.materializedId)
 	}
 
 	/**
@@ -213,6 +295,9 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 				this.dispatcher,
 				this.schema,
 				this.__brands,
+				undefined,
+				undefined,
+				[...this.relationPath, fieldName],
 			)
 			// Intercept add() to lazily promote the placeholder to a real entity first — a child
 			// can't belong to a parent that doesn't exist. Reads pass through untouched.
@@ -244,14 +329,19 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 			get [FIELD_REF_META](): FieldRefMeta {
 				return {
 					entityType: self.targetType,
-					entityId: self.placeholderId,
+					entityId: self.id,
 					path: [fieldName],
 					fieldName,
 					isArray: false,
 					isRelation: false,
+					fullPath: [...self.relationPath, fieldName],
 				}
 			},
 			get value(): unknown {
+				const entityId = self.currentEntityId
+				if (entityId) {
+					return self.store.getPresentationSnapshot<Record<string, unknown>>(self.targetType, entityId)?.data[fieldName] ?? null
+				}
 				const relation = self.store.getRelation(
 					self.parentEntityType,
 					self.parentEntityId,
@@ -263,6 +353,10 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 				return null
 			},
 			get isDirty(): boolean {
+				const entityId = self.currentEntityId
+				if (entityId) {
+					return self.store.getDirtyFields(self.targetType, entityId).includes(fieldName)
+				}
 				const relation = self.store.getRelation(
 					self.parentEntityType,
 					self.parentEntityId,
@@ -271,6 +365,16 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 				return fieldName in (relation?.placeholderData ?? {})
 			},
 			setValue: (value: unknown): void => {
+				if (self.currentEntityId) {
+					self.dispatcher.dispatch({
+						type: 'SET_FIELD',
+						entityType: self.targetType,
+						entityId: self.id,
+						fieldPath: [fieldName],
+						value,
+					})
+					return
+				}
 				self.dispatcher.dispatch({
 					type: 'SET_PLACEHOLDER_DATA',
 					entityType: self.parentEntityType,
@@ -282,6 +386,10 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 			},
 			get inputProps() {
 				const getValue = () => {
+					const entityId = self.currentEntityId
+					if (entityId) {
+						return self.store.getPresentationSnapshot<Record<string, unknown>>(self.targetType, entityId)?.data[fieldName] ?? null
+					}
 					const relation = self.store.getRelation(
 						self.parentEntityType,
 						self.parentEntityId,
@@ -290,6 +398,16 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 					return relation?.placeholderData[fieldName] ?? null
 				}
 				const setValue = (value: unknown) => {
+					if (self.currentEntityId) {
+						self.dispatcher.dispatch({
+							type: 'SET_FIELD',
+							entityType: self.targetType,
+							entityId: self.id,
+							fieldPath: [fieldName],
+							value,
+						})
+						return
+					}
 					self.dispatcher.dispatch({
 						type: 'SET_PLACEHOLDER_DATA',
 						entityType: self.parentEntityType,
@@ -347,25 +465,28 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	 */
 	private createPlaceholderHasOneFieldHandle(fieldName: string, innerTargetType: string): unknown {
 		const self = this
+		const nestedRelationPath = [...this.relationPath, fieldName]
 		const nestedPlaceholderRaw = PlaceholderHandle.createRaw(
 			this.targetType,
-			this.placeholderId,
+			this.id,
 			fieldName,
 			innerTargetType,
 			this.store,
 			this.dispatcher,
 			this.schema,
 			this.__brands,
+			nestedRelationPath,
 		)
 		const nestedPlaceholderProxy = PlaceholderHandle.wrapProxy(nestedPlaceholderRaw)
 		const fieldRefMeta: FieldRefMeta = {
 			entityType: self.targetType,
-			entityId: self.placeholderId,
+			entityId: self.id,
 			path: [fieldName],
 			fieldName,
 			isArray: false,
 			isRelation: true,
 			targetType: innerTargetType,
+			fullPath: nestedRelationPath,
 		}
 		const noopUnsubscribe: Unsubscribe = () => {}
 
@@ -464,40 +585,67 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	}
 
 	// ==================== Event Subscriptions ====================
-	// Placeholder entities don't fire events - these are no-ops that return dummy unsubscribe functions
 
 	/**
-	 * No-op for placeholder entities.
+	 * Activates the subscription when the placeholder materializes.
 	 */
 	on<E extends AfterEventTypes>(
-		_eventType: E,
-		_listener: EventListener<EventTypeMap[E]>,
+		eventType: E,
+		listener: EventListener<EventTypeMap[E]>,
 	): Unsubscribe {
-		return () => {}
+		const emitter = this.dispatcher.getEventEmitter()
+		if (this.currentEntityId) {
+			return emitter.onEntity(eventType, this.targetType, this.id, listener)
+		}
+		let unsubscribe: Unsubscribe | null = null
+		const subscribe = (entityId: string): void => {
+			unsubscribe = emitter.onEntity(eventType, this.targetType, entityId, listener)
+		}
+		this.pendingEventSubscriptions.add(subscribe)
+		this.watchPendingMaterialization()
+		return () => {
+			this.pendingEventSubscriptions.delete(subscribe)
+			this.stopWatchingMaterializationWhenIdle()
+			unsubscribe?.()
+		}
 	}
 
 	/**
-	 * No-op for placeholder entities.
+	 * Activates the interceptor when the placeholder materializes.
 	 */
 	intercept<E extends BeforeEventTypes>(
-		_eventType: E,
-		_interceptor: Interceptor<EventTypeMap[E]>,
+		eventType: E,
+		interceptor: Interceptor<EventTypeMap[E]>,
 	): Unsubscribe {
-		return () => {}
+		const emitter = this.dispatcher.getEventEmitter()
+		if (this.currentEntityId) {
+			return emitter.interceptEntity(eventType, this.targetType, this.id, interceptor)
+		}
+		let unsubscribe: Unsubscribe | null = null
+		const subscribe = (entityId: string): void => {
+			unsubscribe = emitter.interceptEntity(eventType, this.targetType, entityId, interceptor)
+		}
+		this.pendingEventSubscriptions.add(subscribe)
+		this.watchPendingMaterialization()
+		return () => {
+			this.pendingEventSubscriptions.delete(subscribe)
+			this.stopWatchingMaterializationWhenIdle()
+			unsubscribe?.()
+		}
 	}
 
 	/**
-	 * No-op for placeholder entities.
+	 * Subscribes to persistence after materialization.
 	 */
-	onPersisted(_listener: EventListener<EntityPersistedEvent>): Unsubscribe {
-		return () => {}
+	onPersisted(listener: EventListener<EntityPersistedEvent>): Unsubscribe {
+		return this.on('entity:persisted', listener)
 	}
 
 	/**
-	 * No-op for placeholder entities.
+	 * Intercepts persistence after materialization.
 	 */
-	interceptPersisting(_interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe {
-		return () => {}
+	interceptPersisting(interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe {
+		return this.intercept('entity:persisting', interceptor)
 	}
 
 }

package/src/handles/index.ts

@@ -27,6 +27,9 @@ export {
 	type HasManyAccessor,
 	type HasOneAccessor,
 	type EntityAccessor,
+	// Selection-erased views (parameter positions that accept any selection)
+	type EntityRefLike,
+	type EntityAccessorLike,
 	type Unsubscribe,
 	// Type extraction helpers
 	type ExtractHasOneEntityName,

package/src/handles/proxyFactory.ts

@@ -24,6 +24,8 @@ const HANDLE_PASSTHROUGH_PROPERTIES = new Set<string | symbol>([
 	FIELD_REF_META,
 ])
 
+const NO_FIELD_NAMES = (): readonly string[] => []
+
 /**
  * Creates a proxy around a handle that supports direct field access.
  *
@@ -33,14 +35,23 @@ const HANDLE_PASSTHROUGH_PROPERTIES = new Set<string | symbol>([
  * 3. `$xxx` → strip `$`, access handle property
  * 4. Everything else → field access (returns FieldHandle/HasOneHandle/HasManyListHandle)
  *
+ * Enumeration (`for…in`, `Object.keys`) sees `id` plus the selected field names, never
+ * the handle's own instance fields: a generic walker (React's dev prop-diff logger,
+ * a debugger) reading those through the `get` trap would hit field access and throw
+ * `UnfetchedFieldError` for `store`, `dispatcher`, ...
+ *
  * @param handle - The handle instance to wrap
  * @param getFields - Function to get the fields object from the handle
+ * @param getFieldNames - Function to list the selected field names (enumeration only)
  * @returns Proxied handle with direct field access support
  */
 export function createHandleProxy<T extends object, TResult = T>(
 	handle: T,
 	getFields: (target: T) => object,
+	getFieldNames: (target: T) => readonly string[] = NO_FIELD_NAMES,
 ): TResult {
+	const ownKeys = (target: T): string[] => ['id', ...getFieldNames(target).filter(name => name !== 'id')]
+
 	// The proxy adds $ alias support and field access, making the handle satisfy the public type TResult at runtime
 	return new Proxy(handle, {
 		get(target, prop, _receiver) {
@@ -76,6 +87,22 @@ export function createHandleProxy<T extends object, TResult = T>(
 			}
 			return Reflect.has(target, prop)
 		},
+
+		ownKeys(target) {
+			return ownKeys(target)
+		},
+
+		getOwnPropertyDescriptor(target, prop) {
+			if (typeof prop !== 'string' || !ownKeys(target).includes(prop)) {
+				return undefined
+			}
+			const value = prop === 'id'
+				? Reflect.get(target, prop, target)
+				: (getFields(target) as Record<string, unknown>)[prop]
+			// Configurable: the target's own properties are configurable too, so the
+			// proxy invariants allow a descriptor that differs from the target's.
+			return { value, enumerable: true, configurable: true, writable: false }
+		},
 	}) as unknown as TResult
 }
 

package/src/handles/types.ts

@@ -364,6 +364,45 @@ export type EntityAccessor<
 	readonly $data: TSelected | null
 } & EntityFieldsAccessor<TEntity, TSelected, TSchema>
 
+// ============================================================================
+// SELECTION-ERASED VIEWS
+// ============================================================================
+
+/**
+ * Selection-erased pointer to an entity of type `TEntity`.
+ *
+ * `EntityRef<TEntity>` means "an entity ref whose selection is the *whole*
+ * entity", so a ref carrying a narrower selection is (correctly) not assignable
+ * to it, and neither is a ref whose selection is still a free type parameter.
+ * Use `EntityRefLike` in parameter positions that only need entity *identity*
+ * and the selection-independent API (`id`, `$isNew`, `$errors`, `$on`, ...) and
+ * accept any selection, including one not yet known:
+ *
+ * ```ts
+ * // accepts EntityRef<Website, anything>
+ * function trackVisit(website: EntityRefLike<Website>): void { ... }
+ * ```
+ *
+ * It deliberately drops the field proxy: erasing the selection must never grant
+ * field access, because reading an unfetched field throws `UnfetchedFieldError`
+ * at runtime. To read fields, take an `EntityRef<TEntity, TSelected>` instead.
+ *
+ * `TEntityName` is erased to `string`, so refs produced with a literal entity
+ * name (hooks) and refs produced without one (createComponent) both fit.
+ */
+export type EntityRefLike<TEntity> = EntityRefInterface<TEntity, unknown>
+
+/**
+ * Selection-erased live accessor for an entity of type `TEntity`.
+ *
+ * Same erasure as {@link EntityRefLike}, but only satisfied by *live* accessors
+ * (`EntityAccessor` and `HasOneAccessor`), not by pointer-only refs. Like
+ * `EntityRefLike` it exposes no field proxy — see the note there.
+ */
+export type EntityAccessorLike<TEntity> = EntityRefLike<TEntity> & {
+	readonly $data: unknown
+}
+
 // ============================================================================
 // ENTITY FIELDS MAPPING TYPES
 // ============================================================================

package/src/index.ts

@@ -67,6 +67,9 @@ export type {
 	HasManyAccessor,
 	HasOneAccessor,
 	EntityAccessor,
+	// Selection-erased views (parameter positions that accept any selection)
+	EntityRefLike,
+	EntityAccessorLike,
 	// Type extraction helpers
 	ExtractHasOneEntityName,
 	ExtractHasManyEntityName,
@@ -237,13 +240,10 @@ export { MutationCollector, ContemberSchemaMutationAdapter, type SchemaNames } f
 export type { MutationSchemaProvider, EntityMutationResult } from './contember/index.js'
 
 // Undo/Redo
-export { UndoManager } from './undo/index.js'
+export { UndoManager, UnrecordedWriteError } from './undo/index.js'
 export type {
 	UndoManagerConfig,
 	UndoState,
-	UndoEntry,
-	PartialStoreSnapshot,
-	StoreAffectedKeys,
 } from './undo/index.js'
 
 // Store types (for undo)