@contember/bindx 0.1.0

package/src/errors/UnfetchedFieldError.ts

@@ -0,0 +1,18 @@
+/**
+ * Error thrown when accessing a field that wasn't included in the GraphQL selection.
+ * This helps debug field collection issues by clearly indicating which field is missing.
+ */
+export class UnfetchedFieldError extends Error {
+	constructor(
+		public readonly entityType: string,
+		public readonly entityId: string,
+		public readonly fieldPath: string[],
+	) {
+		const pathStr = fieldPath.join('.')
+		super(
+			`Accessing unfetched field "${pathStr}" on entity ${entityType}(${entityId}). ` +
+			`This field was not included in the selection.`,
+		)
+		this.name = 'UnfetchedFieldError'
+	}
+}

package/src/errors/errorPathResolver.ts

@@ -0,0 +1,239 @@
+/**
+ * Deep error path resolution for Contember mutation errors.
+ *
+ * Walks error paths through the schema and store to resolve
+ * the exact target entity and field where the error occurred,
+ * instead of mapping everything to the root entity.
+ */
+
+import type { SchemaRegistry } from '../schema/SchemaRegistry.js'
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type { PathElement, ContemberMutationResult } from './pathMapper.js'
+import { createServerError, type ServerError } from './types.js'
+
+/**
+ * The resolved target of an error path.
+ */
+export interface ResolvedErrorTarget {
+	readonly entityType: string
+	readonly entityId: string
+	readonly fieldName?: string
+	readonly type: 'field' | 'relation' | 'entity'
+}
+
+/**
+ * A fully resolved error with its target and error object.
+ */
+export interface ResolvedError {
+	readonly target: ResolvedErrorTarget
+	readonly error: ServerError
+}
+
+/**
+ * Context needed for resolving error paths.
+ */
+export interface ErrorPathContext {
+	readonly schema: SchemaRegistry
+	readonly store: SnapshotStore
+}
+
+/**
+ * Resolves an error path to the specific entity and field where the error occurred.
+ *
+ * Walks path elements through schema relations and store state:
+ * - `{field: name}` on scalar + last element → field error on current entity
+ * - `{field: name}` on has-one → traverse into related entity via store
+ * - `{field: name}` on has-many → consume next `{index, alias}` element
+ * - `{index, alias}` → resolve entity ID from alias or index-based lookup
+ *
+ * Falls back to last successfully resolved entity on failure.
+ */
+export function resolveErrorPath(
+	path: PathElement[],
+	rootEntityType: string,
+	rootEntityId: string,
+	context: ErrorPathContext,
+): ResolvedErrorTarget {
+	if (path.length === 0) {
+		return { entityType: rootEntityType, entityId: rootEntityId, type: 'entity' }
+	}
+
+	let currentType = rootEntityType
+	let currentId = rootEntityId
+	let lastField: string | undefined
+
+	for (let i = 0; i < path.length; i++) {
+		const element = path[i]!
+
+		if ('field' in element) {
+			const fieldName = element.field
+			const fieldDef = context.schema.getFieldDef(currentType, fieldName)
+
+			if (!fieldDef) {
+				// Unknown field — return as field error on current entity (best effort)
+				return { entityType: currentType, entityId: currentId, fieldName, type: 'field' }
+			}
+
+			if (fieldDef.type === 'scalar') {
+				// Scalar field — this is the leaf target
+				return { entityType: currentType, entityId: currentId, fieldName, type: 'field' }
+			}
+
+			if (fieldDef.type === 'hasOne') {
+				const targetType = context.schema.getRelationTarget(currentType, fieldName)
+				if (!targetType) {
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				// Check if there are more path elements to traverse into
+				if (i === path.length - 1) {
+					// Last element — error is on the relation itself
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				// Traverse into the related entity
+				const relationState = context.store.getRelation(currentType, currentId, fieldName)
+				if (!relationState || !relationState.currentId) {
+					// Can't resolve further — return relation error on current entity
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				currentType = targetType
+				currentId = relationState.currentId
+				lastField = fieldName
+				continue
+			}
+
+			if (fieldDef.type === 'hasMany') {
+				const targetType = context.schema.getRelationTarget(currentType, fieldName)
+				if (!targetType) {
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				// Next element should be {index, alias}
+				const nextElement = path[i + 1]
+				if (!nextElement || !('index' in nextElement)) {
+					// No index element — error is on the relation itself
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				// Consume the index element
+				i++
+
+				// Resolve entity ID from alias or index
+				const resolvedId = resolveHasManyItemId(
+					nextElement as { index: number; alias: string | null },
+					currentType,
+					currentId,
+					fieldName,
+					context.store,
+				)
+
+				if (!resolvedId) {
+					// Can't resolve — return relation error on current entity
+					return { entityType: currentType, entityId: currentId, fieldName, type: 'relation' }
+				}
+
+				currentType = targetType
+				currentId = resolvedId
+				lastField = fieldName
+				continue
+			}
+		} else if ('index' in element) {
+			// Bare index element without preceding has-many field — shouldn't happen
+			// but handle gracefully by returning entity-level error
+			continue
+		}
+	}
+
+	// Ended traversal without hitting a leaf — return entity-level error on current entity
+	return { entityType: currentType, entityId: currentId, type: 'entity' }
+}
+
+/**
+ * Resolves a has-many item ID from an index/alias path element.
+ * Prefers alias (which is the entity ID) over index-based lookup.
+ */
+function resolveHasManyItemId(
+	element: { index: number; alias: string | null },
+	parentType: string,
+	parentId: string,
+	fieldName: string,
+	store: SnapshotStore,
+): string | undefined {
+	// Alias is the entity ID — use directly
+	if (element.alias) {
+		return element.alias
+	}
+
+	// Fall back to index-based lookup from ordered list
+	const orderedIds = store.getHasManyOrderedIds(parentType, parentId, fieldName)
+	return orderedIds[element.index]
+}
+
+/**
+ * Converts error type string to a user-friendly error code.
+ */
+function getErrorCode(errorType?: string): string | undefined {
+	if (!errorType) return undefined
+
+	switch (errorType) {
+		case 'UniqueConstraintViolation':
+			return 'UNIQUE_CONSTRAINT'
+		case 'NotNullConstraintViolation':
+			return 'NOT_NULL'
+		case 'ForeignKeyConstraintViolation':
+			return 'FOREIGN_KEY'
+		case 'NotFoundOrDenied':
+			return 'NOT_FOUND'
+		case 'NonUniqueWhereInput':
+			return 'NON_UNIQUE_WHERE'
+		case 'InvalidDataInput':
+			return 'INVALID_DATA'
+		case 'SqlError':
+			return 'SQL_ERROR'
+		default:
+			return undefined
+	}
+}
+
+/**
+ * Resolves all errors from a Contember mutation result to specific entity targets.
+ * Processes both execution errors and validation errors.
+ */
+export function resolveAllErrors(
+	result: ContemberMutationResult,
+	rootEntityType: string,
+	rootEntityId: string,
+	context: ErrorPathContext,
+): ResolvedError[] {
+	const resolved: ResolvedError[] = []
+
+	for (const error of result.errors) {
+		if (error.paths.length === 0) {
+			resolved.push({
+				target: { entityType: rootEntityType, entityId: rootEntityId, type: 'entity' },
+				error: createServerError(error.message, error.type, getErrorCode(error.type)),
+			})
+			continue
+		}
+
+		for (const path of error.paths) {
+			const target = resolveErrorPath(path, rootEntityType, rootEntityId, context)
+			resolved.push({
+				target,
+				error: createServerError(error.message, error.type, getErrorCode(error.type)),
+			})
+		}
+	}
+
+	for (const error of result.validation.errors) {
+		const target = resolveErrorPath(error.path, rootEntityType, rootEntityId, context)
+		resolved.push({
+			target,
+			error: createServerError(error.message.text, undefined, 'VALIDATION_ERROR'),
+		})
+	}
+
+	return resolved
+}

package/src/errors/index.ts

@@ -0,0 +1,40 @@
+export {
+	type ExecutionErrorType,
+	type ErrorCategory,
+	type BindxError,
+	type ClientError,
+	type ServerError,
+	type LoadError,
+	type FieldError,
+	type ErrorState,
+	type ErrorInput,
+	ExecutionErrorTypes,
+	isExecutionErrorType,
+	classifyError,
+	isRetryableCategory,
+	createClientError,
+	createServerError,
+	createLoadError,
+	isClientError,
+	isServerError,
+	isLoadError,
+	filterErrorsBySource,
+	filterStickyErrors,
+} from './types.js'
+
+export { UnfetchedFieldError } from './UnfetchedFieldError.js'
+
+export {
+	type PathElement,
+	type ContemberMutationError,
+	type ContemberValidationError,
+	type ContemberMutationResult,
+} from './pathMapper.js'
+
+export {
+	type ResolvedErrorTarget,
+	type ResolvedError,
+	type ErrorPathContext,
+	resolveErrorPath,
+	resolveAllErrors,
+} from './errorPathResolver.js'

package/src/errors/pathMapper.ts

@@ -0,0 +1,40 @@
+/**
+ * Types for Contember error paths and mutation results.
+ */
+
+/**
+ * Contember path element - either a field name or an array index.
+ */
+export type PathElement =
+	| { field: string }
+	| { index: number; alias: string | null }
+
+/**
+ * Contember mutation error structure.
+ */
+export interface ContemberMutationError {
+	readonly paths: PathElement[][]
+	readonly message: string
+	readonly type: string
+}
+
+/**
+ * Contember validation error structure.
+ */
+export interface ContemberValidationError {
+	readonly path: PathElement[]
+	readonly message: { text: string }
+}
+
+/**
+ * Processes a Contember mutation result and extracts errors.
+ */
+export interface ContemberMutationResult {
+	readonly ok: boolean
+	readonly errorMessage: string | null
+	readonly errors: ContemberMutationError[]
+	readonly validation: {
+		readonly valid: boolean
+		readonly errors: ContemberValidationError[]
+	}
+}

package/src/errors/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Error types for bindx error handling system.
+ *
+ * Supports both client-side validation errors and server-side errors
+ * from Contember mutations.
+ */
+
+import { Result } from '@contember/schema'
+
+/**
+ * Execution error types from Contember.
+ * Re-exported from @contember/schema to ensure type compatibility.
+ */
+export type ExecutionErrorType = `${Result.ExecutionErrorType}`
+
+/**
+ * All possible execution error type values.
+ * Used for runtime validation and error classification.
+ */
+export const ExecutionErrorTypes: Record<ExecutionErrorType, ExecutionErrorType> = {
+	NotNullConstraintViolation: 'NotNullConstraintViolation',
+	UniqueConstraintViolation: 'UniqueConstraintViolation',
+	ForeignKeyConstraintViolation: 'ForeignKeyConstraintViolation',
+	NotFoundOrDenied: 'NotFoundOrDenied',
+	NonUniqueWhereInput: 'NonUniqueWhereInput',
+	InvalidDataInput: 'InvalidDataInput',
+	SqlError: 'SqlError',
+}
+
+/**
+ * Checks if a string is a valid ExecutionErrorType.
+ */
+export function isExecutionErrorType(value: string): value is ExecutionErrorType {
+	return value in ExecutionErrorTypes
+}
+
+/**
+ * Error classification for retry logic.
+ */
+export type ErrorCategory = 'validation' | 'constraint' | 'not_found' | 'transient' | 'unknown'
+
+/**
+ * Classifies an execution error type into a category.
+ * - 'validation': Data validation errors (not retryable)
+ * - 'constraint': Database constraint violations (not retryable without data change)
+ * - 'not_found': Entity not found or access denied (not retryable)
+ * - 'transient': Temporary errors that may succeed on retry
+ * - 'unknown': Unclassified errors
+ */
+export function classifyError(errorType?: string): ErrorCategory {
+	if (!errorType) return 'unknown'
+
+	switch (errorType) {
+		case 'NotNullConstraintViolation':
+		case 'UniqueConstraintViolation':
+		case 'ForeignKeyConstraintViolation':
+			return 'constraint'
+		case 'InvalidDataInput':
+		case 'NonUniqueWhereInput':
+			return 'validation'
+		case 'NotFoundOrDenied':
+			return 'not_found'
+		case 'SqlError':
+			// SQL errors could be transient (deadlock, connection issues) or permanent
+			return 'transient'
+		default:
+			return 'unknown'
+	}
+}
+
+/**
+ * Checks if an error category is potentially retryable.
+ */
+export function isRetryableCategory(category: ErrorCategory): boolean {
+	return category === 'transient' || category === 'unknown'
+}
+
+/**
+ * Base interface for all bindx errors.
+ */
+export interface BindxError {
+	/** Human-readable error message */
+	readonly message: string
+	/** Optional error code for programmatic handling (e.g., 'REQUIRED', 'UNIQUE_CONSTRAINT') */
+	readonly code?: string
+	/** If true, error won't auto-clear when field value changes */
+	readonly sticky?: boolean
+}
+
+/**
+ * Client-side error - added by user code for validation.
+ */
+export interface ClientError extends BindxError {
+	readonly source: 'client'
+}
+
+/**
+ * Server-side error - from Contember mutation response.
+ */
+export interface ServerError extends BindxError {
+	readonly source: 'server'
+	/** Contember execution error type for database errors (string to support forward-compatible unknown types) */
+	readonly type?: string
+	/** Error category for classification */
+	readonly category: ErrorCategory
+	/** Whether this error might succeed on retry */
+	readonly retryable: boolean
+}
+
+/**
+ * Load error - from data fetching (queries).
+ */
+export interface LoadError extends BindxError {
+	readonly source: 'load'
+	/** Error category for classification */
+	readonly category: ErrorCategory
+	/** Whether this error might succeed on retry */
+	readonly retryable: boolean
+	/** Original Error object for stack trace access */
+	readonly originalError?: Error
+}
+
+/**
+ * Union type for all error sources.
+ */
+export type FieldError = ClientError | ServerError | LoadError
+
+/**
+ * Error state stored in the SnapshotStore.
+ */
+export interface ErrorState {
+	readonly errors: readonly FieldError[]
+	readonly version: number
+}
+
+/**
+ * Input type for addError - allows string shorthand or full error object.
+ */
+export type ErrorInput = string | Omit<ClientError, 'source'>
+
+/**
+ * Creates a ClientError from ErrorInput.
+ */
+export function createClientError(input: ErrorInput): ClientError {
+	if (typeof input === 'string') {
+		return { source: 'client', message: input }
+	}
+	return { ...input, source: 'client' }
+}
+
+/**
+ * Creates a ServerError from Contember error data.
+ * Automatically computes error category and retryable flag.
+ */
+export function createServerError(
+	message: string,
+	type?: string,
+	code?: string,
+): ServerError {
+	const category = classifyError(type)
+	return {
+		source: 'server',
+		message,
+		type,
+		code,
+		category,
+		retryable: isRetryableCategory(category),
+	}
+}
+
+/**
+ * Creates a LoadError from a plain Error.
+ * Load errors are always classified as 'transient' and retryable.
+ */
+export function createLoadError(error: Error): LoadError {
+	return {
+		source: 'load',
+		message: error.message,
+		category: 'transient',
+		retryable: true,
+		originalError: error,
+	}
+}
+
+/**
+ * Checks if an error is a client error.
+ */
+export function isClientError(error: FieldError): error is ClientError {
+	return error.source === 'client'
+}
+
+/**
+ * Checks if an error is a server error.
+ */
+export function isServerError(error: FieldError): error is ServerError {
+	return error.source === 'server'
+}
+
+/**
+ * Checks if an error is a load error.
+ */
+export function isLoadError(error: FieldError): error is LoadError {
+	return error.source === 'load'
+}
+
+/**
+ * Filters errors by source.
+ */
+export function filterErrorsBySource(
+	errors: readonly FieldError[],
+	source: 'client' | 'server' | 'load',
+): FieldError[] {
+	return errors.filter(e => e.source === source)
+}
+
+/**
+ * Filters out non-sticky client errors.
+ * Used when auto-clearing errors on value change.
+ * Load and server errors are always preserved.
+ */
+export function filterStickyErrors(errors: readonly FieldError[]): FieldError[] {
+	return errors.filter(e => e.source === 'server' || e.source === 'load' || e.sticky === true)
+}