@contember/bindx 0.1.0

package/src/store/EntitySnapshotStore.ts

@@ -0,0 +1,260 @@
+import {
+	createEntitySnapshot,
+	type EntitySnapshot,
+} from './snapshots.js'
+
+/**
+ * Manages entity snapshots — core CRUD for immutable entity data.
+ *
+ * Entity snapshots are keyed by composite strings (e.g., "entityType:id").
+ * All snapshots are immutable (frozen) objects. Mutations create new snapshot instances.
+ *
+ * Follows the same sub-store pattern as ErrorStore, RelationStore, etc.
+ * SnapshotStore delegates entity snapshot operations here.
+ */
+export class EntitySnapshotStore {
+	private readonly snapshots = new Map<string, EntitySnapshot>()
+
+	get(key: string): EntitySnapshot | undefined {
+		return this.snapshots.get(key)
+	}
+
+	has(key: string): boolean {
+		return this.snapshots.has(key)
+	}
+
+	/**
+	 * Sets entity data, merging with existing data if present.
+	 * Returns the new snapshot. Does NOT handle notification or meta updates.
+	 */
+	setData<T extends object>(
+		key: string,
+		id: string,
+		entityType: string,
+		data: T,
+		isServerData: boolean,
+	): EntitySnapshot<T> {
+		const existing = this.snapshots.get(key)
+
+		const mergedData = existing?.data
+			? { ...existing.data, ...data } as T
+			: data
+
+		const serverData = isServerData
+			? (existing?.serverData ? { ...existing.serverData, ...data } as T : data)
+			: (existing?.serverData as T) ?? mergedData
+
+		const newSnapshot = createEntitySnapshot(
+			id,
+			entityType,
+			mergedData,
+			serverData,
+			(existing?.version ?? 0) + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+		return newSnapshot
+	}
+
+	/**
+	 * Updates specific fields on an existing entity snapshot.
+	 * Returns the new snapshot, or undefined if entity doesn't exist.
+	 */
+	updateFields<T extends object>(
+		key: string,
+		updates: Partial<T>,
+	): EntitySnapshot<T> | undefined {
+		const existing = this.snapshots.get(key)
+		if (!existing) return undefined
+
+		const newData = { ...existing.data, ...updates } as T
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			newData,
+			existing.serverData as T,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+		return newSnapshot
+	}
+
+	/**
+	 * Sets a nested field value on an existing entity snapshot.
+	 * Returns true if the snapshot was updated, false if entity doesn't exist.
+	 */
+	setFieldValue(key: string, fieldPath: string[], value: unknown): boolean {
+		const existing = this.snapshots.get(key)
+		if (!existing) return false
+
+		const newData = setNestedValue({ ...existing.data }, fieldPath, value)
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			newData,
+			existing.serverData,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+		return true
+	}
+
+	/**
+	 * Commits current data as server data (serverData = data).
+	 */
+	commit(key: string): void {
+		const existing = this.snapshots.get(key)
+		if (!existing) return
+
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			existing.data,
+			existing.data,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+	}
+
+	/**
+	 * Resets data to server data (data = serverData).
+	 */
+	reset(key: string): void {
+		const existing = this.snapshots.get(key)
+		if (!existing) return
+
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			existing.serverData,
+			existing.serverData,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+	}
+
+	/**
+	 * Removes an entity snapshot.
+	 */
+	remove(key: string): void {
+		this.snapshots.delete(key)
+	}
+
+	/**
+	 * Bumps the version of an entity snapshot without changing data.
+	 * Used by SubscriptionManager when child entities change.
+	 */
+	bumpVersion(key: string): void {
+		const existing = this.snapshots.get(key)
+		if (!existing) return
+
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			existing.data,
+			existing.serverData,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+	}
+
+	/**
+	 * Commits specific fields by copying their current values to server data.
+	 */
+	commitFields(key: string, fieldNames: string[]): void {
+		const existing = this.snapshots.get(key)
+		if (!existing) return
+
+		const data = existing.data as Record<string, unknown>
+		const serverData = existing.serverData as Record<string, unknown>
+
+		const newServerData = { ...serverData }
+		for (const fieldName of fieldNames) {
+			if (fieldName in data) {
+				newServerData[fieldName] = data[fieldName]
+			}
+		}
+
+		const newSnapshot = createEntitySnapshot(
+			existing.id,
+			existing.entityType,
+			data,
+			newServerData,
+			existing.version + 1,
+		)
+
+		this.snapshots.set(key, newSnapshot)
+	}
+
+	/**
+	 * Exports snapshots for the given keys.
+	 */
+	exportSnapshots(keys: string[]): Map<string, EntitySnapshot> {
+		const result = new Map<string, EntitySnapshot>()
+		for (const key of keys) {
+			const snapshot = this.snapshots.get(key)
+			if (snapshot) {
+				result.set(key, snapshot)
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Imports snapshots, overwriting any existing entries.
+	 * Returns the set of keys that were imported.
+	 */
+	importSnapshots(snapshots: Map<string, EntitySnapshot>): Set<string> {
+		const keys = new Set<string>()
+		for (const [key, snapshot] of snapshots) {
+			this.snapshots.set(key, snapshot)
+			keys.add(key)
+		}
+		return keys
+	}
+
+	keys(): IterableIterator<string> {
+		return this.snapshots.keys()
+	}
+
+	clear(): void {
+		this.snapshots.clear()
+	}
+}
+
+/**
+ * Sets a nested value in an object, returning a new object.
+ */
+function setNestedValue<T extends Record<string, unknown>>(
+	obj: T,
+	path: string[],
+	value: unknown,
+): T {
+	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
+}

package/src/store/ErrorStore.ts

@@ -0,0 +1,251 @@
+import type { ErrorState, FieldError } from '../errors/types.js'
+import { filterStickyErrors } from '../errors/types.js'
+
+/**
+ * Manages error state for fields, entities, and relations.
+ *
+ * Errors are keyed by composite strings:
+ * - Field errors: "entityType:id:fieldName"
+ * - Entity errors: "entityType:id"
+ * - Relation errors: "entityType:id:relationName"
+ */
+export class ErrorStore {
+	/** Field errors keyed by "entityType:id:fieldName" */
+	private readonly fieldErrors = new Map<string, ErrorState>()
+
+	/** Entity-level errors keyed by "entityType:id" */
+	private readonly entityErrors = new Map<string, ErrorState>()
+
+	/** Relation errors keyed by "entityType:id:relationName" */
+	private readonly relationErrors = new Map<string, ErrorState>()
+
+	// ==================== Field Errors ====================
+
+	/**
+	 * Gets field errors for a specific field.
+	 */
+	getFieldErrors(fieldKey: string): readonly FieldError[] {
+		return this.fieldErrors.get(fieldKey)?.errors ?? []
+	}
+
+	/**
+	 * Adds an error to a field.
+	 */
+	addFieldError(fieldKey: string, error: FieldError): void {
+		const existing = this.fieldErrors.get(fieldKey)
+		const errors = existing ? [...existing.errors, error] : [error]
+		this.fieldErrors.set(fieldKey, { errors, version: (existing?.version ?? 0) + 1 })
+	}
+
+	/**
+	 * Clears field errors, optionally filtering by source.
+	 */
+	clearFieldErrors(fieldKey: string, source?: 'client' | 'server'): void {
+		const existing = this.fieldErrors.get(fieldKey)
+		if (!existing) return
+
+		if (source === undefined) {
+			this.fieldErrors.delete(fieldKey)
+		} else {
+			const filtered = existing.errors.filter(e => e.source !== source)
+			if (filtered.length === 0) {
+				this.fieldErrors.delete(fieldKey)
+			} else {
+				this.fieldErrors.set(fieldKey, { errors: filtered, version: existing.version + 1 })
+			}
+		}
+	}
+
+	/**
+	 * Clears non-sticky client errors for a field.
+	 * Called when field value changes.
+	 * Returns true if any errors were removed.
+	 */
+	clearNonStickyFieldErrors(fieldKey: string): boolean {
+		const existing = this.fieldErrors.get(fieldKey)
+		if (!existing) return false
+
+		const filtered = filterStickyErrors(existing.errors)
+		if (filtered.length === existing.errors.length) return false
+
+		if (filtered.length === 0) {
+			this.fieldErrors.delete(fieldKey)
+		} else {
+			this.fieldErrors.set(fieldKey, { errors: filtered, version: existing.version + 1 })
+		}
+		return true
+	}
+
+	// ==================== Entity Errors ====================
+
+	/**
+	 * Gets entity-level errors.
+	 */
+	getEntityErrors(entityKey: string): readonly FieldError[] {
+		return this.entityErrors.get(entityKey)?.errors ?? []
+	}
+
+	/**
+	 * Adds an entity-level error.
+	 */
+	addEntityError(entityKey: string, error: FieldError): void {
+		const existing = this.entityErrors.get(entityKey)
+		const errors = existing ? [...existing.errors, error] : [error]
+		this.entityErrors.set(entityKey, { errors, version: (existing?.version ?? 0) + 1 })
+	}
+
+	/**
+	 * Clears entity-level errors, optionally filtering by source.
+	 */
+	clearEntityErrors(entityKey: string, source?: 'client' | 'server'): void {
+		const existing = this.entityErrors.get(entityKey)
+		if (!existing) return
+
+		if (source === undefined) {
+			this.entityErrors.delete(entityKey)
+		} else {
+			const filtered = existing.errors.filter(e => e.source !== source)
+			if (filtered.length === 0) {
+				this.entityErrors.delete(entityKey)
+			} else {
+				this.entityErrors.set(entityKey, { errors: filtered, version: existing.version + 1 })
+			}
+		}
+	}
+
+	// ==================== Relation Errors ====================
+
+	/**
+	 * Gets relation errors.
+	 */
+	getRelationErrors(relationKey: string): readonly FieldError[] {
+		return this.relationErrors.get(relationKey)?.errors ?? []
+	}
+
+	/**
+	 * Adds a relation error.
+	 */
+	addRelationError(relationKey: string, error: FieldError): void {
+		const existing = this.relationErrors.get(relationKey)
+		const errors = existing ? [...existing.errors, error] : [error]
+		this.relationErrors.set(relationKey, { errors, version: (existing?.version ?? 0) + 1 })
+	}
+
+	/**
+	 * Clears relation errors, optionally filtering by source.
+	 */
+	clearRelationErrors(relationKey: string, source?: 'client' | 'server'): void {
+		const existing = this.relationErrors.get(relationKey)
+		if (!existing) return
+
+		if (source === undefined) {
+			this.relationErrors.delete(relationKey)
+		} else {
+			const filtered = existing.errors.filter(e => e.source !== source)
+			if (filtered.length === 0) {
+				this.relationErrors.delete(relationKey)
+			} else {
+				this.relationErrors.set(relationKey, { errors: filtered, version: existing.version + 1 })
+			}
+		}
+	}
+
+	// ==================== Bulk Operations ====================
+
+	/**
+	 * Clears all server errors for an entity (entity-level, fields, and relations).
+	 * Called before persist to clear stale server errors.
+	 */
+	clearAllServerErrors(entityKey: string, keyPrefix: string): void {
+		this.clearEntityErrors(entityKey, 'server')
+
+		for (const key of this.fieldErrors.keys()) {
+			if (key.startsWith(keyPrefix)) {
+				this.clearFieldErrors(key, 'server')
+			}
+		}
+
+		for (const key of this.relationErrors.keys()) {
+			if (key.startsWith(keyPrefix)) {
+				this.clearRelationErrors(key, 'server')
+			}
+		}
+	}
+
+	/**
+	 * Clears all errors for an entity (entity-level, fields, and relations).
+	 */
+	clearAllErrors(entityKey: string, keyPrefix: string): void {
+		this.entityErrors.delete(entityKey)
+
+		for (const key of [...this.fieldErrors.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.fieldErrors.delete(key)
+			}
+		}
+
+		for (const key of [...this.relationErrors.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.relationErrors.delete(key)
+			}
+		}
+	}
+
+	/**
+	 * Checks if an entity has any client errors (entity-level, fields, or relations).
+	 * Used to block persist when validation errors exist.
+	 */
+	hasClientErrors(entityKey: string, keyPrefix: string): boolean {
+		const entityErrs = this.entityErrors.get(entityKey)
+		if (entityErrs?.errors.some(e => e.source === 'client')) {
+			return true
+		}
+
+		for (const [key, state] of this.fieldErrors) {
+			if (key.startsWith(keyPrefix) && state.errors.some(e => e.source === 'client')) {
+				return true
+			}
+		}
+
+		for (const [key, state] of this.relationErrors) {
+			if (key.startsWith(keyPrefix) && state.errors.some(e => e.source === 'client')) {
+				return true
+			}
+		}
+
+		return false
+	}
+
+	/**
+	 * Checks if an entity has any errors at all.
+	 */
+	hasAnyErrors(entityKey: string, keyPrefix: string): boolean {
+		const entityErrs = this.entityErrors.get(entityKey)
+		if (entityErrs && entityErrs.errors.length > 0) {
+			return true
+		}
+
+		for (const [key, state] of this.fieldErrors) {
+			if (key.startsWith(keyPrefix) && state.errors.length > 0) {
+				return true
+			}
+		}
+
+		for (const [key, state] of this.relationErrors) {
+			if (key.startsWith(keyPrefix) && state.errors.length > 0) {
+				return true
+			}
+		}
+
+		return false
+	}
+
+	/**
+	 * Clears all error data.
+	 */
+	clear(): void {
+		this.fieldErrors.clear()
+		this.entityErrors.clear()
+		this.relationErrors.clear()
+	}
+}