@contember/bindx 0.1.45 → 0.1.47

package/src/events/EventEmitter.ts

@@ -15,6 +15,9 @@ import type {
 	InterceptorResult,
 	Unsubscribe,
 } from './types.js'
+import type { RekeyContext, Rekeyable } from '../store/RekeyOrchestrator.js'
+
+const SCOPE_SEPARATOR = '\u0000'
 
 interface ScopeKey {
 	entityType: string
@@ -31,7 +34,7 @@ interface ScopeKey {
  * - Field-scoped subscriptions (events for a specific field/relation)
  * - Interceptors for before-events (can cancel or modify)
  */
-export class EventEmitter {
+export class EventEmitter implements Rekeyable {
 	// Global listeners by event type
 	private readonly globalListeners = new Map<string, Set<EventListener<AfterEvent>>>()
 
@@ -44,6 +47,9 @@ export class EventEmitter {
 	// Scoped interceptors
 	private readonly scopedInterceptors = new Map<string, Set<Interceptor<BeforeEvent>>>()
 
+	/** Old scope keys retained so pre-rekey unsubscribe closures still resolve. */
+	private readonly scopeKeyRedirects = new Map<string, string>()
+
 	// ============================================================================
 	// Listener Subscription Methods
 	// ============================================================================
@@ -69,10 +75,11 @@ export class EventEmitter {
 		entityId: string,
 		listener: EventListener<EventTypeMap[T] & AfterEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId }))
 		const listeners = this.getOrCreateSet(this.scopedListeners, key)
-		listeners.add(listener as EventListener<AfterEvent>)
-		return () => listeners.delete(listener as EventListener<AfterEvent>)
+		const typedListener = listener as EventListener<AfterEvent>
+		listeners.add(typedListener)
+		return () => this.removeScoped(this.scopedListeners, key, typedListener)
 	}
 
 	/**
@@ -85,10 +92,11 @@ export class EventEmitter {
 		fieldName: string,
 		listener: EventListener<EventTypeMap[T] & AfterEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId, fieldName })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId, fieldName }))
 		const listeners = this.getOrCreateSet(this.scopedListeners, key)
-		listeners.add(listener as EventListener<AfterEvent>)
-		return () => listeners.delete(listener as EventListener<AfterEvent>)
+		const typedListener = listener as EventListener<AfterEvent>
+		listeners.add(typedListener)
+		return () => this.removeScoped(this.scopedListeners, key, typedListener)
 	}
 
 	// ============================================================================
@@ -117,10 +125,11 @@ export class EventEmitter {
 		entityId: string,
 		interceptor: Interceptor<EventTypeMap[T] & BeforeEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId }))
 		const interceptors = this.getOrCreateSet(this.scopedInterceptors, key)
-		interceptors.add(interceptor as Interceptor<BeforeEvent>)
-		return () => interceptors.delete(interceptor as Interceptor<BeforeEvent>)
+		const typedInterceptor = interceptor as Interceptor<BeforeEvent>
+		interceptors.add(typedInterceptor)
+		return () => this.removeScoped(this.scopedInterceptors, key, typedInterceptor)
 	}
 
 	/**
@@ -133,10 +142,23 @@ export class EventEmitter {
 		fieldName: string,
 		interceptor: Interceptor<EventTypeMap[T] & BeforeEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId, fieldName })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId, fieldName }))
 		const interceptors = this.getOrCreateSet(this.scopedInterceptors, key)
-		interceptors.add(interceptor as Interceptor<BeforeEvent>)
-		return () => interceptors.delete(interceptor as Interceptor<BeforeEvent>)
+		const typedInterceptor = interceptor as Interceptor<BeforeEvent>
+		interceptors.add(typedInterceptor)
+		return () => this.removeScoped(this.scopedInterceptors, key, typedInterceptor)
+	}
+
+	/**
+	 * Whether any interceptor could receive this event for the given entity.
+	 * Lets a caller skip the (async) interceptor pipeline when nothing is listening.
+	 */
+	hasInterceptors(eventType: string, entityType: string, entityId: string): boolean {
+		const global = this.globalInterceptors.get(eventType)
+		if (global !== undefined && global.size > 0) return true
+
+		const scoped = this.scopedInterceptors.get(this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId })))
+		return scoped !== undefined && scoped.size > 0
 	}
 
 	// ============================================================================
@@ -162,7 +184,7 @@ export class EventEmitter {
 				fieldName,
 			})
 			const result = await this.runInterceptorSet(
-				this.scopedInterceptors.get(fieldKey),
+				this.scopedInterceptors.get(this.resolveScopeKey(fieldKey)),
 				currentEvent,
 			)
 			if (result === null) return null
@@ -176,7 +198,7 @@ export class EventEmitter {
 			entityId: event.entityId,
 		})
 		const entityResult = await this.runInterceptorSet(
-			this.scopedInterceptors.get(entityKey),
+			this.scopedInterceptors.get(this.resolveScopeKey(entityKey)),
 			currentEvent,
 		)
 		if (entityResult === null) return null
@@ -209,7 +231,7 @@ export class EventEmitter {
 				entityId: event.entityId,
 				fieldName,
 			})
-			this.notifyListeners(this.scopedListeners.get(fieldKey), event)
+			this.notifyListeners(this.scopedListeners.get(this.resolveScopeKey(fieldKey)), event)
 		}
 
 		// Entity-level listeners
@@ -217,7 +239,7 @@ export class EventEmitter {
 			entityType: event.entityType,
 			entityId: event.entityId,
 		})
-		this.notifyListeners(this.scopedListeners.get(entityKey), event)
+		this.notifyListeners(this.scopedListeners.get(this.resolveScopeKey(entityKey)), event)
 
 		// Global listeners
 		this.notifyListeners(this.globalListeners.get(event.type), event)
@@ -231,11 +253,42 @@ export class EventEmitter {
 	 * Builds a scope key for listener/interceptor lookup.
 	 */
 	private buildScopeKey(eventType: string, scope: ScopeKey): string {
-		const parts = [eventType, scope.entityType, scope.entityId]
-		if (scope.fieldName) {
-			parts.push(scope.fieldName)
+		const parts = [eventType, scope.entityType, scope.entityId, scope.fieldName ?? '']
+		return parts.join(SCOPE_SEPARATOR)
+	}
+
+	private resolveScopeKey(key: string): string {
+		let resolved = key
+		let next = this.scopeKeyRedirects.get(resolved)
+		while (next && next !== resolved) {
+			resolved = next
+			next = this.scopeKeyRedirects.get(resolved)
+		}
+		return resolved
+	}
+
+	private removeScoped<T>(map: Map<string, Set<T>>, key: string, value: T): void {
+		map.get(this.resolveScopeKey(key))?.delete(value)
+	}
+
+	rekey(ctx: RekeyContext): void {
+		this.rekeyScopedMap(this.scopedListeners, ctx)
+		this.rekeyScopedMap(this.scopedInterceptors, ctx)
+	}
+
+	private rekeyScopedMap<T>(map: Map<string, Set<T>>, ctx: RekeyContext): void {
+		const entityType = ctx.oldKey.slice(0, ctx.oldKey.length - ctx.oldId.length - 1)
+		const oldIdentity = `${SCOPE_SEPARATOR}${entityType}${SCOPE_SEPARATOR}${ctx.oldId}${SCOPE_SEPARATOR}`
+		const newIdentity = `${SCOPE_SEPARATOR}${entityType}${SCOPE_SEPARATOR}${ctx.newId}${SCOPE_SEPARATOR}`
+
+		for (const [oldScopeKey, values] of [...map]) {
+			if (!oldScopeKey.includes(oldIdentity)) continue
+			const newScopeKey = oldScopeKey.replace(oldIdentity, newIdentity)
+			const destination = this.getOrCreateSet(map, newScopeKey)
+			for (const value of values) destination.add(value)
+			map.delete(oldScopeKey)
+			this.scopeKeyRedirects.set(oldScopeKey, newScopeKey)
 		}
-		return parts.join(':')
 	}
 
 	/**
@@ -297,7 +350,7 @@ export class EventEmitter {
 				fieldName,
 			})
 			const result = this.runInterceptorSetSync(
-				this.scopedInterceptors.get(fieldKey),
+				this.scopedInterceptors.get(this.resolveScopeKey(fieldKey)),
 				currentEvent,
 			)
 			if (result === null) return null
@@ -310,7 +363,7 @@ export class EventEmitter {
 			entityId: event.entityId,
 		})
 		const entityResult = this.runInterceptorSetSync(
-			this.scopedInterceptors.get(entityKey),
+			this.scopedInterceptors.get(this.resolveScopeKey(entityKey)),
 			currentEvent,
 		)
 		if (entityResult === null) return null
@@ -424,6 +477,7 @@ export class EventEmitter {
 		this.scopedListeners.clear()
 		this.globalInterceptors.clear()
 		this.scopedInterceptors.clear()
+		this.scopeKeyRedirects.clear()
 	}
 
 	/**
@@ -437,7 +491,7 @@ export class EventEmitter {
 
 		// Count scoped listeners
 		for (const [key, listeners] of this.scopedListeners) {
-			if (key.startsWith(eventType + ':')) {
+			if (key.startsWith(eventType + SCOPE_SEPARATOR)) {
 				count += listeners.size
 			}
 		}

package/src/handles/BaseHandle.ts

@@ -39,13 +39,18 @@ export abstract class BaseHandle {
 export abstract class EntityRelatedHandle extends BaseHandle {
 	constructor(
 		protected readonly entityType: string,
-		protected readonly entityId: string,
+		private readonly sourceEntityId: string,
 		store: SnapshotStore,
 		dispatcher: ActionDispatcher,
 	) {
 		super(store, dispatcher)
 	}
 
+	/** Current canonical id; the handle keeps no mutable rekey state. */
+	protected get entityId(): string {
+		return this.store.resolveEntityId(this.entityType, this.sourceEntityId)
+	}
+
 	/**
 	 * Subscribe to entity changes.
 	 */
@@ -62,13 +67,25 @@ export abstract class EntityRelatedHandle extends BaseHandle {
 	}
 
 	/**
-	 * Get entity data.
+	 * Get the CANONICAL entity data — the live, possibly-dirty values. Use this
+	 * for dirty tracking and any logic that must reflect the user's edits, even
+	 * while a pessimistic persist is in-flight. For values to DISPLAY, use
+	 * {@link getPresentationData}.
 	 */
 	protected getEntityData(): Record<string, unknown> | undefined {
 		const snapshot = this.store.getEntitySnapshot(this.entityType, this.entityId)
 		return snapshot?.data as Record<string, unknown> | undefined
 	}
 
+	/**
+	 * Get the entity data a consumer should DISPLAY. Equals {@link getEntityData}
+	 * except while the entity is pessimistically in-flight, when it returns the
+	 * server baseline (the canonical data stays dirty underneath).
+	 */
+	protected getPresentationData(): Record<string, unknown> | undefined {
+		return this.store.getPresentationSnapshot<Record<string, unknown>>(this.entityType, this.entityId)?.data
+	}
+
 	/**
 	 * Get entity server data.
 	 */

package/src/handles/EntityHandle.ts

@@ -80,6 +80,9 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		private readonly schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		private readonly selection?: SelectionMeta,
+		// Segments from the query root down to this entity. Empty at a root and at
+		// every has-many item, so item chains restart their own `fullPath`.
+		private readonly entityPath: readonly string[] = [],
 	) {
 		super(entityType, id, store, dispatcher)
 		this.__brands = brands
@@ -93,8 +96,9 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		entityPath?: readonly string[],
 	): EntityAccessor<T, TSelected> {
-		return EntityHandle.wrapProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection))
+		return EntityHandle.wrapProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection, entityPath))
 	}
 
 	static createRaw<T extends object = object, TSelected = T>(
@@ -105,12 +109,26 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		entityPath?: readonly string[],
 	): EntityHandle<T, TSelected> {
-		return new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection)
+		return new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection, entityPath)
 	}
 
 	static wrapProxy<T extends object, TSelected>(handle: EntityHandle<T, TSelected>): EntityAccessor<T, TSelected> {
-		return createHandleProxy<EntityHandle<T, TSelected>, EntityAccessor<T, TSelected>>(handle, (target) => target.fields)
+		return createHandleProxy<EntityHandle<T, TSelected>, EntityAccessor<T, TSelected>>(
+			handle,
+			(target) => target.fields,
+			(target) => target.selectedFieldNames,
+		)
+	}
+
+	/**
+	 * Field names the handle's selection exposes, for enumeration. Without a selection
+	 * nothing is validated and nothing is listed.
+	 */
+	get selectedFieldNames(): readonly string[] {
+		if (!this.selection) return []
+		return [...this.selection.fields.keys()]
 	}
 
 	get [FIELD_REF_META](): FieldRefMeta {
@@ -139,11 +157,14 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	}
 
 	/**
-	 * Gets the current entity data.
+	 * Gets the current entity data to DISPLAY.
 	 * Returns selected fields subset as specified by TSelected type parameter.
+	 * While a pessimistic persist is in-flight this is the server baseline; the
+	 * canonical snapshot (see {@link getSnapshot}, used for dirty tracking) stays
+	 * dirty underneath.
 	 */
 	get data(): TSelected | null {
-		const snapshot = this.getSnapshot()
+		const snapshot = this.store.getPresentationSnapshot<T>(this.entityType, this.entityId)
 		return (snapshot?.data ?? null) as TSelected | null
 	}
 
@@ -251,24 +272,27 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * Gets a field handle for a specific field.
 	 * Returns cached handle to ensure stable identity.
 	 */
-	field<K extends keyof T>(fieldName: K): FieldAccessor<T[K]> {
-		const cacheKey = String(fieldName)
+	field<K extends keyof T>(fieldName: K, dataFieldName = String(fieldName)): FieldAccessor<T[K]> {
+		const schemaFieldName = String(fieldName)
+		const cacheKey = dataFieldName
 		const cached = this.fieldHandleCache.get(cacheKey)
 
 		if (cached) {
 			return cached.proxy as FieldAccessor<T[K]>
 		}
 
-		const enumName = this.schema.getEnumName(this.entityType, cacheKey)
-		const columnType = this.schema.getColumnType(this.entityType, cacheKey)
+		const enumName = this.schema.getEnumName(this.entityType, schemaFieldName)
+		const columnType = this.schema.getColumnType(this.entityType, schemaFieldName)
 		const raw = FieldHandle.createRaw<T[K]>(
 			this.entityType,
 			this.entityId,
-			[cacheKey],
+			[schemaFieldName],
 			this.store,
 			this.dispatcher,
 			enumName,
 			columnType,
+			[dataFieldName],
+			[...this.entityPath, schemaFieldName],
 		)
 		const proxy = FieldHandle.wrapProxy(raw)
 		this.fieldHandleCache.set(cacheKey, { raw, proxy } as CachedFieldHandle)
@@ -279,8 +303,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	/**
 	 * Gets a has-one relation handle.
 	 */
-	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta): HasOneAccessor<TRelated> {
-		const cacheKey = `hasOne:${fieldName}`
+	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta, dataFieldName = fieldName): HasOneAccessor<TRelated> {
+		const cacheKey = `hasOne:${dataFieldName}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
@@ -304,6 +328,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.schema,
 			undefined,
 			nestedSelection,
+			dataFieldName,
+			[...this.entityPath, fieldName],
 		)
 		const proxy = HasOneHandle.wrapProxy(raw)
 		this.relationHandleCache.set(cacheKey, { raw, proxy })
@@ -344,6 +370,7 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.__brands,
 			effectiveAlias,
 			nestedSelection,
+			[...this.entityPath, fieldName],
 		)
 		this.relationHandleCache.set(cacheKey, { raw: handle as unknown as RelationHandleRaw, proxy: handle })
 
@@ -379,6 +406,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.schema,
 			undefined,
 			undefined,
+			undefined,
+			[...this.entityPath, fieldName],
 		)
 		const proxy = HasOneHandle.wrapProxy(raw)
 		this.relationHandleCache.set(cacheKey, { raw, proxy })
@@ -462,29 +491,31 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 				}
 
 				const nestedSelection = fieldMeta?.nested
+				const schemaFieldName = fieldMeta?.fieldName ?? fieldName
+				const dataFieldName = fieldMeta?.alias ?? fieldName
 
 				// Use schema to determine field type
-				const fieldDef = this.schema.getFieldDef(this.entityType, fieldName)
+				const fieldDef = this.schema.getFieldDef(this.entityType, schemaFieldName)
 
 				if (!fieldDef || fieldDef.type === 'scalar') {
 					// Scalar field - return FieldHandle
-					return this.field(fieldName as keyof T)
+					return this.field(schemaFieldName as keyof T, dataFieldName)
 				}
 
 				if (fieldDef.type === 'hasOne') {
 					// Has-one relation - return HasOneHandle
-					return this.hasOne(fieldName, nestedSelection)
+					return this.hasOne(schemaFieldName, nestedSelection, dataFieldName)
 				}
 
 				if (fieldDef.type === 'hasMany') {
 					// Has-many relation - return HasManyListHandle.
 					// Thread the selected alias so the handle reads data stored under the
 					// auto-generated alias (e.g. `tags_<hash>`) for params-bearing relations.
-					return this.hasMany(fieldName, fieldMeta?.alias, nestedSelection)
+					return this.hasMany(schemaFieldName, fieldMeta?.alias, nestedSelection)
 				}
 
 				// Unknown field type - fallback to FieldHandle
-				return this.field(fieldName as keyof T)
+				return this.field(schemaFieldName as keyof T, dataFieldName)
 			},
 		})
 	}

package/src/handles/FieldHandle.ts

@@ -37,6 +37,9 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 		dispatcher: ActionDispatcher,
 		private readonly _enumName?: string,
 		private readonly _columnType?: string,
+		private readonly dataFieldPath: string[] = fieldPath,
+		// Absolute chain from the query root; see FieldRefMeta.fullPath.
+		private readonly _fullPath: readonly string[] = fieldPath,
 	) {
 		super(entityType, entityId, store, dispatcher)
 	}
@@ -49,8 +52,10 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 		dispatcher: ActionDispatcher,
 		enumName?: string,
 		columnType?: string,
+		dataFieldPath?: string[],
+		fullPath?: readonly string[],
 	): FieldAccessor<T> {
-		return createAliasProxy<FieldHandle<T>, FieldAccessor<T>>(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType))
+		return createAliasProxy<FieldHandle<T>, FieldAccessor<T>>(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType, dataFieldPath, fullPath))
 	}
 
 	static createRaw<T = unknown>(
@@ -61,8 +66,10 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 		dispatcher: ActionDispatcher,
 		enumName?: string,
 		columnType?: string,
+		dataFieldPath?: string[],
+		fullPath?: readonly string[],
 	): FieldHandle<T> {
-		return new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType)
+		return new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType, dataFieldPath, fullPath)
 	}
 
 	static wrapProxy<T>(handle: FieldHandle<T>): FieldAccessor<T> {
@@ -83,16 +90,18 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 			isRelation: false,
 			enumName: this._enumName,
 			columnType: this._columnType,
+			fullPath: this._fullPath,
 		}
 	}
 
 	/**
-	 * Gets the current field value.
+	 * Gets the current field value to DISPLAY. While a pessimistic persist is
+	 * in-flight this is the server baseline; otherwise it is the live value.
 	 */
 	get value(): T | null {
-		const data = this.getEntityData()
+		const data = this.getPresentationData()
 		if (!data) return null
-		return getNestedValue(data, this.fieldPath) as T | null
+		return this.getCurrentValue(data) as T | null
 	}
 
 	/**
@@ -101,14 +110,28 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	get serverValue(): T | null {
 		const serverData = this.getServerData()
 		if (!serverData) return null
-		return getNestedValue(serverData, this.fieldPath) as T | null
+		return this.getServerValue(serverData) as T | null
 	}
 
 	/**
-	 * Checks if the field has been modified.
+	 * Checks if the field has been modified. Compares the CANONICAL value against
+	 * the server value — never the presented value, so a field stays correctly
+	 * dirty even while its display shows the server baseline mid-pessimistic-persist.
 	 */
 	get isDirty(): boolean {
-		return !deepEqual(this.value, this.serverValue)
+		const data = this.getEntityData()
+		const value = data ? (this.getCurrentValue(data) as T | null) : null
+		return !deepEqual(value, this.serverValue)
+	}
+
+	private getCurrentValue(data: Record<string, unknown>): unknown {
+		const value = getNestedValue(data, this.fieldPath)
+		return value === undefined ? getNestedValue(data, this.dataFieldPath) : value
+	}
+
+	private getServerValue(data: Record<string, unknown>): unknown {
+		const value = getNestedValue(data, this.fieldPath)
+		return value === undefined ? getNestedValue(data, this.dataFieldPath) : value
 	}
 
 	/**
@@ -217,12 +240,16 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	nested<K extends keyof NonNullable<T>>(
 		key: K,
 	): FieldAccessor<NonNullable<T>[K]> {
+		const fieldName = String(key)
 		return FieldHandle.create<NonNullable<T>[K]>(
 			this.entityType,
 			this.entityId,
-			[...this.fieldPath, key as string],
+			[...this.fieldPath, fieldName],
 			this.store,
 			this.dispatcher,
+			undefined,
+			undefined,
+			[...this.dataFieldPath, fieldName],
 		)
 	}
 
@@ -277,4 +304,3 @@ function getNestedValue(obj: Record<string, unknown>, path: string[]): unknown {
 
 	return current
 }
-