@contember/bindx 0.1.0

package/src/adapter/types.ts

@@ -0,0 +1,199 @@
+import type { QuerySpec } from '../selection/buildQuery.js'
+import type { EntityWhere, EntityOrderBy } from '../selection/queryTypes.js'
+import type { ContemberMutationResult } from '../errors/pathMapper.js'
+
+/**
+ * Options for query operations
+ */
+export interface QueryOptions {
+	/**
+	 * AbortSignal for cancelling the request
+	 */
+	readonly signal?: AbortSignal
+}
+
+/**
+ * Recursive value type for unique where fields (string or number identifiers).
+ * Structurally compatible with Input.UniqueWhere from @contember/schema.
+ */
+export type UniqueWhereValue = string | number | { readonly [field: string]: UniqueWhereValue }
+
+/**
+ * Unique field lookup for single entity queries.
+ * Supports id and any other unique field.
+ */
+export type EntityUniqueWhere = { readonly [field: string]: UniqueWhereValue }
+
+/**
+ * Query for a single entity by unique field(s)
+ */
+export interface GetQuery {
+	readonly type: 'get'
+	readonly entityType: string
+	readonly by: EntityUniqueWhere
+	readonly spec: QuerySpec
+}
+
+/**
+ * Query for a list of entities
+ */
+export interface ListQuery<TEntity = unknown> {
+	readonly type: 'list'
+	readonly entityType: string
+	readonly filter?: EntityWhere<TEntity>
+	readonly orderBy?: readonly EntityOrderBy<TEntity>[]
+	readonly limit?: number
+	readonly offset?: number
+	readonly spec: QuerySpec
+}
+
+/**
+ * Union of all query types
+ */
+export type Query<TEntity = unknown> = GetQuery | ListQuery<TEntity>
+
+/**
+ * Result for a single get query
+ */
+export interface GetQueryResult {
+	readonly type: 'get'
+	readonly data: Record<string, unknown> | null
+}
+
+/**
+ * Result for a list query
+ */
+export interface ListQueryResult {
+	readonly type: 'list'
+	readonly data: readonly Record<string, unknown>[]
+}
+
+/**
+ * Union of query results
+ */
+export type QueryResult = GetQueryResult | ListQueryResult
+
+/**
+ * Result of a persist operation.
+ * Contains detailed error information for error mapping.
+ */
+export interface PersistResult {
+	readonly ok: boolean
+	readonly errorMessage?: string
+	/** Detailed mutation result for error mapping (Contember-specific) */
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * Result of a create operation.
+ * Contains the created entity data or error information.
+ */
+export interface CreateResult {
+	readonly ok: boolean
+	readonly errorMessage?: string
+	/** The created entity data (when ok is true) */
+	readonly data?: Record<string, unknown>
+	/** Detailed mutation result for error mapping (Contember-specific) */
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * Result of a delete operation.
+ */
+export interface DeleteResult {
+	readonly ok: boolean
+	readonly errorMessage?: string
+	/** Detailed mutation result for error mapping (Contember-specific) */
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * A single mutation in a transaction.
+ */
+export interface TransactionMutation {
+	readonly entityType: string
+	readonly entityId: string
+	readonly operation: 'create' | 'update' | 'delete'
+	readonly data?: Record<string, unknown>
+}
+
+/**
+ * Result of a single mutation in a transaction.
+ */
+export interface TransactionMutationResult {
+	readonly entityType: string
+	readonly entityId: string
+	readonly ok: boolean
+	/** Server-assigned ID for creates */
+	readonly persistedId?: string
+	readonly errorMessage?: string
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * Result of a transaction persist operation.
+ * All-or-nothing: if any mutation fails, all are rolled back.
+ */
+export interface TransactionResult {
+	/** Whether all mutations succeeded */
+	readonly ok: boolean
+	/** Results per mutation, in same order as input */
+	readonly results: readonly TransactionMutationResult[]
+}
+
+/**
+ * Interface for backend adapters.
+ * Implement this to connect bindx to your data source.
+ */
+export interface BackendAdapter {
+	/**
+	 * Execute one or more queries in a single request.
+	 * When multiple queries are provided, the adapter should batch them
+	 * into a single network request where possible.
+	 *
+	 * @param queries - Array of queries to execute
+	 * @param options - Optional query options including AbortSignal
+	 * @returns Array of results in the same order as queries
+	 */
+	query(queries: readonly Query[], options?: QueryOptions): Promise<QueryResult[]>
+
+	/**
+	 * Persists changes to an entity.
+	 * Returns a result object with success/failure status and error details.
+	 *
+	 * @param entityType - The type/name of the entity
+	 * @param id - The entity's unique identifier
+	 * @param changes - The changed fields to persist
+	 * @returns Result with ok status and optional error details
+	 */
+	persist(entityType: string, id: string, changes: Record<string, unknown>): Promise<PersistResult>
+
+	/**
+	 * Creates a new entity.
+	 * Returns a result object with the created entity or error details.
+	 *
+	 * @param entityType - The type/name of the entity
+	 * @param data - The initial data for the entity
+	 * @returns Result with ok status, created entity data, and optional error details
+	 */
+	create?(entityType: string, data: Record<string, unknown>): Promise<CreateResult>
+
+	/**
+	 * Deletes an entity.
+	 * Returns a result object with success/failure status.
+	 *
+	 * @param entityType - The type/name of the entity
+	 * @param id - The entity's unique identifier
+	 * @returns Result with ok status and optional error details
+	 */
+	delete?(entityType: string, id: string): Promise<DeleteResult>
+
+	/**
+	 * Persists multiple mutations in a single transaction.
+	 * All-or-nothing: if any mutation fails, all are rolled back.
+	 *
+	 * @param mutations - Array of mutations to execute
+	 * @returns Result with success status and per-mutation results
+	 */
+	persistTransaction?(mutations: readonly TransactionMutation[]): Promise<TransactionResult>
+}

package/src/brand/ComponentBrand.ts

@@ -0,0 +1,28 @@
+/**
+ * ComponentBrand provides unique identity for each component created with createComponent.
+ * Each instance has a unique runtime Symbol for brand validation.
+ * The class structure itself provides nominal typing in TypeScript.
+ */
+export class ComponentBrand {
+	/**
+	 * Private property to ensure nominal typing.
+	 * Each class instance is considered a unique type.
+	 */
+	private readonly __nominal = true
+
+	/**
+	 * Runtime symbol for brand validation.
+	 * Used to check that EntityRef includes required component brands.
+	 */
+	readonly brandSymbol: symbol
+
+	constructor(public readonly name: string) {
+		this.brandSymbol = Symbol(`component_${name}_${Math.random().toString(36).slice(2)}`)
+	}
+}
+
+/**
+ * Type alias for any ComponentBrand.
+ * Used as default/base type in generic constraints.
+ */
+export type AnyBrand = ComponentBrand

package/src/contember/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Contember-specific utilities for bindx
+ *
+ * @packageDocumentation
+ */
+
+// Re-export unified MutationCollector from persistence
+export { MutationCollector, type EntityMutationResult } from '../persistence/MutationCollector.js'
+export { ContemberSchemaMutationAdapter } from '../persistence/ContemberSchemaMutationAdapter.js'
+export type { MutationSchemaProvider } from '../persistence/MutationSchemaProvider.js'
+
+// Re-export commonly used types from @contember/client-content
+export type {
+	SchemaNames,
+	SchemaEntityNames,
+	ContentClientInput,
+} from '@contember/client-content'

package/src/core/ActionDispatcher.ts

@@ -0,0 +1,450 @@
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type { Action } from './actions.js'
+import { EventEmitter } from '../events/EventEmitter.js'
+import {
+	createBeforeEvent,
+	createAfterEvent,
+	captureStateBeforeAction,
+} from '../events/eventFactory.js'
+
+/**
+ * ActionDispatcher centralizes all state mutations.
+ * All changes to the store go through this dispatcher.
+ *
+ * Benefits:
+ * - Single point of control for all mutations
+ * - Easy to add logging, debugging, middleware
+ * - Ensures consistent state updates
+ * - Enables action replay/undo if needed
+ * - Event system for subscriptions and interceptors
+ */
+export class ActionDispatcher {
+	private readonly middlewares: ActionMiddleware[] = []
+	private readonly eventEmitter: EventEmitter
+
+	constructor(
+		private readonly store: SnapshotStore,
+		eventEmitter?: EventEmitter,
+	) {
+		this.eventEmitter = eventEmitter ?? new EventEmitter()
+	}
+
+	/**
+	 * Gets the event emitter for external access.
+	 */
+	getEventEmitter(): EventEmitter {
+		return this.eventEmitter
+	}
+
+	/**
+	 * Dispatches an action to update the store.
+	 * Runs synchronous interceptors (before-events) and emits after-events.
+	 * Async interceptors are skipped with a warning — use dispatchAsync() for those.
+	 */
+	dispatch(action: Action): void {
+		// Run through middlewares first
+		for (const middleware of this.middlewares) {
+			const result = middleware(action, this.store)
+			if (result === false) {
+				// Middleware can cancel the action
+				return
+			}
+		}
+
+		// Create and run before event through interceptors (synchronously)
+		const beforeEvent = createBeforeEvent(action, this.store)
+		if (beforeEvent) {
+			const result = this.eventEmitter.runInterceptorsSync(beforeEvent)
+			if (result === null) {
+				// Interceptor cancelled the action
+				return
+			}
+			// If event was modified, update action accordingly
+			if (result !== beforeEvent) {
+				action = this.updateActionFromEvent(action, result)
+			}
+		}
+
+		// Capture state before execution (for after events)
+		const stateBefore = captureStateBeforeAction(action, this.store)
+
+		// Execute the action
+		this.execute(action)
+
+		// Emit after event
+		const afterEvent = createAfterEvent(action, stateBefore, this.store)
+		if (afterEvent) {
+			this.eventEmitter.emit(afterEvent)
+		}
+	}
+
+	/**
+	 * Dispatches an action with full interceptor support.
+	 * Returns true if the action was executed, false if it was cancelled by an interceptor.
+	 */
+	async dispatchAsync(action: Action): Promise<boolean> {
+		// Run through middlewares first
+		for (const middleware of this.middlewares) {
+			const result = middleware(action, this.store)
+			if (result === false) {
+				return false
+			}
+		}
+
+		// Create and run before event through interceptors
+		const beforeEvent = createBeforeEvent(action, this.store)
+		if (beforeEvent) {
+			const result = await this.eventEmitter.runInterceptors(beforeEvent)
+			if (result === null) {
+				// Interceptor cancelled the action
+				return false
+			}
+			// If event was modified, update action accordingly
+			if (result !== beforeEvent) {
+				action = this.updateActionFromEvent(action, result)
+			}
+		}
+
+		// Capture state before execution (for after events)
+		const stateBefore = captureStateBeforeAction(action, this.store)
+
+		// Execute the action
+		this.execute(action)
+
+		// Emit after event
+		const afterEvent = createAfterEvent(action, stateBefore, this.store)
+		if (afterEvent) {
+			this.eventEmitter.emit(afterEvent)
+		}
+
+		return true
+	}
+
+	/**
+	 * Updates an action based on a modified before event.
+	 * Used when an interceptor modifies the event.
+	 */
+	private updateActionFromEvent(action: Action, event: ReturnType<typeof createBeforeEvent>): Action {
+		if (!event) return action
+
+		switch (action.type) {
+			case 'SET_FIELD':
+				if (event.type === 'field:changing') {
+					return {
+						...action,
+						value: event.newValue,
+					}
+				}
+				break
+
+			case 'CONNECT_RELATION':
+				if (event.type === 'relation:connecting') {
+					return {
+						...action,
+						targetId: event.targetId,
+					}
+				}
+				break
+
+			// Other action types don't have modifiable properties in their before events
+		}
+
+		return action
+	}
+
+	/**
+	 * Adds a middleware to the dispatcher.
+	 * Middlewares are called in order before action execution.
+	 */
+	addMiddleware(middleware: ActionMiddleware): void {
+		this.middlewares.push(middleware)
+	}
+
+	/**
+	 * Removes a middleware from the dispatcher.
+	 */
+	removeMiddleware(middleware: ActionMiddleware): void {
+		const index = this.middlewares.indexOf(middleware)
+		if (index !== -1) {
+			this.middlewares.splice(index, 1)
+		}
+	}
+
+	/**
+	 * Executes an action, updating the store.
+	 */
+	private execute(action: Action): void {
+		switch (action.type) {
+			case 'SET_FIELD':
+				this.store.setFieldValue(
+					action.entityType,
+					action.entityId,
+					action.fieldPath,
+					action.value,
+				)
+				break
+
+			case 'RESET_ENTITY':
+				this.store.resetEntity(action.entityType, action.entityId)
+				break
+
+			case 'COMMIT_ENTITY':
+				this.store.commitEntity(action.entityType, action.entityId)
+				break
+
+			case 'SET_ENTITY_DATA':
+				this.store.setEntityData(
+					action.entityType,
+					action.entityId,
+					action.data,
+					action.isServerData,
+				)
+				break
+
+			case 'CONNECT_RELATION':
+				this.store.setRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					{
+						currentId: action.targetId,
+						state: 'connected',
+					},
+				)
+				break
+
+			case 'DISCONNECT_RELATION':
+				this.store.setRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					{
+						currentId: null,
+						state: 'disconnected',
+						placeholderData: {},
+					},
+				)
+				break
+
+			case 'DELETE_RELATION':
+				this.store.setRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					{
+						state: 'deleted',
+					},
+				)
+				break
+
+			case 'RESET_RELATION':
+				this.store.resetRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+				)
+				break
+
+			case 'COMMIT_RELATION':
+				this.store.commitRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+				)
+				break
+
+			case 'SET_PLACEHOLDER_DATA': {
+				const relation = this.store.getRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+				)
+				const currentPlaceholderData = relation?.placeholderData ?? {}
+				const newPlaceholderData = setNestedValue(
+					{ ...currentPlaceholderData },
+					action.fieldPath,
+					action.value,
+				)
+				this.store.setRelation(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					{ placeholderData: newPlaceholderData },
+				)
+				break
+			}
+
+			case 'ADD_TO_LIST': {
+				// Create entity if itemId not provided
+				const itemId = action.itemId ?? this.store.createEntity(action.targetType, action.itemData)
+				// Add to has-many relation
+				this.store.addToHasMany(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					itemId,
+				)
+				break
+			}
+
+			case 'REMOVE_FROM_LIST':
+				this.store.removeFromHasMany(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					action.itemKey,
+				)
+				break
+
+			case 'MOVE_IN_LIST':
+				this.store.moveInHasMany(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					action.fromIndex,
+					action.toIndex,
+				)
+				break
+
+			case 'SET_LOAD_STATE':
+				this.store.setLoadState(
+					action.entityType,
+					action.entityId,
+					action.status,
+					action.error,
+				)
+				break
+
+			case 'SET_PERSISTING':
+				this.store.setPersisting(
+					action.entityType,
+					action.entityId,
+					action.isPersisting,
+				)
+				break
+
+			case 'ADD_FIELD_ERROR':
+				this.store.addFieldError(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					action.error,
+				)
+				break
+
+			case 'CLEAR_FIELD_ERRORS':
+				this.store.clearFieldErrors(
+					action.entityType,
+					action.entityId,
+					action.fieldName,
+					action.source,
+				)
+				break
+
+			case 'ADD_ENTITY_ERROR':
+				this.store.addEntityError(
+					action.entityType,
+					action.entityId,
+					action.error,
+				)
+				break
+
+			case 'CLEAR_ENTITY_ERRORS':
+				this.store.clearEntityErrors(
+					action.entityType,
+					action.entityId,
+					action.source,
+				)
+				break
+
+			case 'ADD_RELATION_ERROR':
+				this.store.addRelationError(
+					action.entityType,
+					action.entityId,
+					action.relationName,
+					action.error,
+				)
+				break
+
+			case 'CLEAR_RELATION_ERRORS':
+				this.store.clearRelationErrors(
+					action.entityType,
+					action.entityId,
+					action.relationName,
+					action.source,
+				)
+				break
+
+			case 'CLEAR_ALL_SERVER_ERRORS':
+				this.store.clearAllServerErrors(
+					action.entityType,
+					action.entityId,
+				)
+				break
+
+			case 'CLEAR_ALL_ERRORS':
+				this.store.clearAllErrors(
+					action.entityType,
+					action.entityId,
+				)
+				break
+
+			default:
+				// Exhaustive check
+				const _exhaustive: never = action
+				throw new Error(`Unknown action type: ${(_exhaustive as Action).type}`)
+		}
+	}
+}
+
+/**
+ * Middleware function type.
+ * Can inspect/modify actions before execution.
+ * Return false to cancel the action.
+ */
+export type ActionMiddleware = (action: Action, store: SnapshotStore) => boolean | void
+
+/**
+ * Creates a logging middleware for debugging.
+ */
+export function createLoggingMiddleware(
+	prefix: string = '[Bindx]',
+): ActionMiddleware {
+	return (action) => {
+		console.log(`${prefix} ${action.type}`, action)
+	}
+}
+
+// ==================== Helper Functions ====================
+
+/**
+ * Sets a nested value in an object, returning a new object.
+ */
+function setNestedValue(
+	obj: Record<string, unknown>,
+	path: string[],
+	value: unknown,
+): Record<string, unknown> {
+	if (path.length === 0) return obj
+
+	const result = { ...obj }
+	let current: Record<string, unknown> = result
+
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i]!
+		const nextValue = current[key]
+
+		if (typeof nextValue === 'object' && nextValue !== null) {
+			current[key] = { ...(nextValue as Record<string, unknown>) }
+		} else {
+			current[key] = {}
+		}
+
+		current = current[key] as Record<string, unknown>
+	}
+
+	const lastKey = path[path.length - 1]!
+	current[lastKey] = value
+
+	return result
+}