@contember/bindx-react 0.1.4 → 0.1.10

package/src/hooks/useEntity.ts

@@ -12,6 +12,7 @@ import type {
 	CommonEntity,
 	EntityForRoles,
 	RoleNames,
+	EntityAccessor,
 } from '@contember/bindx'
 import {
 	EntityHandle,
@@ -51,165 +52,62 @@ export interface UseEntityOptions {
 // ============================================================================
 
 /**
- * Loading state for entity accessor
+ * Common properties on every UseEntityResult state.
+ * All prefixed with $ to avoid collision with entity field names.
  */
-export interface LoadingEntityAccessor {
-	readonly status: 'loading'
-	readonly isLoading: true
-	readonly isError: false
-	readonly isNotFound: false
-	readonly isPersisting: false
-	readonly isDirty: false
-	readonly id: string
-	readonly fields: never
-	readonly data: never
-	persist(): Promise<void>
-	reset(): void
+interface UseEntityResultBase {
+	$persist(): Promise<void>
+	$reset(): void
 }
 
-/**
- * Error state for entity accessor
- */
-export interface ErrorEntityAccessor {
-	readonly status: 'error'
-	readonly isLoading: false
-	readonly isError: true
-	readonly isNotFound: false
-	readonly error: FieldError
-	readonly isPersisting: false
-	readonly isDirty: false
+export type LoadingEntityResult = UseEntityResultBase & {
+	readonly $status: 'loading'
+	readonly $isLoading: true
+	readonly $isError: false
+	readonly $isNotFound: false
+	readonly $error: null
 	readonly id: string
-	readonly fields: never
-	readonly data: never
-	persist(): Promise<void>
-	reset(): void
 }
 
-/**
- * Not found state for entity accessor
- */
-export interface NotFoundEntityAccessor {
-	readonly status: 'not_found'
-	readonly isLoading: false
-	readonly isError: false
-	readonly isNotFound: true
-	readonly isPersisting: false
-	readonly isDirty: false
+export type ErrorEntityResult = UseEntityResultBase & {
+	readonly $status: 'error'
+	readonly $isLoading: false
+	readonly $isError: true
+	readonly $isNotFound: false
+	readonly $error: FieldError
 	readonly id: string
-	readonly fields: never
-	readonly data: never
-	persist(): Promise<void>
-	reset(): void
 }
 
-/**
- * Ready state base interface for entity accessor
- */
-export interface ReadyEntityAccessorBase<TEntity extends object, TSelected extends object = TEntity> {
-	readonly status: 'ready'
-	readonly isLoading: false
-	readonly isError: false
-	readonly isNotFound: false
-	readonly isPersisting: boolean
-	readonly isDirty: boolean
+export type NotFoundEntityResult = UseEntityResultBase & {
+	readonly $status: 'not_found'
+	readonly $isLoading: false
+	readonly $isError: false
+	readonly $isNotFound: true
+	readonly $error: null
 	readonly id: string
-	readonly fields: SelectedEntityFields<TEntity, TSelected>
-	readonly data: TSelected
-	persist(): Promise<void>
-	reset(): void
 }
 
 /**
- * Ready state for entity accessor with direct field access via Proxy.
+ * Ready state — full EntityAccessor with status metadata.
  */
-export type ReadyEntityAccessor<TEntity extends object, TSelected extends object = TEntity> =
-	ReadyEntityAccessorBase<TEntity, TSelected> & SelectedEntityFields<TEntity, TSelected>
+export type ReadyEntityResult<TEntity extends object, TSelected extends object = TEntity> =
+	UseEntityResultBase & EntityAccessor<TEntity, TSelected> & {
+		readonly $status: 'ready'
+		readonly $isLoading: false
+		readonly $isError: false
+		readonly $isNotFound: false
+		readonly $error: null
+	}
 
 /**
- * Union of all entity accessor states
+ * Union of all useEntity return states.
+ * Discriminated on $status.
  */
-export type EntityAccessorResult<TEntity extends object, TSelected extends object = TEntity> =
-	| LoadingEntityAccessor
-	| ErrorEntityAccessor
-	| NotFoundEntityAccessor
-	| ReadyEntityAccessor<TEntity, TSelected>
-
-// ============================================================================
-// Internal helpers
-// ============================================================================
-
-function createLoadingAccessor(id: string): LoadingEntityAccessor {
-	return {
-		status: 'loading',
-		isLoading: true,
-		isError: false,
-		isNotFound: false,
-		isPersisting: false,
-		isDirty: false,
-		id,
-		get fields(): never {
-			throw new Error('Cannot access fields while loading')
-		},
-		get data(): never {
-			throw new Error('Cannot access data while loading')
-		},
-		async persist() {
-			// No-op while loading
-		},
-		reset() {
-			// No-op while loading
-		},
-	}
-}
-
-function createErrorAccessor(id: string, error: FieldError): ErrorEntityAccessor {
-	return {
-		status: 'error',
-		isLoading: false,
-		isError: true,
-		isNotFound: false,
-		error,
-		isPersisting: false,
-		isDirty: false,
-		id,
-		get fields(): never {
-			throw new Error('Cannot access fields after error')
-		},
-		get data(): never {
-			throw new Error('Cannot access data after error')
-		},
-		async persist() {
-			// No-op after error
-		},
-		reset() {
-			// No-op after error
-		},
-	}
-}
-
-function createNotFoundAccessor(id: string): NotFoundEntityAccessor {
-	return {
-		status: 'not_found',
-		isLoading: false,
-		isError: false,
-		isNotFound: true,
-		isPersisting: false,
-		isDirty: false,
-		id,
-		get fields(): never {
-			throw new Error('Cannot access fields — entity not found')
-		},
-		get data(): never {
-			throw new Error('Cannot access data — entity not found')
-		},
-		async persist() {
-			// No-op for not found
-		},
-		reset() {
-			// No-op for not found
-		},
-	}
-}
+export type UseEntityResult<TEntity extends object, TSelected extends object = TEntity> =
+	| LoadingEntityResult
+	| ErrorEntityResult
+	| NotFoundEntityResult
+	| ReadyEntityResult<TEntity, TSelected>
 
 // ============================================================================
 // Hook overloads
@@ -217,11 +115,6 @@ function createNotFoundAccessor(id: string): NotFoundEntityAccessor {
 
 /**
  * Hook to fetch and manage a single entity with role-expanded type inference.
- *
- * @example
- * ```tsx
- * const article = useEntity(schema.Article, { by: { id }, roles: ['admin'] }, e => e.title().internalNotes())
- * ```
  */
 export function useEntity<
 	TRoleMap extends Record<string, object>,
@@ -231,16 +124,15 @@ export function useEntity<
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityOptions & { roles: readonly TRoles[] },
 	definer: SelectionInput<EntityForRoles<TRoleMap, TRoles>, TResult>,
-): EntityAccessorResult<EntityForRoles<TRoleMap, TRoles>, TResult>
+): UseEntityResult<EntityForRoles<TRoleMap, TRoles>, TResult>
 
 /**
  * Hook to fetch and manage a single entity with full type inference.
- * Uses the common (narrowest) entity type when no roles are specified.
  *
  * @example
  * ```tsx
  * const article = useEntity(schema.Article, { by: { id } }, e => e.title().content())
- * if (article.status !== 'ready') return <Loading />
+ * if (article.$status !== 'ready') return <Loading />
  * return <input value={article.title.value} onChange={...} />
  * ```
  */
@@ -248,31 +140,26 @@ export function useEntity<TRoleMap extends Record<string, object>, TResult exten
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityOptions,
 	definer: SelectionInput<CommonEntity<TRoleMap>, TResult>,
-): EntityAccessorResult<CommonEntity<TRoleMap>, TResult>
+): UseEntityResult<CommonEntity<TRoleMap>, TResult>
 
 /**
  * Hook to fetch and manage a single entity with pre-resolved selection.
- *
  * Used internally by Entity component that collects selection from JSX.
  */
 export function useEntity(
 	entity: EntityDef,
 	options: UseEntityOptions & { selection: SelectionMeta },
-): EntityAccessorResult<object, object>
+): UseEntityResult<object, object>
 
 // ============================================================================
 // Implementation
 // ============================================================================
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function useEntity(
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	entity: EntityDef<any>,
 	options: UseEntityOptions,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	definer?: SelectionInput<any, any>,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-): EntityAccessorResult<any, any> {
+): UseEntityResult<any, any> {
 	const schemaRegistry = useSchemaRegistry()
 	const entityType = entity.$name
 	const { store, dispatcher, batcher, batchPersister } = useBindxContext()
@@ -409,81 +296,83 @@ export function useEntity(
 	}, [entityType, id, byKey, effectiveQueryKey, options.cache, batcher, store, dispatcher, selectionMeta])
 
 	// --- EntityHandle ---
-	// Include snapshot in deps so handle reference changes when entity data changes.
-	// This ensures memo-wrapped children that receive individual field handles re-render.
-	const handle = useMemo(
-		() => EntityHandle.create(id, entityType, store, dispatcher, schemaRegistry as SchemaRegistry<Record<string, object>>),
+	const rawHandle = useMemo(
+		() => EntityHandle.createRaw(id, entityType, store, dispatcher, schemaRegistry as SchemaRegistry<Record<string, object>>),
 		[id, entityType, store, dispatcher, schemaRegistry, snapshot],
 	)
 
+	const handle = useMemo(
+		() => EntityHandle.wrapProxy(rawHandle),
+		[rawHandle],
+	)
+
 	useEffect(() => {
 		return () => {
-			handle.dispose()
+			rawHandle.dispose()
 		}
-	}, [handle])
+	}, [rawHandle])
+
+	// --- Persist & reset callbacks ---
+	const persist = useCallback(async () => {
+		await batchPersister.persist(entityType, id)
+	}, [batchPersister, entityType, id])
 
-	// --- Build accessor ---
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	const accessor = useMemo((): EntityAccessorResult<any, any> => {
-		if (!loadState || loadState.status === 'loading') {
-			return createLoadingAccessor(id)
+	const reset = useCallback(() => {
+		rawHandle.reset()
+	}, [rawHandle])
+
+	// --- Build result ---
+	const result = useMemo((): UseEntityResult<any, any> => {
+		if (!loadState || loadState.status === 'loading' || (!snapshot && loadState.status === 'success')) {
+			return { $status: 'loading', $isLoading: true, $isError: false, $isNotFound: false, $error: null, id, $persist: persist, $reset: reset }
 		}
 
 		if (loadState.status === 'error') {
-			return createErrorAccessor(id, loadState.error!)
+			return { $status: 'error', $isLoading: false, $isError: true, $isNotFound: false, $error: loadState.error!, id, $persist: persist, $reset: reset }
 		}
 
 		if (loadState.status === 'not_found') {
-			return createNotFoundAccessor(id)
+			return { $status: 'not_found', $isLoading: false, $isError: false, $isNotFound: true, $error: null, id, $persist: persist, $reset: reset }
 		}
 
-		if (!snapshot) {
-			return createLoadingAccessor(id)
-		}
+		// Ready — layer status metadata on top of EntityHandle proxy
+		return createReadyResult(handle, persist, reset)
+	}, [snapshot, loadState, isPersisting, id, handle, persist, reset])
 
-		// Ready state
-		const realId = (snapshot.data as Record<string, unknown>)?.['id'] as string | undefined ?? id
-
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const baseAccessor: ReadyEntityAccessorBase<any, any> = {
-			status: 'ready',
-			isLoading: false,
-			isError: false,
-			isNotFound: false,
-			isPersisting,
-			get isDirty() {
-				return handle.$isDirty
-			},
-			id: realId,
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			fields: handle.$fields as any,
-			data: snapshot.data,
-			async persist() {
-				await batchPersister.persist(entityType, realId)
-			},
-			reset() {
-				handle.reset()
-			},
-		}
+	return result
+}
 
-		// Wrap in Proxy for direct field access
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		return new Proxy(baseAccessor as any, {
-			get(target: Record<string, unknown>, prop: string | symbol, receiver: unknown) {
-				if (prop in target) {
-					return Reflect.get(target, prop, receiver)
-				}
-				if (typeof prop === 'string') {
-					const fields = target['fields'] as Record<string, unknown>
-					const fieldValue = fields[prop]
-					if (fieldValue !== undefined) {
-						return fieldValue
-					}
-				}
-				return undefined
-			},
-		})
-	}, [snapshot, loadState, isPersisting, id, handle, batchPersister, entityType])
+// ============================================================================
+// Result factories
+// ============================================================================
+
+function createReadyResult(
+	handle: EntityAccessor<object, object>,
+	persist: () => Promise<void>,
+	reset: () => void,
+): ReadyEntityResult<any, any> {
+	const meta = {
+		$status: 'ready' as const,
+		$isLoading: false as const,
+		$isError: false as const,
+		$isNotFound: false as const,
+		$error: null,
+		$persist: persist,
+		$reset: reset,
+	}
 
-	return accessor
+	return new Proxy(handle as any, {
+		get(target, prop, receiver) {
+			if (typeof prop === 'string' && prop in meta) {
+				return (meta as any)[prop]
+			}
+			return Reflect.get(target, prop, receiver)
+		},
+		has(target, prop) {
+			if (typeof prop === 'string' && prop in meta) {
+				return true
+			}
+			return Reflect.has(target, prop)
+		},
+	}) as any
 }

package/src/hooks/useEntityList.ts

@@ -34,106 +34,66 @@ export interface UseEntityListOptions {
 // Result types
 // ============================================================================
 
-/**
- * Loading state for entity list accessor
- */
-export interface LoadingEntityListAccessor {
-	readonly status: 'loading'
-	readonly isLoading: true
-	readonly isError: false
-	readonly isDirty: false
-	readonly items: never
-	readonly length: 0
-	add(data?: unknown): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
+interface EntityListResultBase {
+	$add(data?: unknown): string
+	$remove(key: string): void
+	$move(fromIndex: number, toIndex: number): void
 }
 
-/**
- * Error state for entity list accessor
- */
-export interface ErrorEntityListAccessor {
-	readonly status: 'error'
-	readonly isLoading: false
-	readonly isError: true
-	readonly error: FieldError
-	readonly isDirty: false
-	readonly items: never
-	readonly length: 0
-	add(data?: unknown): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
+export type LoadingEntityListResult = EntityListResultBase & {
+	readonly $status: 'loading'
+	readonly $isLoading: true
+	readonly $isError: false
+	readonly $error: null
 }
 
-/**
- * Ready state for entity list accessor
- */
-export interface ReadyEntityListAccessor<T extends object> {
-	readonly status: 'ready'
-	readonly isLoading: false
-	readonly isError: false
-	readonly isDirty: boolean
+export type ErrorEntityListResult = EntityListResultBase & {
+	readonly $status: 'error'
+	readonly $isLoading: false
+	readonly $isError: true
+	readonly $error: FieldError
+}
+
+export type ReadyEntityListResult<T extends object> = EntityListResultBase & {
+	readonly $status: 'ready'
+	readonly $isLoading: false
+	readonly $isError: false
+	readonly $error: null
+	readonly $isDirty: boolean
 	readonly items: Array<EntityAccessor<T>>
 	readonly length: number
-	add(data?: Partial<T>): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
 }
 
-/**
- * Union of all entity list accessor states
- */
-export type EntityListAccessorResult<T extends object> =
-	| LoadingEntityListAccessor
-	| ErrorEntityListAccessor
-	| ReadyEntityListAccessor<T>
+export type UseEntityListResult<T extends object> =
+	| LoadingEntityListResult
+	| ErrorEntityListResult
+	| ReadyEntityListResult<T>
 
 // ============================================================================
 // Internal helpers
 // ============================================================================
 
-function createLoadingListAccessor(): LoadingEntityListAccessor {
+function createLoadingListResult(): LoadingEntityListResult {
 	return {
-		status: 'loading',
-		isLoading: true,
-		isError: false,
-		isDirty: false,
-		get items(): never {
-			throw new Error('Cannot access items while loading')
-		},
-		length: 0,
-		add() {
-			throw new Error('Cannot add items while loading')
-		},
-		remove() {
-			throw new Error('Cannot remove items while loading')
-		},
-		move() {
-			throw new Error('Cannot move items while loading')
-		},
+		$status: 'loading',
+		$isLoading: true,
+		$isError: false,
+		$error: null,
+		$add() { throw new Error('Cannot add items while loading') },
+		$remove() { throw new Error('Cannot remove items while loading') },
+		$move() { throw new Error('Cannot move items while loading') },
 	}
 }
 
-function createErrorListAccessor(error: FieldError): ErrorEntityListAccessor {
+function createErrorListResult(error: FieldError): ErrorEntityListResult {
 	return {
-		status: 'error',
-		isLoading: false,
-		isError: true,
-		error,
-		isDirty: false,
-		get items(): never {
-			throw new Error('Cannot access items after error')
-		},
-		length: 0,
-		add() {
-			throw new Error('Cannot add items after error')
-		},
-		remove() {
-			throw new Error('Cannot remove items after error')
-		},
-		move() {
-			throw new Error('Cannot move items after error')
-		},
+		$status: 'error',
+		$isLoading: false,
+		$isError: true,
+		$error: error,
+		$add() { throw new Error('Cannot add items after error') },
+		$remove() { throw new Error('Cannot remove items after error') },
+		$move() { throw new Error('Cannot move items after error') },
 	}
 }
 
@@ -157,7 +117,7 @@ export function useEntityList<
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityListOptions & { roles: readonly TRoles[] },
 	definer: SelectionInput<EntityForRoles<TRoleMap, TRoles>, TResult>,
-): EntityListAccessorResult<TResult>
+): UseEntityListResult<TResult>
 
 /**
  * Hook to fetch and manage a list of entities with full type inference.
@@ -174,7 +134,7 @@ export function useEntityList<TRoleMap extends Record<string, object>, TResult e
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityListOptions,
 	definer: SelectionInput<CommonEntity<TRoleMap>, TResult>,
-): EntityListAccessorResult<TResult>
+): UseEntityListResult<TResult>
 
 /**
  * Hook to fetch and manage a list of entities with pre-resolved selection.
@@ -185,7 +145,7 @@ export function useEntityList<TRoleMap extends Record<string, object>, TResult e
 export function useEntityList(
 	entity: EntityDef,
 	options: UseEntityListOptions & { selection: SelectionMeta },
-): EntityListAccessorResult<object>
+): UseEntityListResult<object>
 
 // ============================================================================
 // Implementation
@@ -197,7 +157,7 @@ export function useEntityList(
 	options: UseEntityListOptions,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	definer?: SelectionInput<any, any>,
-): EntityListAccessorResult<any> {
+): UseEntityListResult<any> {
 	const schemaRegistry = useSchemaRegistry()
 	const entityType = entity.$name
 	const { store, dispatcher, batcher } = useBindxContext()
@@ -250,7 +210,7 @@ export function useEntityList(
 		version: number
 		storeVersion: number
 		status: string
-		result: EntityListAccessorResult<object>
+		result: UseEntityListResult<any>
 	} | null>(null)
 
 	// --- Store subscription ---
@@ -310,7 +270,7 @@ export function useEntityList(
 	)
 
 	// --- Snapshot ---
-	const getSnapshot = useCallback((): EntityListAccessorResult<object> => {
+	const getSnapshot = useCallback((): UseEntityListResult<any> => {
 		const state = listStateRef.current
 		const version = versionRef.current
 		const storeVersion = store.getVersion()
@@ -320,12 +280,12 @@ export function useEntityList(
 			return cache.result
 		}
 
-		let result: EntityListAccessorResult<object>
+		let result: UseEntityListResult<any>
 
 		if (state.status === 'loading') {
-			result = createLoadingListAccessor()
+			result = createLoadingListResult()
 		} else if (state.status === 'error') {
-			result = createErrorListAccessor(state.error!)
+			result = createErrorListResult(state.error!)
 		} else {
 			const items = state.items.map((item) => {
 				return EntityHandle.create<object>(
@@ -334,19 +294,20 @@ export function useEntityList(
 					store,
 					dispatcher,
 					schemaRegistry as SchemaRegistry<Record<string, object>>,
-				) as unknown as EntityAccessor<object>
+				) as unknown as EntityAccessor<any>
 			})
 
 			result = {
-				status: 'ready',
-				isLoading: false,
-				isError: false,
-				isDirty: false,
+				$status: 'ready',
+				$isLoading: false,
+				$isError: false,
+				$error: null,
+				$isDirty: false,
 				items,
 				length: items.length,
-				add: addItem,
-				remove: removeItem,
-				move: moveItem,
+				$add: addItem,
+				$remove: removeItem,
+				$move: moveItem,
 			}
 		}
 
@@ -361,7 +322,7 @@ export function useEntityList(
 	}, [entityType, store, dispatcher, schemaRegistry, addItem, removeItem, moveItem])
 
 	const isEqual = useCallback(
-		(a: EntityListAccessorResult<object>, b: EntityListAccessorResult<object>): boolean => {
+		(a: UseEntityListResult<any>, b: UseEntityListResult<any>): boolean => {
 			return a === b
 		},
 		[],