@contember/bindx 0.1.0

package/src/core/Disposable.ts

@@ -0,0 +1,126 @@
+/**
+ * Disposable pattern for cleanup management.
+ * Ensures proper cleanup of subscriptions and resources.
+ */
+
+/**
+ * Interface for objects that can be disposed.
+ */
+export interface Disposable {
+	dispose(): void
+}
+
+/**
+ * A group of disposables that can be disposed together.
+ * Provides safe cleanup even if individual dispose() calls throw.
+ */
+export class DisposableGroup implements Disposable {
+	private disposables: Disposable[] = []
+	private disposed = false
+
+	/**
+	 * Adds a disposable to the group.
+	 * If the group is already disposed, the disposable is disposed immediately.
+	 */
+	add(disposable: Disposable): void {
+		if (this.disposed) {
+			// Already disposed, dispose immediately
+			try {
+				disposable.dispose()
+			} catch (error) {
+				console.error('Error disposing:', error)
+			}
+			return
+		}
+		this.disposables.push(disposable)
+	}
+
+	/**
+	 * Adds a callback as a disposable.
+	 */
+	addCallback(callback: () => void): void {
+		this.add({ dispose: callback })
+	}
+
+	/**
+	 * Adds an unsubscribe function as a disposable.
+	 */
+	addUnsubscribe(unsubscribe: () => void): void {
+		this.addCallback(unsubscribe)
+	}
+
+	/**
+	 * Disposes all items in the group.
+	 * Each item is disposed even if previous ones throw.
+	 */
+	dispose(): void {
+		if (this.disposed) return
+		this.disposed = true
+
+		const errors: Error[] = []
+
+		for (const disposable of this.disposables) {
+			try {
+				disposable.dispose()
+			} catch (error) {
+				errors.push(error instanceof Error ? error : new Error(String(error)))
+			}
+		}
+
+		this.disposables = []
+
+		if (errors.length > 0) {
+			console.error('Errors during disposal:', errors)
+		}
+	}
+
+	/**
+	 * Checks if the group has been disposed.
+	 */
+	isDisposed(): boolean {
+		return this.disposed
+	}
+
+	/**
+	 * Gets the number of disposables in the group.
+	 */
+	get size(): number {
+		return this.disposables.length
+	}
+}
+
+/**
+ * Creates a disposable from a callback function.
+ */
+export function createDisposable(callback: () => void): Disposable {
+	let disposed = false
+	return {
+		dispose() {
+			if (disposed) return
+			disposed = true
+			callback()
+		},
+	}
+}
+
+/**
+ * Combines multiple disposables into one.
+ */
+export function combineDisposables(...disposables: Disposable[]): Disposable {
+	const group = new DisposableGroup()
+	for (const d of disposables) {
+		group.add(d)
+	}
+	return group
+}
+
+/**
+ * Type guard to check if something is disposable.
+ */
+export function isDisposable(value: unknown): value is Disposable {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as Disposable).dispose === 'function'
+	)
+}

package/src/core/EntityLoader.ts

@@ -0,0 +1,169 @@
+import type { BackendAdapter } from '../adapter/types.js'
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type { QuerySpec } from '../selection/buildQuery.js'
+import type { EntityWhere, EntityOrderBy } from '../selection/queryTypes.js'
+import { createLoadError, type FieldError } from '../errors/types.js'
+
+/**
+ * Checks if an error is an AbortError that should be rethrown.
+ */
+function isAbortError(error: unknown): boolean {
+	return error instanceof DOMException && error.name === 'AbortError'
+}
+
+/**
+ * Normalizes unknown error to Error instance.
+ */
+function normalizeError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Result of entity loading operation
+ */
+export type EntityLoadResult<T> =
+	| { status: 'success'; data: T }
+	| { status: 'error'; error: FieldError }
+	| { status: 'not_found' }
+
+/**
+ * Result of entity list loading operation
+ */
+export type EntityListLoadResult<T> =
+	| { status: 'success'; data: T[] }
+	| { status: 'error'; error: FieldError }
+
+/**
+ * Options for loading a single entity
+ */
+export interface LoadEntityOptions {
+	entityType: string
+	id: string
+	query: QuerySpec
+	useCache?: boolean
+	signal?: AbortSignal
+}
+
+/**
+ * Options for loading entity list
+ */
+export interface LoadEntityListOptions<TEntity = unknown> {
+	entityType: string
+	query: QuerySpec
+	filter?: EntityWhere<TEntity>
+	orderBy?: readonly EntityOrderBy<TEntity>[]
+	limit?: number
+	offset?: number
+	signal?: AbortSignal
+}
+
+/**
+ * Non-React service for loading entities.
+ * Can be used in any JavaScript environment.
+ */
+export class EntityLoader {
+	constructor(
+		private readonly adapter: BackendAdapter,
+		private readonly store: SnapshotStore,
+	) {}
+
+	/**
+	 * Loads a single entity by ID.
+	 */
+	async loadOne<T>(options: LoadEntityOptions): Promise<EntityLoadResult<T>> {
+		const { entityType, id, query, useCache = false, signal } = options
+
+		// Check cache first
+		if (useCache && this.store.hasEntity(entityType, id)) {
+			const snapshot = this.store.getEntitySnapshot(entityType, id)
+			if (snapshot) {
+				return { status: 'success', data: snapshot.data as T }
+			}
+		}
+
+		try {
+			const results = await this.adapter.query(
+				[{ type: 'get', entityType, by: { id }, spec: query }],
+				{ signal },
+			)
+
+			const result = results[0]
+			if (!result || result.type !== 'get' || result.data === null) {
+				return { status: 'not_found' }
+			}
+
+			// Store in snapshot store
+			this.store.setEntityData(entityType, id, result.data, true)
+
+			return { status: 'success', data: result.data as T }
+		} catch (error) {
+			if (isAbortError(error)) {
+				throw error
+			}
+			return { status: 'error', error: createLoadError(normalizeError(error)) }
+		}
+	}
+
+	/**
+	 * Loads multiple entities matching filter.
+	 */
+	async loadMany<T, TEntity = unknown>(options: LoadEntityListOptions<TEntity>): Promise<EntityListLoadResult<T>> {
+		const { entityType, query, filter, orderBy, limit, offset, signal } = options
+
+		try {
+			const results = await this.adapter.query(
+				[{ type: 'list', entityType, filter, orderBy, limit, offset, spec: query }],
+				{ signal },
+			)
+
+			const result = results[0]
+			if (!result || result.type !== 'list') {
+				return {
+					status: 'error',
+					error: createLoadError(new Error('Unexpected query result type')),
+				}
+			}
+
+			// Store each entity in snapshot store
+			for (const item of result.data) {
+				const record = item as Record<string, unknown>
+				if (typeof record['id'] === 'string') {
+					this.store.setEntityData(entityType, record['id'], record, true)
+				}
+			}
+
+			return { status: 'success', data: result.data as T[] }
+		} catch (error) {
+			if (isAbortError(error)) {
+				throw error
+			}
+			return { status: 'error', error: createLoadError(normalizeError(error)) }
+		}
+	}
+
+	/**
+	 * Checks if entity exists in cache.
+	 */
+	hasInCache(entityType: string, id: string): boolean {
+		return this.store.hasEntity(entityType, id)
+	}
+
+	/**
+	 * Gets entity from cache if available.
+	 */
+	getFromCache<T>(entityType: string, id: string): T | null {
+		const snapshot = this.store.getEntitySnapshot(entityType, id)
+		return snapshot ? (snapshot.data as T) : null
+	}
+}
+
+/**
+ * Creates an EntityLoader instance.
+ * Factory function for easier testing and dependency injection.
+ */
+export function createEntityLoader(
+	adapter: BackendAdapter,
+	store: SnapshotStore,
+): EntityLoader {
+	return new EntityLoader(adapter, store)
+}

package/src/core/SelectionResolver.ts

@@ -0,0 +1,78 @@
+import type { SelectionMeta, FluentFragment, SelectionBuilder } from '../selection/types.js'
+import { createSelectionBuilder, SELECTION_META, buildQueryFromSelection } from '../selection/index.js'
+import type { QuerySpec } from '../selection/buildQuery.js'
+
+/**
+ * Input types for selection resolution
+ */
+export type SelectionInput<TModel, TResult extends object> =
+	| FluentDefiner<TModel, TResult>
+	| FluentFragment<TModel, TResult>
+	| SelectionMeta
+
+/**
+ * Type for fluent definer function
+ */
+export type FluentDefiner<TModel, TResult extends object> = (
+	builder: SelectionBuilder<TModel>,
+) => SelectionBuilder<TModel, TResult, object>
+
+/**
+ * Resolves various selection input formats to SelectionMeta.
+ * Works without React - pure function.
+ */
+export function resolveSelectionMeta<TModel, TResult extends object>(
+	input: SelectionInput<TModel, TResult>,
+): SelectionMeta {
+	// Already SelectionMeta
+	if (isSelectionMeta(input)) {
+		return input
+	}
+
+	// FluentFragment
+	if (isFluentFragment(input)) {
+		return input.__meta
+	}
+
+	// FluentDefiner function
+	const builder = createSelectionBuilder<TModel>()
+	const resultBuilder = input(builder)
+	return resultBuilder[SELECTION_META]
+}
+
+/**
+ * Type guard for SelectionMeta
+ */
+function isSelectionMeta(input: unknown): input is SelectionMeta {
+	return (
+		typeof input === 'object' &&
+		input !== null &&
+		'fields' in input &&
+		input.fields instanceof Map
+	)
+}
+
+/**
+ * Type guard for FluentFragment
+ */
+function isFluentFragment<TModel, TResult extends object>(
+	input: unknown,
+): input is FluentFragment<TModel, TResult> {
+	return (
+		typeof input === 'object' &&
+		input !== null &&
+		'__isFragment' in input &&
+		(input as FluentFragment<TModel, TResult>).__isFragment === true
+	)
+}
+
+/**
+ * Builds a QuerySpec from selection input.
+ * Convenience function combining resolution and building.
+ */
+export function buildQuery<TModel, TResult extends object>(
+	input: SelectionInput<TModel, TResult>,
+): QuerySpec {
+	const meta = resolveSelectionMeta(input)
+	return buildQueryFromSelection(meta)
+}

package/src/core/actionClassification.ts

@@ -0,0 +1,196 @@
+import type { Action } from './actions.js'
+
+/**
+ * Keys in the store that are affected by an action.
+ * Used for partial snapshot capture/restore.
+ */
+export interface StoreAffectedKeys {
+	/** Entity keys in format "entityType:id" */
+	entityKeys: string[]
+	/** Relation keys in format "entityType:id:fieldName" */
+	relationKeys: string[]
+	/** Has-many keys in format "entityType:id:fieldName" */
+	hasManyKeys: string[]
+}
+
+/**
+ * Action types that should be tracked for undo/redo.
+ * These are user-initiated data mutations.
+ */
+const TRACKABLE_ACTION_TYPES = new Set<Action['type']>([
+	'SET_FIELD',
+	'SET_ENTITY_DATA',
+	'SET_PLACEHOLDER_DATA',
+	'CONNECT_RELATION',
+	'DISCONNECT_RELATION',
+	'DELETE_RELATION',
+	'RESET_ENTITY',
+	'RESET_RELATION',
+	'ADD_TO_LIST',
+	'REMOVE_FROM_LIST',
+	'MOVE_IN_LIST',
+])
+
+/**
+ * Action types that should be skipped for undo/redo.
+ * These are operational, commit, or error actions.
+ */
+const SKIP_ACTION_TYPES = new Set<Action['type']>([
+	'SET_LOAD_STATE',
+	'SET_PERSISTING',
+	'COMMIT_ENTITY',
+	'COMMIT_RELATION',
+	// Error actions are skipped as errors are ephemeral state
+	'ADD_FIELD_ERROR',
+	'CLEAR_FIELD_ERRORS',
+	'ADD_ENTITY_ERROR',
+	'CLEAR_ENTITY_ERRORS',
+	'ADD_RELATION_ERROR',
+	'CLEAR_RELATION_ERRORS',
+	'CLEAR_ALL_SERVER_ERRORS',
+	'CLEAR_ALL_ERRORS',
+])
+
+/**
+ * Checks if an action should be tracked for undo/redo.
+ * Server data loads (SET_ENTITY_DATA with isServerData=true) are not tracked.
+ */
+export function isTrackableAction(action: Action): boolean {
+	if (!TRACKABLE_ACTION_TYPES.has(action.type)) {
+		return false
+	}
+	// Server data loads are not user-initiated mutations
+	if (action.type === 'SET_ENTITY_DATA' && action.isServerData) {
+		return false
+	}
+	return true
+}
+
+/**
+ * Checks if an action should be skipped for undo/redo.
+ */
+export function isSkippedAction(action: Action): boolean {
+	return SKIP_ACTION_TYPES.has(action.type)
+}
+
+/**
+ * Creates an entity key from type and id.
+ */
+export function createEntityKey(entityType: string, entityId: string): string {
+	return `${entityType}:${entityId}`
+}
+
+/**
+ * Creates a relation key from parent type, id and field name.
+ */
+export function createRelationKey(
+	entityType: string,
+	entityId: string,
+	fieldName: string,
+): string {
+	return `${entityType}:${entityId}:${fieldName}`
+}
+
+/**
+ * Extracts the store keys affected by an action.
+ * Returns entity keys, relation keys, and has-many keys.
+ */
+export function getAffectedKeys(action: Action): StoreAffectedKeys {
+	const entityKeys: string[] = []
+	const relationKeys: string[] = []
+	const hasManyKeys: string[] = []
+
+	switch (action.type) {
+		case 'SET_FIELD':
+		case 'SET_ENTITY_DATA':
+		case 'RESET_ENTITY':
+		case 'COMMIT_ENTITY':
+			entityKeys.push(createEntityKey(action.entityType, action.entityId))
+			break
+
+		case 'CONNECT_RELATION':
+		case 'DISCONNECT_RELATION':
+		case 'DELETE_RELATION':
+		case 'RESET_RELATION':
+		case 'COMMIT_RELATION':
+		case 'SET_PLACEHOLDER_DATA':
+			relationKeys.push(
+				createRelationKey(action.entityType, action.entityId, action.fieldName),
+			)
+			break
+
+		case 'ADD_TO_LIST':
+		case 'REMOVE_FROM_LIST':
+		case 'MOVE_IN_LIST':
+			hasManyKeys.push(
+				createRelationKey(action.entityType, action.entityId, action.fieldName),
+			)
+			break
+
+		case 'SET_LOAD_STATE':
+		case 'SET_PERSISTING':
+		case 'ADD_FIELD_ERROR':
+		case 'CLEAR_FIELD_ERRORS':
+		case 'ADD_ENTITY_ERROR':
+		case 'CLEAR_ENTITY_ERRORS':
+		case 'ADD_RELATION_ERROR':
+		case 'CLEAR_RELATION_ERRORS':
+		case 'CLEAR_ALL_SERVER_ERRORS':
+		case 'CLEAR_ALL_ERRORS':
+			// These don't affect undo-able state
+			break
+
+		default: {
+			const _exhaustive: never = action
+			throw new Error(`Unknown action type: ${(_exhaustive as Action).type}`)
+		}
+	}
+
+	return { entityKeys, relationKeys, hasManyKeys }
+}
+
+/**
+ * Merges two StoreAffectedKeys objects, deduplicating keys.
+ */
+export function mergeAffectedKeys(
+	target: StoreAffectedKeys,
+	source: StoreAffectedKeys,
+): void {
+	for (const key of source.entityKeys) {
+		if (!target.entityKeys.includes(key)) {
+			target.entityKeys.push(key)
+		}
+	}
+	for (const key of source.relationKeys) {
+		if (!target.relationKeys.includes(key)) {
+			target.relationKeys.push(key)
+		}
+	}
+	for (const key of source.hasManyKeys) {
+		if (!target.hasManyKeys.includes(key)) {
+			target.hasManyKeys.push(key)
+		}
+	}
+}
+
+/**
+ * Creates an empty StoreAffectedKeys object.
+ */
+export function createEmptyAffectedKeys(): StoreAffectedKeys {
+	return {
+		entityKeys: [],
+		relationKeys: [],
+		hasManyKeys: [],
+	}
+}
+
+/**
+ * Checks if StoreAffectedKeys is empty.
+ */
+export function isEmptyAffectedKeys(keys: StoreAffectedKeys): boolean {
+	return (
+		keys.entityKeys.length === 0 &&
+		keys.relationKeys.length === 0 &&
+		keys.hasManyKeys.length === 0
+	)
+}