@contember/binding-common 2.0.0-alpha.17

package/src/types/EntityAccessor.ts

@@ -0,0 +1,126 @@
+import { Environment } from '../environment'
+import { EntityListSubTreeMarker, EntitySubTreeMarker, HasManyRelationMarker, HasOneRelationMarker } from '../markers'
+import type {
+	EntityId,
+	EntityName,
+	EntityRealmKey,
+	FieldName,
+	FieldValue,
+	RelativeEntityList,
+	RelativeSingleEntity,
+	RelativeSingleField,
+	SugaredRelativeEntityList,
+	SugaredRelativeSingleEntity,
+	SugaredRelativeSingleField,
+} from '../treeParameters'
+import type { AsyncBatchUpdatesOptions } from './AsyncBatchUpdatesOptions'
+import type { BatchUpdatesOptions } from './BatchUpdatesOptions'
+import { EntityListAccessor } from './EntityListAccessor'
+import type { Errorable } from './Errorable'
+import { ErrorAccessor } from './ErrorAccessor'
+import type { FieldAccessor } from './FieldAccessor'
+import type { PersistErrorOptions } from './PersistErrorOptions'
+import type { PersistSuccessOptions } from './PersistSuccessOptions'
+
+export const isEntityAccessor = (accessor: unknown): accessor is EntityAccessor =>
+	accessor !== null && typeof accessor === 'object' && '__type' in accessor && accessor.__type === 'EntityAccessor'
+
+interface EntityAccessor extends Errorable {
+	readonly __type: 'EntityAccessor'
+	/**
+	 * The key is a unique identifier of the entity. It is not the id of the entity.
+	 */
+	readonly key?: EntityRealmKey
+	readonly name: EntityName
+	readonly hasUnpersistedChanges: boolean
+	readonly errors: ErrorAccessor | undefined
+	readonly environment: Environment
+	readonly getAccessor: EntityAccessor.GetEntityAccessor
+	readonly idOnServer: EntityId | undefined
+	readonly id: EntityId
+	readonly existsOnServer: boolean
+
+	addError: ErrorAccessor.AddError
+
+	addEventListener: EntityAccessor.AddEventListener
+
+	batchUpdates(performUpdates: EntityAccessor.BatchUpdatesHandler): void
+
+	connectEntityAtField(field: SugaredRelativeSingleEntity | string, entityToConnect: EntityAccessor): void
+
+	disconnectEntityAtField(field: SugaredRelativeSingleEntity | string, initializeReplacement?: EntityAccessor.BatchUpdatesHandler): void
+
+	deleteEntity(): void
+
+	updateValues(fieldValuePairs: EntityAccessor.FieldValuePairs): void
+
+	/**
+	 * Please keep in mind that this method signature is literally impossible to implement safely. The generic parameter
+	 * is really just a way to succinctly write a type cast. Nothing more, really.
+	 */
+	getField<Value extends FieldValue = FieldValue>(field: SugaredRelativeSingleField | string | RelativeSingleField): FieldAccessor<Value>
+
+	getEntity(entity: SugaredRelativeSingleEntity | string | RelativeSingleEntity): EntityAccessor
+
+	getEntityList(entityList: SugaredRelativeEntityList | string | RelativeEntityList): EntityListAccessor
+
+	getParent(): EntityAccessor | EntityListAccessor | undefined
+
+	getMarker(): HasManyRelationMarker | HasOneRelationMarker | EntitySubTreeMarker | EntityListSubTreeMarker
+}
+
+namespace EntityAccessor {
+	export interface FieldDatum {
+		getAccessor(): NestedAccessor
+	}
+	export type NestedAccessor = EntityAccessor | EntityListAccessor | FieldAccessor<any>
+
+	export type FieldValuePairs =
+		| {
+			[field: string]: FieldValue
+		  }
+		| Iterable<[SugaredRelativeSingleField | string, FieldValue]>
+
+	export type FieldData = Map<FieldName, FieldDatum>
+
+	export type GetEntityAccessor = () => EntityAccessor
+	export type BatchUpdatesHandler = (getAccessor: GetEntityAccessor, options: BatchUpdatesOptions) => void
+	export type UpdateListener = (accessor: EntityAccessor) => void
+
+	export type BeforePersistHandler = (
+		getAccessor: GetEntityAccessor,
+		options: AsyncBatchUpdatesOptions,
+	) => void | BeforePersistHandler | Promise<void | BeforePersistHandler>
+
+	export type PersistErrorHandler = (
+		getAccessor: GetEntityAccessor,
+		options: PersistErrorOptions,
+	) => void | Promise<void>
+
+	export type PersistSuccessHandler = (
+		getAccessor: GetEntityAccessor,
+		options: PersistSuccessOptions,
+	) => void | PersistSuccessHandler | Promise<void | PersistSuccessHandler>
+
+	export type RuntimeEntityEventListenerMap = {
+		beforePersist: BeforePersistHandler
+		beforeUpdate: BatchUpdatesHandler
+		connectionUpdate: UpdateListener
+		persistError: PersistErrorHandler
+		persistSuccess: PersistSuccessHandler
+		update: UpdateListener
+	}
+	export type EntityEventListenerMap =
+		& RuntimeEntityEventListenerMap
+		& {
+			initialize: BatchUpdatesHandler
+		}
+	export type EntityEventType = keyof EntityEventListenerMap
+
+	export type AddEventListener = <Type extends keyof EntityAccessor.RuntimeEntityEventListenerMap>(
+		event: { type: Type; key?: string },
+		listener: EntityAccessor.EntityEventListenerMap[Type],
+	) => () => void
+}
+
+export type { EntityAccessor }

package/src/types/EntityListAccessor.ts

@@ -0,0 +1,123 @@
+import type { Environment } from '../environment'
+import type { EntityId, EntityName, EntityRealmKey } from '../treeParameters'
+import type { AsyncBatchUpdatesOptions } from './AsyncBatchUpdatesOptions'
+import type { BatchUpdatesOptions } from './BatchUpdatesOptions'
+import type { EntityAccessor } from './EntityAccessor'
+import type { Errorable } from './Errorable'
+import { ErrorAccessor } from './ErrorAccessor'
+import type { PersistErrorOptions } from './PersistErrorOptions'
+import type { PersistSuccessOptions } from './PersistSuccessOptions'
+import { RuntimeId } from '../RuntimeId'
+import { EntityListSubTreeMarker, HasManyRelationMarker } from '../markers'
+
+export const isEntityListAccessor = (accessor: unknown): accessor is EntityListAccessor =>
+	accessor !== null && typeof accessor === 'object' && '__type' in accessor && accessor.__type === 'EntityListAccessor'
+
+interface EntityListAccessor extends Errorable {
+	readonly __type: 'EntityListAccessor'
+	readonly name: EntityName
+	readonly hasUnpersistedChanges: boolean
+	readonly errors: ErrorAccessor | undefined
+	readonly environment: Environment
+	readonly getAccessor: EntityListAccessor.GetEntityListAccessor
+
+	/**
+	 * Returns all entity keys that are on the list.
+	 * **KEYS ARE NOT IDS!**
+	 * @see EntityAccessor.key
+	 */
+	keys(): IterableIterator<EntityRealmKey>
+
+	ids(): IterableIterator<EntityId>
+
+	/**
+	 * This will only contain the ids that the server knows about. Not necessarily the ids that have been added on
+	 * the list since the last server query.
+	 */
+	idsPersistedOnServer: Set<EntityId>
+
+	[Symbol.iterator](): IterableIterator<EntityAccessor>
+
+	hasEntityId(id: EntityId): boolean
+
+	isEmpty(): boolean
+
+	length: number
+
+	deleteAll(): void
+
+	disconnectAll(): void
+
+	addError(error: ErrorAccessor.Error | string): () => void
+
+	addEventListener: EntityListAccessor.AddEventListener
+
+	addChildEventListener: EntityListAccessor.AddChildEventListener
+
+	batchUpdates(performUpdates: EntityListAccessor.BatchUpdatesHandler): void
+
+	connectEntity(entityToConnect: EntityAccessor): void
+
+	createNewEntity(initialize?: EntityAccessor.BatchUpdatesHandler): RuntimeId
+	disconnectEntity(childEntity: EntityAccessor, options?: { noPersist?: boolean }): void
+	getChildEntityById(id: EntityId): EntityAccessor
+
+	getParent(): EntityAccessor | undefined
+
+	getMarker(): EntityListSubTreeMarker | HasManyRelationMarker
+}
+
+namespace EntityListAccessor {
+	export type GetEntityListAccessor = () => EntityListAccessor
+	export type BatchUpdatesHandler = (getAccessor: GetEntityListAccessor, options: BatchUpdatesOptions) => void
+
+	export type UpdateListener = (accessor: EntityListAccessor) => void
+
+	export type BeforePersistHandler = (
+		getAccessor: GetEntityListAccessor,
+		options: AsyncBatchUpdatesOptions,
+	) => void | Promise<void | BeforePersistHandler>
+
+	export type PersistErrorHandler = (
+		getAccessor: GetEntityListAccessor,
+		options: PersistErrorOptions,
+	) => void | Promise<void>
+
+	export type PersistSuccessHandler = (
+		getAccessor: GetEntityListAccessor,
+		options: PersistSuccessOptions,
+	) => void | Promise<void | PersistSuccessHandler>
+
+	export type ChildEventListenerMap = {
+		childBeforeUpdate: EntityAccessor.BatchUpdatesHandler
+		childInitialize: EntityAccessor.BatchUpdatesHandler
+		childUpdate: EntityAccessor.UpdateListener
+	}
+
+	export type RuntimeEntityListEventListenerMap = {
+		beforePersist: BeforePersistHandler
+		beforeUpdate: BatchUpdatesHandler
+		persistError: PersistErrorHandler
+		persistSuccess: PersistSuccessHandler
+		update: UpdateListener
+	}
+	export type EntityListEventListenerMap =
+		& RuntimeEntityListEventListenerMap
+		& {
+			initialize: BatchUpdatesHandler
+		}
+
+	export type EntityListEventType = keyof EntityListEventListenerMap
+
+	export type AddEventListener = <Type extends keyof EntityListAccessor.RuntimeEntityListEventListenerMap>(
+		event: { type: Type; key?: string },
+		listener: EntityListAccessor.EntityListEventListenerMap[Type],
+	) => () => void
+
+	export type AddChildEventListener = <Type extends keyof EntityAccessor.EntityEventListenerMap>(
+		event: { type: Type; key?: string },
+		listener: EntityAccessor.EntityEventListenerMap[Type],
+	) => () => void
+}
+
+export { type EntityListAccessor }

package/src/types/ErrorAccessor.ts

@@ -0,0 +1,43 @@
+import type { Result } from '@contember/client'
+
+interface ErrorAccessor {
+	readonly errors: ErrorAccessor.Error[]
+}
+
+namespace ErrorAccessor {
+	export type ErrorId = number
+	export type Error = ExecutionError | ValidationError
+	export type ErrorsById = Map<ErrorId, Error>
+	export type ClearError = () => void
+
+	export type AddError = (error: ErrorAccessor.Error | string) => ClearError
+
+	export type ExecutionErrors = ExecutionError[]
+
+	export interface ExecutionError {
+		type: 'execution'
+		code: Result.ExecutionErrorType
+		developerMessage: string | null
+	}
+
+	export type ValidationErrors = ValidationError[]
+
+	export interface ValidationError {
+		type: 'validation'
+		code: WellKnownErrorCode | string | undefined
+		message: string
+	}
+
+	export type WellKnownErrorCode = 'fieldRequired'
+
+	export const normalizeError = (error: Error | string): Error => typeof error === 'string' ? {
+		type: 'validation',
+		message: error,
+		code: undefined,
+	} : error
+}
+export { ErrorAccessor }
+
+export interface ErrorAccessorHolder {
+	readonly errors: ErrorAccessor | undefined
+}

package/src/types/Errorable.ts

@@ -0,0 +1,5 @@
+import type { ErrorAccessor } from './ErrorAccessor'
+
+export interface Errorable {
+	errors: ErrorAccessor | undefined
+}

package/src/types/ExtendTree.ts

@@ -0,0 +1,10 @@
+import type { Environment } from '../environment'
+import type { TreeRootId } from '../treeParameters'
+
+export interface ExtendTreeOptions {
+	signal?: AbortSignal
+	environment?: Environment
+	force?: boolean
+}
+
+export type ExtendTree<Node> = (newFragment: Node, options?: ExtendTreeOptions) => Promise<TreeRootId | undefined>

package/src/types/FieldAccessor.ts

@@ -0,0 +1,74 @@
+import type { FieldName, FieldValue } from '../treeParameters'
+import type { BatchUpdatesOptions } from './BatchUpdatesOptions'
+import type { Errorable } from './Errorable'
+import { ErrorAccessor } from './ErrorAccessor'
+import type { SchemaColumn } from '../schema'
+import { EntityAccessor } from './EntityAccessor'
+
+
+export const isFieldAccessor = (accessor: unknown): accessor is FieldAccessor =>
+	accessor !== null && typeof accessor === 'object' && '__type' in accessor && accessor.__type === 'FieldAccessor'
+
+interface FieldAccessor<Value extends FieldValue = FieldValue> extends Errorable {
+	readonly __type: 'FieldAccessor'
+	readonly fieldName: FieldName
+	readonly value: Value | null
+	readonly valueOnServer: Value | null
+	readonly defaultValue: Value | undefined
+	readonly errors: ErrorAccessor | undefined
+	readonly hasUnpersistedChanges: boolean
+	readonly getAccessor: FieldAccessor.GetFieldAccessor<Value>
+	readonly schema: SchemaColumn
+
+	addError(error: ErrorAccessor.Error | string): ErrorAccessor.ClearError
+
+	clearErrors(): void
+
+	addEventListener: FieldAccessor.AddEventListener<Value>
+
+	updateValue(newValue: Value | null, options?: FieldAccessor.UpdateOptions): void
+
+	isTouchedBy(agent: FieldAccessor.TouchAgent): boolean
+
+	isTouched: boolean
+
+	getParent(): EntityAccessor
+}
+
+namespace FieldAccessor {
+	export type TouchAgent = 'user' | (string & {})
+	export interface UpdateOptions {
+		agent?: TouchAgent
+	}
+
+	export type GetFieldAccessor<Value extends FieldValue = FieldValue> = () => FieldAccessor<Value>
+
+	export type BeforeUpdateListener<Value extends FieldValue = FieldValue> = (
+		updatedAccessor: FieldAccessor<Value>,
+	) => void
+	export type InitializeListener<Value extends FieldValue = FieldValue> = (
+		getAccessor: GetFieldAccessor<Value>,
+		options: BatchUpdatesOptions,
+	) => void
+	export type UpdateListener<Value extends FieldValue = FieldValue> = (accessor: FieldAccessor<Value>) => void
+
+	export type RuntimeFieldEventListenerMap<Value extends FieldValue = FieldValue> = {
+		beforeUpdate: BeforeUpdateListener<Value>
+		update: UpdateListener<Value>
+	}
+
+	export type FieldEventListenerMap<Value extends FieldValue = FieldValue> =
+		& RuntimeFieldEventListenerMap<Value>
+		& {
+			initialize: InitializeListener<Value>
+		}
+
+	export type FieldEventType = keyof FieldEventListenerMap
+
+	export type AddEventListener<Value extends FieldValue = FieldValue> = <Type extends FieldEventType>(
+		event: { type: Type; key?: string },
+		listener: FieldEventListenerMap<Value>[Type],
+	) => () => void
+}
+
+export { type FieldAccessor }

package/src/types/GetEntityByKey.ts

@@ -0,0 +1,3 @@
+import type { EntityAccessor } from './EntityAccessor'
+
+export type GetEntityByKey = (key: string | (() => EntityAccessor)) => EntityAccessor

package/src/types/GetEntityListSubTree.ts

@@ -0,0 +1,14 @@
+import type { Environment } from '../environment'
+import type {
+	Alias,
+	SugaredQualifiedEntityList,
+	SugaredUnconstrainedQualifiedEntityList,
+	TreeRootId,
+} from '../treeParameters'
+import type { EntityListAccessor } from './EntityListAccessor'
+
+export type GetEntityListSubTree = (
+	parametersOrAlias: Alias | SugaredQualifiedEntityList | SugaredUnconstrainedQualifiedEntityList,
+	treeId?: TreeRootId,
+	environment?: Environment,
+) => EntityListAccessor

package/src/types/GetEntitySubTree.ts

@@ -0,0 +1,14 @@
+import type { Environment } from '../environment'
+import type {
+	Alias,
+	SugaredQualifiedSingleEntity,
+	SugaredUnconstrainedQualifiedSingleEntity,
+	TreeRootId,
+} from '../treeParameters'
+import type { EntityAccessor } from './EntityAccessor'
+
+export type GetEntitySubTree = (
+	parametersOrAlias: Alias | SugaredQualifiedSingleEntity | SugaredUnconstrainedQualifiedSingleEntity,
+	treeId?: TreeRootId,
+	environment?: Environment,
+) => EntityAccessor

package/src/types/Persist.ts

@@ -0,0 +1,11 @@
+import type { SuccessfulPersistResult } from './PersistResult'
+import type { PersistErrorOptions } from './PersistErrorOptions'
+import type { PersistSuccessOptions } from './PersistSuccessOptions'
+
+export interface PersistOptions {
+	signal?: AbortSignal
+	onPersistSuccess?: (options: PersistSuccessOptions) => void | Promise<void>
+	onPersistError?: (options: PersistErrorOptions) => void | Promise<void>
+}
+
+export type Persist = (options?: PersistOptions) => Promise<SuccessfulPersistResult>

package/src/types/PersistErrorOptions.ts

@@ -0,0 +1,5 @@
+import type { AsyncBatchUpdatesOptions } from './AsyncBatchUpdatesOptions'
+
+
+export interface PersistErrorOptions extends AsyncBatchUpdatesOptions {
+}

package/src/types/PersistResult.ts

@@ -0,0 +1,28 @@
+import { ErrorAccessor } from './ErrorAccessor'
+import { EntityId } from '../treeParameters'
+import { DataBindingTransactionResult } from './DataBindingTransactionResult'
+
+export interface NothingToPersistPersistResult {
+	type: 'nothingToPersist'
+}
+
+export interface JustSuccessPersistResult {
+	type: 'justSuccess'
+	persistedEntityIds: EntityId[]
+	afterPersistError?: any
+}
+
+export interface InvalidInputPersistResult {
+	type: 'invalidInput'
+	errors: ErrorAccessor.Error[]
+	response?: DataBindingTransactionResult
+}
+
+export interface InvalidResponseResult {
+	type: 'invalidResponse'
+	errors: any // todo
+}
+
+export type SuccessfulPersistResult = NothingToPersistPersistResult | JustSuccessPersistResult
+
+export type ErrorPersistResult = InvalidInputPersistResult  | InvalidResponseResult

package/src/types/PersistSuccessOptions.ts

@@ -0,0 +1,5 @@
+import type { AsyncBatchUpdatesOptions } from './AsyncBatchUpdatesOptions'
+
+export interface PersistSuccessOptions extends AsyncBatchUpdatesOptions {
+	successType: 'justSuccess' | 'nothingToPersist'
+}

package/src/types/QueryRequestResponse.ts

@@ -0,0 +1,23 @@
+import type { EntityId, FieldValue } from '../treeParameters'
+
+export type ReceivedFieldData = FieldValue | ReceivedEntityData | Array<ReceivedEntityData>
+
+export type ReceivedEntityData =
+	& {
+		__typename: string
+		id: EntityId
+	}
+	& {
+		[fieldName: string]: ReceivedFieldData
+	}
+
+export type ReceivedData = ReceivedEntityData | ReceivedEntityData[]
+
+export interface ReceivedDataTree {
+	[treeId: string]: ReceivedData | null
+}
+
+export interface QueryRequestResponse {
+	data: ReceivedDataTree
+	errors?: { message: string; path?: string[] }[]
+}

package/src/types/TreeRootAccessor.ts

@@ -0,0 +1,14 @@
+import type { BindingOperations } from './BindingOperations'
+
+// This allows us to have several parallel sub-trees without one having to be the main tree
+// and all the other ones subordinate.
+export class TreeRootAccessor<Node> {
+	/**
+	 * Whenever an update occurs, a new instance of this class is created.
+	 */
+	public constructor(
+		public readonly hasUnpersistedChanges: boolean,
+		public readonly isMutating: boolean,
+		public readonly bindingOperations: BindingOperations<Node>,
+	) {}
+}

package/src/types/index.ts

@@ -0,0 +1,19 @@
+export * from './AsyncBatchUpdatesOptions'
+export * from './BatchUpdatesOptions'
+export * from './BindingOperations'
+export * from './DataBindingTransactionResult'
+export * from './EntityAccessor'
+export * from './EntityListAccessor'
+export * from './Errorable'
+export * from './ErrorAccessor'
+export * from './ExtendTree'
+export * from './GetEntityByKey'
+export * from './GetEntityListSubTree'
+export * from './GetEntitySubTree'
+export * from './FieldAccessor'
+export * from './Persist'
+export * from './PersistErrorOptions'
+export * from './PersistResult'
+export * from './PersistSuccessOptions'
+export * from './QueryRequestResponse'
+export * from './TreeRootAccessor'

package/src/utils/Hashing.ts

@@ -0,0 +1,20 @@
+// TODO update hashing so that for offset, 0 == undefined
+export class Hashing {
+	public static hashAny(array: any[]): number {
+		const json = JSON.stringify(array)
+		return Hashing.hash(json)
+	}
+
+	// Taken from Java
+	public static hash(str: string): number {
+		let hash = 0
+		if (str.length === 0) {
+			return hash
+		}
+		for (let i = 0; i < str.length; i++) {
+			hash = (hash << 5) - hash + str.charCodeAt(i)
+			hash = hash & hash // Convert to 32bit integer
+		}
+		return Math.abs(hash)
+	}
+}

package/src/utils/TreeNodeUtils.ts

@@ -0,0 +1,92 @@
+import { Environment } from '../environment'
+import { BaseRelation, Schema, SchemaColumn, SchemaEntity, SchemaField, SchemaRelation } from '../schema'
+import { BindingError } from '../BindingError'
+import levenshtein from 'js-levenshtein'
+
+export class TreeNodeUtils {
+
+	public static resolveEntity(schema: Schema, entityName: string, type: 'entity' | 'entity list'): SchemaEntity {
+		const entity = schema.getEntityOrUndefined(entityName)
+		if (!entity) {
+			const alternative = this.recommendAlternative(entityName, schema.getEntityNames())
+			const didYouMean = alternative ? `Did you mean '${alternative}'?` : ''
+			throw new BindingError(`Invalid ${type} sub tree: Entity '${entityName}' doesn't exist. ${didYouMean}`)
+		}
+		return entity
+	}
+
+	public static resolveHasOneRelation(environment: Environment, field: string, isReduced: boolean): SchemaRelation {
+		if (isReduced) {
+			return this.resolveRelation(environment, field, 'reduced has-one relation', ['ManyHasMany', 'OneHasMany'])
+		}
+		return this.resolveRelation(environment, field, 'a has-one relation', ['ManyHasOne', 'OneHasOne'])
+	}
+
+
+	public static resolveHasManyRelation(environment: Environment, field: string): SchemaRelation {
+		return this.resolveRelation(environment, field, 'a has-many relation', ['ManyHasMany', 'OneHasMany'])
+	}
+
+	private static resolveRelation(environment: Environment, field: string, relationDescription: string, expectedRelationType: BaseRelation['type'][]): SchemaRelation {
+		return this.resolveField(environment, field, (field): field is SchemaRelation => {
+			return field.__typename === '_Relation' && expectedRelationType.includes(field.type)
+		}, relationDescription)
+	}
+
+	public static resolveColumn(environment: Environment, fieldName: string): SchemaColumn {
+		return this.resolveField(environment, fieldName, (field): field is SchemaColumn => field.__typename === '_Column', 'an ordinary field')
+		// TODO check that defaultValue matches the type
+		// TODO run custom validators
+	}
+
+	private static resolveField<T extends SchemaField>(environment: Environment, fieldName: string, matcher: (field: SchemaField) => field is T, expectedDescription: string): T {
+		const treeLocation = environment.getSubTreeNode()
+		const entity = treeLocation.entity
+		const field = entity.fields.get(fieldName)
+		if (!field) {
+			const alternative = this.recommendAlternative(
+				fieldName,
+				Array.from(entity.fields)
+					.filter(([, field]) => matcher(field))
+					.map(([fieldName]) => fieldName),
+			)
+			const didYouMean = alternative ? `Did you mean '${alternative}'?` : ''
+			throw new BindingError(`Field '${fieldName}' doesn't exist on ${this.describeLocation(environment)}. ${didYouMean}`)
+		}
+		if (!matcher(field)) {
+			const actual = field.__typename === '_Column' ? 'an ordinary field' : `a ${field.type} relation`
+			throw new BindingError(
+				`Invalid field: the name '${field.name}' on ${this.describeLocation(environment)} ` +
+				`refers to ${actual} but is being used as a ${expectedDescription}.`,
+			)
+		}
+		return field
+	}
+
+	public static describeLocation(environment: Environment): string {
+		const path = []
+		const loc = environment.getSubTreeNode()
+		for (let env = environment; ; env = env.getParent()) {
+			const node = env.getSubTreeNode()
+			if (node.type === 'subtree-entity' || node.type === 'subtree-entity-list') {
+				return `entity '${loc.entity.name}' in path '${[node.entity.name, ...path.reverse()].join('.')}'`
+			}
+			path.push(node.field.name)
+		}
+	}
+
+	public static recommendAlternative(original: string, possibleAlternatives: Iterable<string>): string | undefined {
+		let bestAlternative: string | undefined = undefined
+		let bestAlternativeDistance = Number.MAX_SAFE_INTEGER
+
+		for (const alternative of possibleAlternatives) {
+			const distance = levenshtein(original, alternative)
+
+			if (distance < bestAlternativeDistance) {
+				bestAlternative = alternative
+				bestAlternativeDistance = distance
+			}
+		}
+		return bestAlternative
+	}
+}

package/src/utils/assertNever.ts

@@ -0,0 +1,7 @@
+import { BindingError } from '../BindingError'
+
+export function assertNever(_: never): never {
+	throw new BindingError(
+		`FATAL ERROR. This should absolutely never have happened. Please report this bug.`,
+	)
+}