@contember/bindx 0.1.5 → 0.1.9

package/src/handles/HasOneHandle.ts

@@ -12,11 +12,11 @@ import {
 } from '../core/actions.js'
 import {
 	FIELD_REF_META,
-	type HasOneRef,
 	type FieldRefMeta,
 	type SelectedEntityFields,
 	type Unsubscribe,
 	type EntityAccessor,
+	type HasOneAccessor,
 } from './types.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -34,7 +34,7 @@ import type {
 } from '../events/types.js'
 import { EntityHandle } from './EntityHandle.js'
 import { PlaceholderHandle } from './PlaceholderHandle.js'
-import { createHandleProxy, HAS_ONE_HANDLE_PROPERTIES } from './proxyFactory.js'
+import { createHandleProxy } from './proxyFactory.js'
 
 
 /**
@@ -44,35 +44,15 @@ import { createHandleProxy, HAS_ONE_HANDLE_PROPERTIES } from './proxyFactory.js'
  * @typeParam TEntity - The full entity type of the related entity
  * @typeParam TSelected - The selected subset of fields (defaults to TEntity for backwards compatibility)
  */
-export class HasOneHandle<TEntity extends object = object, TSelected = TEntity> extends EntityRelatedHandle implements HasOneRef<TEntity, TSelected> {
-	private entityHandleCache: EntityHandle<TEntity, TSelected> | null = null
-	private placeholderCache: PlaceholderHandle<TEntity, TSelected> | null = null
+export class HasOneHandle<TEntity extends object = object, TSelected = TEntity> extends EntityRelatedHandle {
+	private entityHandleCacheRaw: EntityHandle<TEntity, TSelected> | null = null
+	private entityHandleCacheProxy: EntityAccessor<TEntity, TSelected> | null = null
+	private placeholderCacheRaw: PlaceholderHandle<TEntity, TSelected> | null = null
+	private placeholderCacheProxy: EntityAccessor<TEntity, TSelected> | null = null
 
 	/** 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 $id: string
-	declare readonly $isDirty: boolean
-	declare readonly $state: 'connected' | 'disconnected' | 'deleted' | 'creating'
-	declare readonly $fields: SelectedEntityFields<TEntity, TSelected>
-	declare readonly $entity: EntityAccessor<TEntity, TSelected>
-	declare readonly $errors: readonly FieldError[]
-	declare readonly $hasError: boolean
-	declare $connect: (id: string) => void
-	declare $disconnect: () => void
-	declare $delete: () => void
-	declare $reset: () => void
-	declare $addError: (error: ErrorInput) => void
-	declare $clearErrors: () => void
-	declare $onConnect: (listener: EventListener<RelationConnectedEvent>) => Unsubscribe
-	declare $onDisconnect: (listener: EventListener<RelationDisconnectedEvent>) => Unsubscribe
-	declare $interceptConnect: (interceptor: Interceptor<RelationConnectingEvent>) => Unsubscribe
-	declare $interceptDisconnect: (interceptor: Interceptor<RelationDisconnectingEvent>) => Unsubscribe
-
 	private constructor(
 		parentEntityType: string,
 		parentEntityId: string,
@@ -98,11 +78,26 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+	): 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)
+	}
+
+	static createRaw<TEntity extends object = object, TSelected = TEntity>(
+		parentEntityType: string,
+		parentEntityId: string,
+		fieldName: string,
+		targetType: string,
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		schema: SchemaRegistry,
+		brands?: Set<symbol>,
+		selection?: SelectionMeta,
 	): HasOneHandle<TEntity, TSelected> {
-		return createHandleProxy(new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection), {
-			knownProperties: HAS_ONE_HANDLE_PROPERTIES,
-			getFields: (target) => target.entity.$fields,
-		})
+		return new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection)
+	}
+
+	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)
 	}
 
 	/**
@@ -198,21 +193,18 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	}
 
 	/**
-	 * Gets the related entity accessor with direct field access.
-	 * Implements HasOneRef.$entity - returns EntityAccessor for the related entity.
-	 * Returns PlaceholderHandle (with placeholder ID) if the relation is disconnected.
+	 * Gets the raw (unproxied) related entity handle.
+	 * Returns raw EntityHandle or raw PlaceholderHandle.
+	 * Used internally to avoid going through the proxy layer.
 	 */
-	get entity(): EntityAccessor<TEntity, TSelected> {
+	get entityRaw(): EntityHandle<TEntity, TSelected> | PlaceholderHandle<TEntity, TSelected> {
 		const id = this.relatedId
 
 		if (id) {
-			// Ensure the related entity has a snapshot in the store
-			// (it may be embedded in the parent entity's data)
 			this.ensureRelatedEntitySnapshot(id)
 
-			// Connected - return real entity handle
-			if (!this.entityHandleCache || this.entityHandleCache.id !== id) {
-				this.entityHandleCache = EntityHandle.create<TEntity, TSelected>(
+			if (!this.entityHandleCacheRaw || this.entityHandleCacheRaw.id !== id) {
+				this.entityHandleCacheRaw = EntityHandle.createRaw<TEntity, TSelected>(
 					id,
 					this.targetType,
 					this.store,
@@ -221,14 +213,13 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 					this.__brands,
 					this.selection,
 				)
+				this.entityHandleCacheProxy = EntityHandle.wrapProxy(this.entityHandleCacheRaw)
 			}
-			// EntityHandle constructor returns a Proxy that implements EntityAccessor
-			return this.entityHandleCache as unknown as EntityAccessor<TEntity, TSelected>
+			return this.entityHandleCacheRaw
 		}
 
-		// Disconnected - return placeholder handle
-		if (!this.placeholderCache) {
-			this.placeholderCache = PlaceholderHandle.create<TEntity, TSelected>(
+		if (!this.placeholderCacheRaw) {
+			this.placeholderCacheRaw = PlaceholderHandle.createRaw<TEntity, TSelected>(
 				this.entityType,
 				this.entityId,
 				this.fieldName,
@@ -237,9 +228,38 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 				this.dispatcher,
 				this.__brands,
 			)
+			this.placeholderCacheProxy = PlaceholderHandle.wrapProxy(this.placeholderCacheRaw)
+		}
+		return this.placeholderCacheRaw
+	}
+
+	/**
+	 * Gets the related entity accessor with direct field access.
+	 * Implements HasOneRef.$entity - returns EntityAccessor for the related entity.
+	 * Returns PlaceholderHandle (with placeholder ID) if the relation is disconnected.
+	 */
+	get entity(): EntityAccessor<TEntity, TSelected> {
+		const id = this.relatedId
+
+		if (id) {
+			// Ensure the related entity has a snapshot in the store
+			// (it may be embedded in the parent entity's data)
+			this.ensureRelatedEntitySnapshot(id)
+
+			// Connected - return real entity handle (populate raw cache via entityRaw if needed)
+			if (!this.entityHandleCacheRaw || this.entityHandleCacheRaw.id !== id) {
+				// entityRaw populates both raw and proxy caches
+				this.entityRaw
+			}
+			return this.entityHandleCacheProxy!
+		}
+
+		// Disconnected - return placeholder handle
+		if (!this.placeholderCacheRaw) {
+			// entityRaw populates both raw and proxy caches
+			this.entityRaw
 		}
-		// PlaceholderHandle implements EntityRef but for API consistency return as EntityAccessor
-		return this.placeholderCache as unknown as EntityAccessor<TEntity, TSelected>
+		return this.placeholderCacheProxy!
 	}
 
 	/**
@@ -288,6 +308,15 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		)
 	}
 
+	/**
+	 * Checks if the related entity is currently being persisted.
+	 */
+	get isPersisting(): boolean {
+		const id = this.relatedId
+		if (!id) return false
+		return this.store.isPersisting(this.targetType, id)
+	}
+
 	/**
 	 * Checks if the relation is dirty.
 	 */
@@ -349,8 +378,11 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 */
 	override dispose(): void {
 		super.dispose()
-		this.entityHandleCache?.dispose()
-		this.entityHandleCache = null
+		this.entityHandleCacheRaw?.dispose()
+		this.entityHandleCacheRaw = null
+		this.entityHandleCacheProxy = null
+		this.placeholderCacheRaw = null
+		this.placeholderCacheProxy = null
 	}
 
 	/**
@@ -454,47 +486,47 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	}
 
 	// ==================== EntityRef-compatible Properties ====================
-	// These make HasOneAccessor structurally compatible with EntityAccessor
+	// These delegate to entityRaw so that proxy resolution ($data→data, $isNew→isNew, etc.) works correctly.
 
-	/** Raw data snapshot of the related entity - delegates to $entity */
-	get $data(): TSelected | null { return this.entity.$data }
+	/** Raw data snapshot of the related entity - delegates to entityRaw */
+	get data(): TSelected | null { return this.entityRaw.data }
 
-	/** Whether this entity is new - delegates to $entity */
-	get $isNew(): boolean { return this.entity.$isNew }
+	/** Whether this entity is new - delegates to entityRaw */
+	get isNew(): boolean { return this.entityRaw.isNew }
 
-	/** Server-assigned ID after persistence - delegates to $entity */
-	get $persistedId(): string | null { return this.entity.$persistedId }
+	/** Server-assigned ID after persistence - delegates to entityRaw */
+	get persistedId(): string | null { return this.entityRaw.persistedId }
 
 	/** Type brand for entity name */
 	get __entityName(): string { return this.targetType }
 
-	/** Clear all errors - delegates to $entity */
-	$clearAllErrors(): void { this.entity.$clearAllErrors() }
+	/** Clear all errors - delegates to entityRaw */
+	clearAllErrors(): void { this.entityRaw.clearAllErrors() }
 
 	/** Subscribe to any event on the related entity */
-	$on<E extends AfterEventTypes>(
+	on<E extends AfterEventTypes>(
 		eventType: E,
 		listener: EventListener<EventTypeMap[E]>,
 	): Unsubscribe {
-		return this.entity.$on(eventType, listener)
+		return this.entityRaw.on(eventType, listener)
 	}
 
 	/** Intercept any before event on the related entity */
-	$intercept<E extends BeforeEventTypes>(
+	intercept<E extends BeforeEventTypes>(
 		eventType: E,
 		interceptor: Interceptor<EventTypeMap[E]>,
 	): Unsubscribe {
-		return this.entity.$intercept(eventType, interceptor)
+		return this.entityRaw.intercept(eventType, interceptor)
 	}
 
 	/** Subscribe to persist success events on the related entity */
-	$onPersisted(listener: EventListener<EntityPersistedEvent>): Unsubscribe {
-		return this.entity.$onPersisted(listener)
+	onPersisted(listener: EventListener<EntityPersistedEvent>): Unsubscribe {
+		return this.entityRaw.onPersisted(listener)
 	}
 
 	/** Intercept persist on the related entity */
-	$interceptPersisting(interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe {
-		return this.entity.$interceptPersisting(interceptor)
+	interceptPersisting(interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe {
+		return this.entityRaw.interceptPersisting(interceptor)
 	}
 
 }

package/src/handles/PlaceholderHandle.ts

@@ -3,10 +3,10 @@ import type { SnapshotStore } from '../store/SnapshotStore.js'
 import { generatePlaceholderId } from '../store/SnapshotStore.js'
 import {
 	FIELD_REF_META,
-	type EntityRef,
 	type SelectedEntityFields,
 	type FieldRefMeta,
 	type Unsubscribe,
+	type EntityAccessor,
 } from './types.js'
 import type { ErrorInput, FieldError } from '../errors/types.js'
 import type {
@@ -28,34 +28,13 @@ import { createAliasProxy } from './proxyFactory.js'
  * @typeParam TEntity - The full entity type
  * @typeParam TSelected - The selected subset of fields
  */
-export class PlaceholderHandle<TEntity extends object = object, TSelected = TEntity>
-	implements EntityRef<TEntity, TSelected>
-{
+export class PlaceholderHandle<TEntity extends object = object, TSelected = TEntity> {
 	/** Runtime brand symbols for validation */
 	readonly __brands?: Set<symbol>
 
-	/** Type brand for schema - placeholder at runtime */
-	declare readonly __schema: Record<string, object>
-
 	/** Placeholder ID for this handle */
 	private readonly placeholderId: string
 
-	// $ aliases - handled by proxy at runtime, declared for TypeScript
-	declare readonly $fields: SelectedEntityFields<TEntity, TSelected>
-	declare readonly $data: TSelected | null
-	declare readonly $isDirty: boolean
-	declare readonly $persistedId: 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(
 		private readonly parentEntityType: string,
 		private readonly parentEntityId: string,
@@ -77,8 +56,24 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		store: SnapshotStore,
 		dispatcher: ActionDispatcher,
 		brands?: Set<symbol>,
+	): EntityAccessor<TEntity, TSelected> {
+		return PlaceholderHandle.wrapProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands))
+	}
+
+	static createRaw<TEntity extends object = object, TSelected = TEntity>(
+		parentEntityType: string,
+		parentEntityId: string,
+		fieldName: string,
+		targetType: string,
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		brands?: Set<symbol>,
 	): PlaceholderHandle<TEntity, TSelected> {
-		return createAliasProxy(new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands))
+		return new PlaceholderHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, brands)
+	}
+
+	static wrapProxy<TEntity extends object, TSelected>(handle: PlaceholderHandle<TEntity, TSelected>): EntityAccessor<TEntity, TSelected> {
+		return createAliasProxy<PlaceholderHandle<TEntity, TSelected>, EntityAccessor<TEntity, TSelected>>(handle)
 	}
 
 	/**
@@ -115,6 +110,13 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		return relation ? Object.keys(relation.placeholderData).length > 0 : false
 	}
 
+	/**
+	 * Placeholder entities are never being persisted.
+	 */
+	get isPersisting(): boolean {
+		return false
+	}
+
 	/**
 	 * Placeholder entities are always new (not yet persisted).
 	 */

package/src/handles/proxyFactory.ts

@@ -8,132 +8,40 @@
  * The $ prefix convention allows handle properties to avoid collision with entity field names:
  * - `entity.title` → field access (returns FieldHandle)
  * - `entity.$isDirty` → handle property
+ * - `entity.id` → entity ID (special case, always passes through)
  */
 
 import { FIELD_REF_META } from './types.js'
 
 /**
- * Shared base properties for entity-like handles (EntityHandle, HasOneHandle).
- * Extracting a common set prevents bugs from inconsistent maintenance (e.g. missing `id`).
+ * Properties that always pass through to the handle, never treated as field access.
+ * Kept minimal to avoid collisions with entity field names.
  */
-const BASE_ENTITY_PROPERTIES: (string | symbol)[] = [
-	// Entity identity — id is always the entity ID, not a field handle
+const HANDLE_PASSTHROUGH_PROPERTIES = new Set<string | symbol>([
+	// Entity identity — `entity.id` must return the entity ID string, not a FieldHandle
 	'id',
-	// Type brands (phantom types)
-	'__entityType', '__entityName', '__brands', '__schema',
-	// Symbol
+	// Symbol for field reference metadata
 	FIELD_REF_META,
-	// Core internals shared by all entity-like handles
-	'entityType', 'entityId', 'store', 'dispatcher', 'schema',
-	'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
-	'dispose', 'subscribe',
-]
-
-/**
- * Known properties on EntityHandle that should NOT be treated as field access.
- * Properties like `fields`, `data`, `errors` are NOT included - use $ prefix for those.
- */
-export const ENTITY_HANDLE_PROPERTIES = new Set<string | symbol>([
-	...BASE_ENTITY_PROPERTIES,
-	// Entity-specific internals
-	'type', 'fieldHandleCache', 'relationHandleCache',
-	// Internal methods (unlikely to be field names)
-	'field', 'hasOne', 'hasMany', 'getSnapshot',
-	'reset', 'commit',
-	'getDirtyFields', 'getDirtyRelations',
-	// State properties (unlikely to be field names)
-	'serverData', 'isLoaded', 'isLoading', 'isError', 'error', 'isPersisting',
-])
-
-/**
- * Known properties on HasOneHandle that should NOT be treated as field access.
- * Properties like `fields`, `entity`, `errors`, `state` are NOT included - they require $ prefix.
- */
-export const HAS_ONE_HANDLE_PROPERTIES = new Set<string | symbol>([
-	...BASE_ENTITY_PROPERTIES,
-	// HasOne-specific internals
-	'fieldName', 'targetType',
-	'entityHandleCache', 'placeholderCache', 'ensureRelatedEntitySnapshot', 'relatedId',
-	// Methods that are unlikely to be field names
-	'connect', 'disconnect', 'delete', 'reset',
-])
-
-/**
- * All properties on FieldHandle (no field access proxy needed, just $ aliasing).
- */
-export const FIELD_HANDLE_PROPERTIES = new Set<string | symbol>([
-	FIELD_REF_META,
-	// Core properties
-	'value', 'serverValue', 'isDirty', 'inputProps', 'errors', 'hasError',
-	'path', 'fieldName',
-	// Methods
-	'setValue', 'addError', 'clearErrors', 'onChange', 'onChanging', 'nested',
-	// Internal
-	'entityType', 'entityId', 'fieldPath', 'store', 'dispatcher',
-	'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
-	'subscribe', 'dispose',
-])
-
-/**
- * All properties on HasManyListHandle (no field access proxy needed, just $ aliasing).
- */
-export const HAS_MANY_HANDLE_PROPERTIES = new Set<string | symbol>([
-	FIELD_REF_META,
-	// Type brands
-	'__entityType', '__brands',
-	// Core properties
-	'items', 'length', 'isDirty', 'errors', 'hasError',
-	// Methods
-	'map', 'add', 'remove', 'move', 'connect', 'disconnect', 'reset',
-	'getItemHandle', 'addError', 'clearErrors',
-	'onItemConnected', 'onItemDisconnected', 'interceptItemConnecting', 'interceptItemDisconnecting',
-	// Internal
-	'entityType', 'entityId', 'fieldName', 'itemType', 'store', 'dispatcher', 'schema',
-	'itemHandleCache', 'getEntityData', 'getServerData', 'assertNotDisposed', 'isDisposed',
-	'subscribe', 'dispose', 'ensureItemSnapshots',
 ])
 
-/**
- * All properties on PlaceholderHandle (no field access proxy needed, just $ aliasing).
- */
-export const PLACEHOLDER_HANDLE_PROPERTIES = new Set<string | symbol>([
-	// Core properties
-	'id', 'data', 'isDirty', 'persistedId', 'isNew', 'fields', 'errors', 'hasError',
-	// Type brands
-	'__entityType', '__entityName', '__brands',
-	// Methods
-	'addError', 'clearErrors', 'clearAllErrors',
-	'on', 'intercept', 'onPersisted', 'interceptPersisting',
-	// Internal
-	'parentEntityType', 'parentEntityId', 'fieldName', 'targetType', 'store', 'dispatcher',
-	'placeholderId', 'createPlaceholderFieldHandle',
-])
-
-/**
- * Configuration for creating a handle proxy.
- */
-export interface HandleProxyConfig<T extends object> {
-	/** Set of property names that should pass through to the handle */
-	knownProperties: Set<string | symbol>
-	/** Function to get the fields proxy from the handle */
-	getFields: (target: T) => object
-}
-
 /**
  * Creates a proxy around a handle that supports direct field access.
  *
- * - `handle.fieldName` is equivalent to `handle.$fields.fieldName`
- * - `handle.$propertyName` accesses handle properties with $ prefix stripped
- * - Known properties pass through directly to the handle
+ * Resolution order:
+ * 1. Symbols → pass through to handle
+ * 2. `id` / FIELD_REF_META → pass through to handle
+ * 3. `$xxx` → strip `$`, access handle property
+ * 4. Everything else → field access (returns FieldHandle/HasOneHandle/HasManyListHandle)
  *
  * @param handle - The handle instance to wrap
- * @param config - Configuration for the proxy
+ * @param getFields - Function to get the fields object from the handle
  * @returns Proxied handle with direct field access support
  */
-export function createHandleProxy<T extends object>(
+export function createHandleProxy<T extends object, TResult = T>(
 	handle: T,
-	config: HandleProxyConfig<T>,
-): T {
+	getFields: (target: T) => object,
+): TResult {
+	// 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) {
 			// Symbols and non-string props - pass through
@@ -141,41 +49,34 @@ export function createHandleProxy<T extends object>(
 				return Reflect.get(target, prop, target)
 			}
 
+			// Special properties that always pass through
+			if (HANDLE_PASSTHROUGH_PROPERTIES.has(prop)) {
+				return Reflect.get(target, prop, target)
+			}
+
 			// $ prefixed - strip $ and access handle property
 			if (prop.startsWith('$')) {
 				const realProp = prop.slice(1)
-				// Use target as receiver so getters use target as `this`, not the Proxy
 				const value = Reflect.get(target, realProp, target)
-				// Bind methods to preserve `this`
-				if (typeof value === 'function') {
-					return value.bind(target)
-				}
-				return value
-			}
-
-			// Known handle properties - pass through for backwards compatibility
-			if (config.knownProperties.has(prop)) {
-				const value = Reflect.get(target, prop, target)
 				if (typeof value === 'function') {
 					return value.bind(target)
 				}
 				return value
 			}
 
-			// Otherwise, treat as field access
-			const fields = config.getFields(target)
+			// Everything else → field access
+			const fields = getFields(target)
 			return (fields as Record<string, unknown>)[prop]
 		},
 
 		has(target, prop) {
-			if (typeof prop === 'string' && !config.knownProperties.has(prop) && !prop.startsWith('$')) {
-				// Check if it's a field
-				const fields = config.getFields(target)
+			if (typeof prop === 'string' && !HANDLE_PASSTHROUGH_PROPERTIES.has(prop) && !prop.startsWith('$')) {
+				const fields = getFields(target)
 				return prop in fields
 			}
 			return Reflect.has(target, prop)
 		},
-	})
+	}) as unknown as TResult
 }
 
 /**
@@ -188,7 +89,8 @@ export function createHandleProxy<T extends object>(
  * @param handle - The handle instance to wrap
  * @returns Proxied handle with $ alias support
  */
-export function createAliasProxy<T extends object>(handle: T): T {
+export function createAliasProxy<T extends object, TResult = T>(handle: T): TResult {
+	// The proxy adds $ alias support, making the handle satisfy the public type TResult at runtime
 	return new Proxy(handle, {
 		get(target, prop, _receiver) {
 			// Symbols and non-string props - pass through
@@ -200,7 +102,6 @@ export function createAliasProxy<T extends object>(handle: T): T {
 			if (prop.startsWith('$')) {
 				const realProp = prop.slice(1)
 				const value = Reflect.get(target, realProp, target)
-				// Bind methods to preserve `this`
 				if (typeof value === 'function') {
 					return value.bind(target)
 				}
@@ -214,5 +115,5 @@ export function createAliasProxy<T extends object>(handle: T): T {
 			}
 			return value
 		},
-	})
+	}) as unknown as TResult
 }

package/src/handles/types.ts

@@ -396,6 +396,9 @@ export interface HasOneRefBase<
 	/** Whether this entity is new */
 	readonly $isNew: boolean
 
+	/** Whether entity is currently being persisted */
+	readonly $isPersisting: boolean
+
 	/** Server-assigned ID after persistence */
 	readonly $persistedId: string | null
 
@@ -539,6 +542,9 @@ export interface EntityRefBase<
 	/** Whether entity is dirty */
 	readonly $isDirty: boolean
 
+	/** Whether entity is currently being persisted */
+	readonly $isPersisting: boolean
+
 	/** Server-assigned ID after persistence */
 	readonly $persistedId: string | null
 

package/src/index.ts

@@ -224,7 +224,7 @@ export { deepEqual } from './utils/deepEqual.js'
 export { generateHasManyAlias } from './utils/aliasGenerator.js'
 
 // Contember integration
-export { MutationCollector, ContemberSchemaMutationAdapter } from './contember/index.js'
+export { MutationCollector, ContemberSchemaMutationAdapter, type SchemaNames } from './contember/index.js'
 export type { MutationSchemaProvider, EntityMutationResult } from './contember/index.js'
 
 // Undo/Redo
@@ -328,8 +328,27 @@ export {
 } from './errors/index.js'
 
 
-// Re-export Contember types for convenience
-export type { SchemaNames, SchemaEntityNames } from '@contember/client-content'
+// Re-export bindx-client types
+export {
+	ContentClient,
+	type ContentClientOptions,
+	type ContentQuery,
+	type ContentMutation,
+	ContentOperation,
+	type MutationResult as ClientMutationResult,
+	MutationFailedError,
+	type QuerySpecContext,
+	querySpecToGraphQl,
+	buildGetArgs,
+	buildListArgs,
+	buildCreateArgs,
+	buildUpdateArgs,
+	buildDeleteArgs,
+	buildMutationSelection,
+	mutationFragments,
+	unwrapPaginateResult,
+} from '@contember/bindx-client'
+export { qb } from '@contember/bindx-client'
 
 // DataView / DataGrid
 export type {

package/src/persistence/ContemberSchemaMutationAdapter.ts

@@ -1,4 +1,22 @@
-import type { SchemaNames } from '@contember/client-content'
+/**
+ * Runtime schema names format (from Contember API / generated code).
+ */
+export interface SchemaNames {
+	readonly entities: {
+		readonly [entityName: string]: {
+			readonly name: string
+			readonly scalars: readonly string[]
+			readonly fields: {
+				readonly [fieldName: string]:
+					| { readonly type: 'column'; readonly enumName?: string; readonly columnType?: string }
+					| { readonly type: 'many' | 'one'; readonly entity: string }
+			}
+		}
+	}
+	readonly enums?: {
+		readonly [enumName: string]: readonly string[]
+	}
+}
 import type { MutationSchemaProvider } from './MutationSchemaProvider.js'
 
 /**