@contember/bindx-react 0.1.5 → 0.1.11

package/src/hooks/ContemberBindxProvider.tsx

@@ -1,23 +1,44 @@
 import { memo, useMemo, type ReactNode } from 'react'
 import { GraphQlClient } from '@contember/graphql-client'
-import { ContentClient, ContentQueryBuilder, type SchemaNames } from '@contember/client-content'
+import { ContentClient } from '@contember/bindx-client'
 import { ContemberAdapter, SnapshotStore, ActionDispatcher, BatchPersister, MutationCollector, ContemberSchemaMutationAdapter, UndoManager, SchemaRegistry, type SchemaDefinition, type FieldDef, type UndoManagerConfig, type UpdateMode } from '@contember/bindx'
 import { BindxContext, type BindxContextValue } from './BackendAdapterContext.js'
 import { QueryBatcher } from '../batching/QueryBatcher.js'
 
+/**
+ * Runtime schema names format (from Contember API / generated code).
+ * Used by ContemberBindxProvider for backwards compatibility.
+ */
+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[]
+	}
+}
+
 /**
  * Converts SchemaNames (Contember format) to SchemaDefinition (bindx format)
  * so that a SchemaRegistry can be created for standalone hooks.
  */
 export function schemaNamesToDef(schemaNames: SchemaNames): SchemaDefinition<Record<string, object>> {
-	const enumsMap = (schemaNames as { enums?: Record<string, readonly string[]> }).enums ?? {}
+	const enumsMap = schemaNames.enums ?? {}
 	const entities: Record<string, { fields: Record<string, FieldDef> }> = {}
 	for (const [entityName, entity] of Object.entries(schemaNames.entities)) {
 		const fields: Record<string, FieldDef> = {}
 		for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
 			if (fieldDef.type === 'column') {
-				const enumName = (fieldDef as { enumName?: string }).enumName
-				const columnType = (fieldDef as { columnType?: string }).columnType
+				const enumName = fieldDef.enumName
+				const columnType = fieldDef.columnType
 				const enumValues = enumName ? enumsMap[enumName] : undefined
 				if (enumName && enumValues) {
 					fields[fieldName] = { type: 'enum', enumName, values: enumValues }
@@ -64,35 +85,6 @@ export interface ContemberBindxProviderProps {
 
 /**
  * Provider component that combines Contember authentication with bindx data binding.
- *
- * @example
- * ```tsx
- * import { ContemberBindxProvider, useUndo } from '@contember/bindx-react'
- * import { schema } from './generated/schema'
- *
- * function App() {
- *   return (
- *     <ContemberBindxProvider
- *       client={graphQlClient}
- *       schema={schema}
- *       undoManager={true}
- *     >
- *       <ArticleEditor id="123" />
- *     </ContemberBindxProvider>
- *   )
- * }
- *
- * // Access undo/redo in child components
- * function UndoControls() {
- *   const { canUndo, canRedo, undo, redo } = useUndo()
- *   return (
- *     <div>
- *       <button onClick={undo} disabled={!canUndo}>Undo</button>
- *       <button onClick={redo} disabled={!canRedo}>Redo</button>
- *     </div>
- *   )
- * }
- * ```
  */
 export const ContemberBindxProvider = memo(function ContemberBindxProvider({
 	schema,
@@ -108,7 +100,12 @@ export const ContemberBindxProvider = memo(function ContemberBindxProvider({
 	// Create GraphQL client and adapter
 	const bindxValue = useMemo((): BindxContextValue => {
 
-		const adapter = new ContemberAdapter(new ContentClient(graphQlClient), new ContentQueryBuilder(schema))
+		// Create schema registry from SchemaNames for standalone hooks
+		const schemaRegistry = new SchemaRegistry(schemaNamesToDef(schema))
+
+		// Create adapter using new bindx-client ContentClient
+		const contentClient = new ContentClient(graphQlClient)
+		const adapter = new ContemberAdapter(contentClient, schemaRegistry)
 		const batcher = new QueryBatcher(adapter)
 
 		const store = customStore ?? new SnapshotStore()
@@ -124,9 +121,6 @@ export const ContemberBindxProvider = memo(function ContemberBindxProvider({
 			dispatcher.addMiddleware(undoManager.createMiddleware())
 		}
 
-		// Create schema registry from SchemaNames for standalone hooks
-		const schemaRegistry = new SchemaRegistry(schemaNamesToDef(schema))
-
 		// Create mutation collector for proper nested operations
 		// Use ContemberSchemaMutationAdapter to wrap SchemaNames
 		const schemaAdapter = new ContemberSchemaMutationAdapter(schema)
@@ -146,6 +140,7 @@ export const ContemberBindxProvider = memo(function ContemberBindxProvider({
 			batchPersister,
 			schema: schemaRegistry,
 			undoManager,
+			graphQlClient,
 			debug,
 		}
 	}, [schema, customStore, undoManagerProp, undoConfig, defaultUpdateMode, debug])

package/src/hooks/index.ts

@@ -8,6 +8,7 @@ export {
 	useSchemaRegistry,
 	type BindxProviderProps,
 	type BindxContextValue,
+	type BindxGraphQlClient,
 } from './BackendAdapterContext.js'
 
 export {
@@ -21,20 +22,20 @@ export {
 export {
 	useEntity,
 	type UseEntityOptions,
-	type LoadingEntityAccessor,
-	type ErrorEntityAccessor,
-	type NotFoundEntityAccessor,
-	type ReadyEntityAccessor,
-	type EntityAccessorResult,
+	type LoadingEntityResult,
+	type ErrorEntityResult,
+	type NotFoundEntityResult,
+	type ReadyEntityResult,
+	type UseEntityResult,
 } from './useEntity.js'
 
 export {
 	useEntityList,
 	type UseEntityListOptions,
-	type LoadingEntityListAccessor,
-	type ErrorEntityListAccessor,
-	type ReadyEntityListAccessor,
-	type EntityListAccessorResult,
+	type LoadingEntityListResult,
+	type ErrorEntityListResult,
+	type ReadyEntityListResult,
+	type UseEntityListResult,
 } from './useEntityList.js'
 
 export {

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,85 @@ 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<object, object> => {
+		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()
-			},
-		}
+	// Proxy-based result satisfies the full UseEntityResult<T> at runtime via field access delegation
+	return result as UseEntityResult<any, any>
+}
 
-		// 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,
+): UseEntityResult<object, object> {
+	const meta: Record<string, unknown> = {
+		$status: 'ready' as const,
+		$isLoading: false as const,
+		$isError: false as const,
+		$isNotFound: false as const,
+		$error: null,
+		$persist: persist,
+		$reset: reset,
+	}
 
-	return accessor
+	// Proxy merges status metadata onto EntityAccessor — satisfies ReadyEntityResult at runtime
+	return new Proxy(handle as object, {
+		get(target, prop, receiver) {
+			if (typeof prop === 'string' && prop in meta) {
+				return meta[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 unknown as UseEntityResult<object, object>
 }