@contember/bindx 0.1.4 → 0.1.8

package/src/handles/EntityHandle.ts

@@ -11,7 +11,7 @@ import {
 	clearEntityErrors,
 	clearAllErrors as clearAllErrorsAction,
 } from '../core/actions.js'
-import { type EntityRef, type SelectedEntityFields, type Unsubscribe, type EntityAccessor } from './types.js'
+import { type FieldRef, type HasOneAccessor, type HasManyRef, type SelectedEntityFields, type Unsubscribe, type EntityAccessor } from './types.js'
 import { deepEqual } from '../utils/deepEqual.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -25,12 +25,21 @@ import type {
 } from '../events/types.js'
 import { HasOneHandle } from './HasOneHandle.js'
 import { HasManyListHandle } from './HasManyListHandle.js'
-import { createHandleProxy, ENTITY_HANDLE_PROPERTIES } from './proxyFactory.js'
+import { createHandleProxy } from './proxyFactory.js'
 import type { SelectionMeta } from '../selection/types.js'
 import { UnfetchedFieldError } from '../errors/UnfetchedFieldError.js'
 
-// Type for relation handle cache
-type RelationHandle = HasOneHandle<object> | HasManyListHandle<object>
+interface CachedHandle<TRaw, TProxy> {
+	readonly raw: TRaw
+	readonly proxy: TProxy
+}
+
+/** Minimal internal interface for cached relation handles that need reset/dispose.
+ * At runtime, the proxied handles satisfy this through delegation, even if the public type doesn't expose dispose(). */
+interface RelationHandleRaw {
+	reset(): void
+	dispose(): void
+}
 
 /**
  * EntityHandle provides stable access to an entity.
@@ -49,35 +58,16 @@ type RelationHandle = HasOneHandle<object> | HasManyListHandle<object>
  * @typeParam T - The full entity type
  * @typeParam TSelected - The selected subset of fields (defaults to T for backwards compatibility)
  */
-export class EntityHandle<T extends object = object, TSelected = T> extends EntityRelatedHandle implements EntityRef<T, TSelected> {
+export class EntityHandle<T extends object = object, TSelected = T> extends EntityRelatedHandle {
 	/** Cache for field handles to ensure stable identity */
-	private readonly fieldHandleCache = new Map<string, FieldHandle<unknown>>()
+	private readonly fieldHandleCache = new Map<string, CachedHandle<FieldHandle<unknown>, FieldRef<unknown>>>()
 
 	/** Cache for relation handles */
-	private readonly relationHandleCache = new Map<string, RelationHandle>()
+	private readonly relationHandleCache = new Map<string, CachedHandle<RelationHandleRaw, HasOneAccessor<object> | HasManyRef<object>>>()
 
 	/** Runtime brand symbols for validation */
 	readonly __brands?: Set<symbol>
 
-	/** Type brand for schema - placeholder at runtime */
-	declare readonly __schema: Record<string, object>
-
-	// $ aliases - handled by proxy at runtime, declared for TypeScript
-	declare readonly $fields: SelectedEntityFields<T, TSelected>
-	declare readonly $data: TSelected | null
-	declare readonly $isDirty: boolean
-	declare readonly $persistedId: string | null
-	declare readonly $isNew: boolean
-	declare readonly $errors: readonly FieldError[]
-	declare readonly $hasError: boolean
-	declare $addError: (error: ErrorInput) => void
-	declare $clearErrors: () => void
-	declare $clearAllErrors: () => void
-	declare $on: <E extends AfterEventTypes>(eventType: E, listener: EventListener<EventTypeMap[E]>) => Unsubscribe
-	declare $intercept: <E extends BeforeEventTypes>(eventType: E, interceptor: Interceptor<EventTypeMap[E]>) => Unsubscribe
-	declare $onPersisted: (listener: EventListener<EntityPersistedEvent>) => Unsubscribe
-	declare $interceptPersisting: (interceptor: Interceptor<EntityPersistingEvent>) => Unsubscribe
-
 	private constructor(
 		id: string,
 		entityType: string,
@@ -99,11 +89,24 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+	): EntityAccessor<T, TSelected> {
+		return EntityHandle.wrapProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection))
+	}
+
+	static createRaw<T extends object = object, TSelected = T>(
+		id: string,
+		entityType: string,
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		schema: SchemaRegistry,
+		brands?: Set<symbol>,
+		selection?: SelectionMeta,
 	): EntityHandle<T, TSelected> {
-		return createHandleProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection), {
-			knownProperties: ENTITY_HANDLE_PROPERTIES,
-			getFields: (target) => target.fields,
-		})
+		return new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection)
+	}
+
+	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)
 	}
 
 	/**
@@ -113,13 +116,6 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		return this.entityId
 	}
 
-	/**
-	 * Gets the entity type.
-	 */
-	get type(): string {
-		return this.entityType
-	}
-
 	/**
 	 * Gets the current entity snapshot.
 	 */
@@ -201,18 +197,18 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			const relationType = this.schema.getRelationType(this.entityType, fieldName)
 
 			if (relationType === 'hasOne') {
-				const handle = this.hasOne(fieldName)
+				const rawHandle = this.getHasOneHandleRaw(fieldName)
 				// Check if the relation itself is dirty (connect/disconnect)
-				if (handle.$isDirty) {
+				if (rawHandle.isDirty) {
 					return true
 				}
 				// Check if the target entity has dirty fields
-				if (handle.$entity.$isDirty) {
+				if (rawHandle.entityRaw.isDirty) {
 					return true
 				}
 			} else if (relationType === 'hasMany') {
-				const handle = this.hasMany(fieldName)
-				if (handle.isDirty) {
+				const rawHandle = this.getHasManyHandleRaw(fieldName)
+				if (rawHandle.isDirty) {
 					return true
 				}
 			}
@@ -240,17 +236,17 @@ 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): FieldHandle<T[K]> {
+	field<K extends keyof T>(fieldName: K): FieldRef<T[K]> {
 		const cacheKey = String(fieldName)
 		const cached = this.fieldHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached as FieldHandle<T[K]>
+			return cached.proxy as FieldRef<T[K]>
 		}
 
 		const enumName = this.schema.getEnumName(this.entityType, cacheKey)
 		const columnType = this.schema.getColumnType(this.entityType, cacheKey)
-		const handle = FieldHandle.create<T[K]>(
+		const raw = FieldHandle.createRaw<T[K]>(
 			this.entityType,
 			this.entityId,
 			[cacheKey],
@@ -259,20 +255,21 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			enumName,
 			columnType,
 		)
-		this.fieldHandleCache.set(cacheKey, handle as FieldHandle<unknown>)
+		const proxy = FieldHandle.wrapProxy(raw)
+		this.fieldHandleCache.set(cacheKey, { raw, proxy } as CachedHandle<FieldHandle<unknown>, FieldRef<unknown>>)
 
-		return handle
+		return proxy
 	}
 
 	/**
 	 * Gets a has-one relation handle.
 	 */
-	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta): HasOneHandle<TRelated> {
+	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta): HasOneAccessor<TRelated> {
 		const cacheKey = `hasOne:${fieldName}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached as HasOneHandle<TRelated>
+			return cached.proxy as HasOneAccessor<TRelated>
 		}
 
 		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
@@ -282,7 +279,7 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			)
 		}
 
-		const handle = HasOneHandle.create<TRelated>(
+		const raw = HasOneHandle.createRaw<TRelated>(
 			this.entityType,
 			this.entityId,
 			fieldName,
@@ -293,9 +290,10 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			undefined,
 			nestedSelection,
 		)
-		this.relationHandleCache.set(cacheKey, handle as RelationHandle)
+		const proxy = HasOneHandle.wrapProxy(raw)
+		this.relationHandleCache.set(cacheKey, { raw, proxy } as unknown as CachedHandle<RelationHandleRaw, HasOneAccessor<object> | HasManyRef<object>>)
 
-		return handle
+		return proxy
 	}
 
 	/**
@@ -304,13 +302,13 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * @param alias - Optional alias for the relation. When the same field is used multiple times
 	 *                with different parameters (filter, orderBy, limit), each needs a unique alias.
 	 */
-	hasMany<TItem extends object>(fieldName: string, alias?: string, nestedSelection?: SelectionMeta): HasManyListHandle<TItem> {
+	hasMany<TItem extends object>(fieldName: string, alias?: string, nestedSelection?: SelectionMeta): HasManyRef<TItem> {
 		const effectiveAlias = alias ?? fieldName
 		const cacheKey = `hasMany:${effectiveAlias}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
-			return cached as HasManyListHandle<TItem>
+			return cached.proxy as HasManyRef<TItem>
 		}
 
 		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
@@ -332,7 +330,79 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			effectiveAlias,
 			nestedSelection,
 		)
-		this.relationHandleCache.set(cacheKey, handle as RelationHandle)
+		this.relationHandleCache.set(cacheKey, { raw: handle, proxy: handle } as unknown as CachedHandle<RelationHandleRaw, HasOneAccessor<object> | HasManyRef<object>>)
+
+		return handle
+	}
+
+	/**
+	 * Gets a raw (unproxied) has-one relation handle from cache.
+	 * Creates the handle if not cached yet.
+	 */
+	private getHasOneHandleRaw(fieldName: string): HasOneHandle<object> {
+		const cacheKey = `hasOne:${fieldName}`
+		const cached = this.relationHandleCache.get(cacheKey)
+
+		if (cached) {
+			return cached.raw as HasOneHandle<object>
+		}
+
+		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
+		if (!targetType) {
+			throw new Error(
+				`Field "${fieldName}" is not a relation on entity "${this.entityType}"`,
+			)
+		}
+
+		const raw = HasOneHandle.createRaw(
+			this.entityType,
+			this.entityId,
+			fieldName,
+			targetType,
+			this.store,
+			this.dispatcher,
+			this.schema,
+			undefined,
+			undefined,
+		)
+		const proxy = HasOneHandle.wrapProxy(raw)
+		this.relationHandleCache.set(cacheKey, { raw, proxy } as unknown as CachedHandle<RelationHandleRaw, HasOneAccessor<object> | HasManyRef<object>>)
+
+		return raw
+	}
+
+	/**
+	 * Gets a raw (unproxied) has-many relation handle from cache.
+	 * Creates the handle if not cached yet.
+	 */
+	private getHasManyHandleRaw(fieldName: string): HasManyRef<object> {
+		const cacheKey = `hasMany:${fieldName}`
+		const cached = this.relationHandleCache.get(cacheKey)
+
+		if (cached) {
+			return cached.proxy as HasManyRef<object>
+		}
+
+		const targetType = this.schema.getRelationTarget(this.entityType, fieldName)
+		if (!targetType) {
+			throw new Error(
+				`Field "${fieldName}" is not a relation on entity "${this.entityType}"`,
+			)
+		}
+
+		const handle = HasManyListHandle.create(
+			this.entityType,
+			this.entityId,
+			fieldName,
+			targetType,
+			this.store,
+			this.dispatcher,
+			this.schema,
+			this.__brands,
+			fieldName,
+			undefined,
+		)
+		this.relationHandleCache.set(cacheKey, { raw: handle, proxy: handle } as unknown as CachedHandle<RelationHandleRaw, HasOneAccessor<object> | HasManyRef<object>>)
 
 		return handle
 	}
@@ -346,8 +416,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		this.dispatcher.dispatch(resetEntity(this.entityType, this.entityId))
 
 		// Reset all cached relation handles
-		for (const handle of this.relationHandleCache.values()) {
-			handle.reset()
+		for (const { raw } of this.relationHandleCache.values()) {
+			raw.reset()
 		}
 	}
 
@@ -365,13 +435,13 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	override dispose(): void {
 		super.dispose()
 
-		for (const handle of this.fieldHandleCache.values()) {
-			handle.dispose()
+		for (const { raw } of this.fieldHandleCache.values()) {
+			raw.dispose()
 		}
 		this.fieldHandleCache.clear()
 
-		for (const handle of this.relationHandleCache.values()) {
-			handle.dispose()
+		for (const { raw } of this.relationHandleCache.values()) {
+			raw.dispose()
 		}
 		this.relationHandleCache.clear()
 	}

package/src/handles/FieldHandle.ts

@@ -23,7 +23,7 @@ import { createAliasProxy } from './proxyFactory.js'
  * - Provides inputProps for form integration
  * - Implements FieldRef interface for JSX compatibility
  */
-export class FieldHandle<T = unknown> extends EntityRelatedHandle implements FieldRef<T> {
+export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	private _cachedInputProps: InputProps<T> | null = null
 	private _cachedInputPropsValue: T | null | undefined = undefined
 
@@ -49,8 +49,24 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle implements Fie
 		dispatcher: ActionDispatcher,
 		enumName?: string,
 		columnType?: string,
+	): FieldRef<T> {
+		return createAliasProxy<FieldHandle<T>, FieldRef<T>>(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType))
+	}
+
+	static createRaw<T = unknown>(
+		entityType: string,
+		entityId: string,
+		fieldPath: string[],
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		enumName?: string,
+		columnType?: string,
 	): FieldHandle<T> {
-		return createAliasProxy(new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType))
+		return new FieldHandle<T>(entityType, entityId, fieldPath, store, dispatcher, enumName, columnType)
+	}
+
+	static wrapProxy<T>(handle: FieldHandle<T>): FieldRef<T> {
+		return createAliasProxy<FieldHandle<T>, FieldRef<T>>(handle)
 	}
 
 	/**
@@ -204,7 +220,7 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle implements Fie
 	 */
 	nested<K extends keyof NonNullable<T>>(
 		key: K,
-	): FieldHandle<NonNullable<T>[K]> {
+	): FieldRef<NonNullable<T>[K]> {
 		return FieldHandle.create<NonNullable<T>[K]>(
 			this.entityType,
 			this.entityId,

package/src/handles/HasManyListHandle.ts

@@ -27,8 +27,9 @@ import { createAliasProxy } from './proxyFactory.js'
  * @typeParam TEntity - The full entity type of items in the relation
  * @typeParam TSelected - The selected subset of fields (defaults to TEntity for backwards compatibility)
  */
-export class HasManyListHandle<TEntity extends object = object, TSelected = TEntity> extends EntityRelatedHandle implements HasManyRef<TEntity, TSelected> {
-	private itemHandleCache = new Map<string, EntityHandle<TEntity, TSelected>>()
+export class HasManyListHandle<TEntity extends object = object, TSelected = TEntity> extends EntityRelatedHandle {
+	private itemHandleCacheRaw = new Map<string, EntityHandle<TEntity, TSelected>>()
+	private itemHandleCacheProxy = new Map<string, EntityAccessor<TEntity, TSelected>>()
 
 	/** Runtime brand symbols for validation */
 	readonly __brands?: Set<symbol>
@@ -84,8 +85,8 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		brands?: Set<symbol>,
 		alias?: string,
 		selection?: SelectionMeta,
-	): HasManyListHandle<TEntity, TSelected> {
-		return createAliasProxy(new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection))
+	): HasManyRef<TEntity, TSelected> {
+		return createAliasProxy<HasManyListHandle<TEntity, TSelected>, HasManyRef<TEntity, TSelected>>(new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection))
 	}
 
 	/**
@@ -221,10 +222,10 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Returns selection-aware EntityAccessor that supports direct field access.
 	 */
 	getItemHandle(itemId: string): EntityAccessor<TEntity, TSelected> {
-		let handle = this.itemHandleCache.get(itemId)
+		let proxy = this.itemHandleCacheProxy.get(itemId)
 
-		if (!handle) {
-			handle = EntityHandle.create<TEntity, TSelected>(
+		if (!proxy) {
+			const raw = EntityHandle.createRaw<TEntity, TSelected>(
 				itemId,
 				this.itemType,
 				this.store,
@@ -233,11 +234,12 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 				this.__brands,
 				this.selection,
 			)
-			this.itemHandleCache.set(itemId, handle)
+			proxy = EntityHandle.wrapProxy(raw)
+			this.itemHandleCacheRaw.set(itemId, raw)
+			this.itemHandleCacheProxy.set(itemId, proxy)
 		}
 
-		// EntityHandle constructor returns a Proxy that implements EntityAccessor
-		return handle as unknown as EntityAccessor<TEntity, TSelected>
+		return proxy
 	}
 
 	/**
@@ -391,10 +393,11 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	override dispose(): void {
 		super.dispose()
 
-		for (const handle of this.itemHandleCache.values()) {
+		for (const handle of this.itemHandleCacheRaw.values()) {
 			handle.dispose()
 		}
-		this.itemHandleCache.clear()
+		this.itemHandleCacheRaw.clear()
+		this.itemHandleCacheProxy.clear()
 	}
 
 	/**