@contember/bindx 0.1.0

package/src/store/SubscriptionManager.ts

@@ -0,0 +1,241 @@
+type Subscriber = () => void
+
+/**
+ * Callback interface for SubscriptionManager to request snapshot version bumps.
+ * This decouples notification logic from entity snapshot storage.
+ */
+export interface SnapshotVersionBumper {
+	bumpEntitySnapshotVersion(key: string): void
+}
+
+/**
+ * Manages subscriptions for entity and relation changes.
+ *
+ * Provides:
+ * - Entity-level subscriptions
+ * - Relation-level subscriptions
+ * - Global subscriptions (any change)
+ * - Parent-child change propagation
+ * - Global version tracking for change detection
+ */
+export class SubscriptionManager {
+	/** Subscribers per entity key */
+	private readonly entitySubscribers = new Map<string, Set<Subscriber>>()
+
+	/** Subscribers per relation key */
+	private readonly relationSubscribers = new Map<string, Set<Subscriber>>()
+
+	/** Global subscribers (notified on any change) */
+	private readonly globalSubscribers = new Set<Subscriber>()
+
+	/** Parent-child relationships: childKey -> Set of parentKeys */
+	private readonly childToParents = new Map<string, Set<string>>()
+
+	/** Global version number for change detection */
+	private globalVersion = 0
+
+	/**
+	 * Subscribe to changes on a specific entity.
+	 * Returns unsubscribe function.
+	 */
+	subscribeToEntity(key: string, callback: Subscriber): () => void {
+		if (!this.entitySubscribers.has(key)) {
+			this.entitySubscribers.set(key, new Set())
+		}
+
+		this.entitySubscribers.get(key)!.add(callback)
+
+		return () => {
+			this.entitySubscribers.get(key)?.delete(callback)
+		}
+	}
+
+	/**
+	 * Subscribe to changes on a specific relation.
+	 * Returns unsubscribe function.
+	 */
+	subscribeToRelation(key: string, callback: Subscriber): () => void {
+		if (!this.relationSubscribers.has(key)) {
+			this.relationSubscribers.set(key, new Set())
+		}
+
+		this.relationSubscribers.get(key)!.add(callback)
+
+		return () => {
+			this.relationSubscribers.get(key)?.delete(callback)
+		}
+	}
+
+	/**
+	 * Subscribe to all changes (global).
+	 * Returns unsubscribe function.
+	 */
+	subscribe(callback: Subscriber): () => void {
+		this.globalSubscribers.add(callback)
+		return () => {
+			this.globalSubscribers.delete(callback)
+		}
+	}
+
+	/**
+	 * Gets the global version number for change detection.
+	 */
+	getVersion(): number {
+		return this.globalVersion
+	}
+
+	/**
+	 * Triggers a global notification to all subscribers.
+	 * Use when external state changes need to trigger re-renders.
+	 */
+	notify(): void {
+		this.globalVersion++
+		for (const sub of this.globalSubscribers) {
+			sub()
+		}
+	}
+
+	// ==================== Parent-Child Relationships ====================
+
+	/**
+	 * Registers a parent-child relationship for change propagation.
+	 * When the child entity changes, parent entity subscribers will be notified.
+	 */
+	registerParentChild(parentKey: string, childKey: string): void {
+		let parents = this.childToParents.get(childKey)
+		if (!parents) {
+			parents = new Set()
+			this.childToParents.set(childKey, parents)
+		}
+		parents.add(parentKey)
+	}
+
+	/**
+	 * Unregisters a parent-child relationship.
+	 */
+	unregisterParentChild(parentKey: string, childKey: string): void {
+		const parents = this.childToParents.get(childKey)
+		if (parents) {
+			parents.delete(parentKey)
+			if (parents.size === 0) {
+				this.childToParents.delete(childKey)
+			}
+		}
+	}
+
+	// ==================== Notification ====================
+
+	/**
+	 * Notifies entity subscribers and propagates changes to parents.
+	 * The bumper callback is used to bump parent entity snapshot versions.
+	 */
+	notifyEntitySubscribers(
+		key: string,
+		bumper: SnapshotVersionBumper,
+		notifiedKeys: Set<string> = new Set(),
+	): void {
+		// Prevent infinite recursion
+		if (notifiedKeys.has(key)) return
+		notifiedKeys.add(key)
+
+		this.globalVersion++
+
+		// Notify entity-specific subscribers
+		const entitySubs = this.entitySubscribers.get(key)
+		if (entitySubs) {
+			for (const sub of entitySubs) {
+				sub()
+			}
+		}
+
+		// Notify parent entity subscribers (propagate change up the tree)
+		const parents = this.childToParents.get(key)
+		if (parents) {
+			for (const parentKey of parents) {
+				// Bump parent snapshot version so useSyncExternalStore detects a change
+				bumper.bumpEntitySnapshotVersion(parentKey)
+				this.notifyEntitySubscribers(parentKey, bumper, notifiedKeys)
+			}
+		}
+
+		// Notify global subscribers (only once, not for each parent)
+		if (notifiedKeys.size === 1) {
+			for (const sub of this.globalSubscribers) {
+				sub()
+			}
+		}
+	}
+
+	/**
+	 * Notifies relation subscribers and the parent entity's subscribers.
+	 * The bumper callback is used to bump the parent entity snapshot version.
+	 * The entityKey is the parent entity key derived from the relation key.
+	 */
+	notifyRelationSubscribers(
+		key: string,
+		entityKey: string,
+		bumper: SnapshotVersionBumper,
+	): void {
+		this.globalVersion++
+
+		// Notify relation-specific subscribers
+		const relationSubs = this.relationSubscribers.get(key)
+		if (relationSubs) {
+			for (const sub of relationSubs) {
+				sub()
+			}
+		}
+
+		// Bump entity snapshot version so isEqual detects a change
+		bumper.bumpEntitySnapshotVersion(entityKey)
+
+		// Notify entity subscribers
+		const entitySubs = this.entitySubscribers.get(entityKey)
+		if (entitySubs) {
+			for (const sub of entitySubs) {
+				sub()
+			}
+		}
+
+		// Notify global subscribers
+		for (const sub of this.globalSubscribers) {
+			sub()
+		}
+	}
+
+	/**
+	 * Notifies entity subscribers without propagation.
+	 * Used during batch imports (e.g., undo/redo).
+	 */
+	notifyEntityDirect(key: string): void {
+		const subs = this.entitySubscribers.get(key)
+		if (subs) {
+			for (const sub of subs) {
+				sub()
+			}
+		}
+	}
+
+	/**
+	 * Notifies relation subscribers without propagation.
+	 * Used during batch imports (e.g., undo/redo).
+	 */
+	notifyRelationDirect(key: string): void {
+		const subs = this.relationSubscribers.get(key)
+		if (subs) {
+			for (const sub of subs) {
+				sub()
+			}
+		}
+	}
+
+	/**
+	 * Bumps global version and notifies global subscribers.
+	 */
+	notifyGlobal(): void {
+		this.globalVersion++
+		for (const sub of this.globalSubscribers) {
+			sub()
+		}
+	}
+}

package/src/store/TouchedStore.ts

@@ -0,0 +1,42 @@
+/**
+ * Manages touched state for entity fields.
+ *
+ * A field is "touched" when the user has interacted with it.
+ * Used for conditional error display (show errors only after user interaction).
+ *
+ * Keys are pre-computed composite strings (e.g., "entityType:id:fieldName").
+ */
+export class TouchedStore {
+	/** Touched state keyed by "entityType:id:fieldName" */
+	private readonly touchedFields = new Map<string, boolean>()
+
+	isFieldTouched(key: string): boolean {
+		return this.touchedFields.get(key) ?? false
+	}
+
+	/**
+	 * Sets the touched state for a field.
+	 * Returns true if the state actually changed.
+	 */
+	setFieldTouched(key: string, touched: boolean): boolean {
+		const current = this.touchedFields.get(key) ?? false
+		if (current === touched) return false
+		this.touchedFields.set(key, touched)
+		return true
+	}
+
+	/**
+	 * Clears all touched state for an entity.
+	 */
+	clearForEntity(keyPrefix: string): void {
+		for (const key of [...this.touchedFields.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.touchedFields.delete(key)
+			}
+		}
+	}
+
+	clear(): void {
+		this.touchedFields.clear()
+	}
+}

package/src/store/entityId.ts

@@ -0,0 +1,43 @@
+/**
+ * Entity ID type detection and generation utilities.
+ *
+ * IDs in Bindx can be:
+ * - Persisted: server-assigned UUIDs
+ * - Temporary: locally created, prefixed with "__temp_"
+ * - Placeholder: disconnected relation placeholders, prefixed with "__placeholder_"
+ */
+
+/**
+ * Checks if an ID is a temporary ID (created locally, not yet persisted).
+ */
+export function isTempId(id: string): boolean {
+	return id.startsWith('__temp_')
+}
+
+/**
+ * Checks if an ID is a placeholder ID (disconnected relation placeholder).
+ */
+export function isPlaceholderId(id: string): boolean {
+	return id.startsWith('__placeholder_')
+}
+
+/**
+ * Checks if an ID is a persisted/real ID from the server.
+ */
+export function isPersistedId(id: string): boolean {
+	return !isTempId(id) && !isPlaceholderId(id)
+}
+
+/**
+ * Generates a new placeholder ID.
+ */
+export function generatePlaceholderId(): string {
+	return `__placeholder_${crypto.randomUUID()}`
+}
+
+/**
+ * Generates a new temporary ID.
+ */
+export function generateTempId(): string {
+	return `__temp_${crypto.randomUUID()}`
+}

package/src/store/index.ts

@@ -0,0 +1,2 @@
+// Store exports are now in main index.ts (SnapshotStore)
+// This file is kept for backwards compatibility during migration

package/src/store/snapshots.ts

@@ -0,0 +1,203 @@
+/**
+ * Immutable snapshot types for React integration.
+ * All snapshots are frozen objects that are replaced (not mutated) on changes.
+ */
+
+import type { HasOneRelationState } from '../handles/types.js'
+
+/**
+ * Status of a data load operation
+ */
+export type LoadStatus = 'idle' | 'loading' | 'success' | 'error' | 'not_found'
+
+/**
+ * Immutable snapshot of entity data stored in the IdentityMap.
+ * A new snapshot is created whenever the entity data changes.
+ */
+export interface EntitySnapshot<T extends object = object> {
+	/** Entity ID */
+	readonly id: string
+	/** Entity type name */
+	readonly entityType: string
+	/** Current (local) data - may differ from serverData if modified */
+	readonly data: Readonly<T>
+	/** Data as received from server - used for dirty tracking and reset */
+	readonly serverData: Readonly<T>
+	/** Version number - incremented on each change, used for comparison */
+	readonly version: number
+}
+
+/**
+ * Immutable snapshot of a scalar field value.
+ */
+export interface FieldSnapshot<T = unknown> {
+	/** Current value */
+	readonly value: T | null
+	/** Server value (for dirty tracking) */
+	readonly serverValue: T | null
+	/** Whether the field has been modified */
+	readonly isDirty: boolean
+}
+
+/**
+ * State information for a has-one relation.
+ */
+export interface HasOneRelationSnapshot<T extends object = object> {
+	/** Current relation state */
+	readonly state: HasOneRelationState
+	/** Current referenced entity ID (null if disconnected) */
+	readonly entityId: string | null
+	/** Server-side entity ID (for dirty tracking) */
+	readonly serverEntityId: string | null
+	/** The related entity snapshot (if connected and loaded) */
+	readonly entity: EntitySnapshot<T> | null
+	/** Whether the relation has been modified */
+	readonly isDirty: boolean
+	/** Version for change detection */
+	readonly version: number
+}
+
+/**
+ * Item in a has-many relation list.
+ */
+export interface HasManyItemSnapshot<T extends object = object> {
+	/** Unique key for React reconciliation */
+	readonly key: string
+	/** The entity snapshot */
+	readonly entity: EntitySnapshot<T>
+	/** Whether this item was added locally (not from server) */
+	readonly isNew: boolean
+}
+
+/**
+ * Immutable snapshot of a has-many relation (entity list).
+ */
+export interface HasManySnapshot<T extends object = object> {
+	/** List items in current order */
+	readonly items: ReadonlyArray<HasManyItemSnapshot<T>>
+	/** Keys of items that came from the server */
+	readonly serverItemKeys: ReadonlySet<string>
+	/** Keys of items that were added locally */
+	readonly addedKeys: ReadonlySet<string>
+	/** Keys of items that were removed locally */
+	readonly removedKeys: ReadonlySet<string>
+	/** Whether the order has been changed */
+	readonly orderChanged: boolean
+	/** Whether the list has any modifications */
+	readonly isDirty: boolean
+	/** Version for change detection */
+	readonly version: number
+}
+
+/**
+ * Loading state for an entity.
+ */
+export interface LoadingState {
+	readonly status: 'loading'
+	readonly id: string
+}
+
+/**
+ * Error state for an entity.
+ */
+export interface ErrorState {
+	readonly status: 'error'
+	readonly id: string
+	readonly error: Error
+}
+
+/**
+ * Not found state for an entity.
+ */
+export interface NotFoundState {
+	readonly status: 'not_found'
+	readonly id: string
+}
+
+/**
+ * Ready state with entity data.
+ */
+export interface ReadyState<T extends object = object> {
+	readonly status: 'ready'
+	readonly id: string
+	readonly entityType: string
+	readonly snapshot: EntitySnapshot<T>
+}
+
+/**
+ * Union of all possible entity states.
+ */
+export type EntityState<T extends object = object> =
+	| LoadingState
+	| ErrorState
+	| NotFoundState
+	| ReadyState<T>
+
+/**
+ * Helper to check if state is ready
+ */
+export function isReadyState<T extends object>(state: EntityState<T>): state is ReadyState<T> {
+	return state.status === 'ready'
+}
+
+/**
+ * Helper to check if state is loading
+ */
+export function isLoadingState<T extends object>(state: EntityState<T>): state is LoadingState {
+	return state.status === 'loading'
+}
+
+/**
+ * Helper to check if state is error
+ */
+export function isErrorState<T extends object>(state: EntityState<T>): state is ErrorState {
+	return state.status === 'error'
+}
+
+/**
+ * Creates an immutable entity snapshot from data.
+ */
+export function createEntitySnapshot<T extends object>(
+	id: string,
+	entityType: string,
+	data: T,
+	serverData: T,
+	version: number,
+): EntitySnapshot<T> {
+	return Object.freeze({
+		id,
+		entityType,
+		data: Object.freeze({ ...data }) as Readonly<T>,
+		serverData: Object.freeze({ ...serverData }) as Readonly<T>,
+		version,
+	})
+}
+
+/**
+ * Creates a new entity snapshot with updated data.
+ * Returns a new frozen object with incremented version.
+ */
+export function updateEntitySnapshot<T extends object>(
+	snapshot: EntitySnapshot<T>,
+	updates: Partial<T>,
+): EntitySnapshot<T> {
+	return Object.freeze({
+		...snapshot,
+		data: Object.freeze({ ...snapshot.data, ...updates }) as Readonly<T>,
+		version: snapshot.version + 1,
+	})
+}
+
+/**
+ * Creates a field snapshot from entity snapshot.
+ */
+export function createFieldSnapshot<T>(
+	value: T | null,
+	serverValue: T | null,
+): FieldSnapshot<T> {
+	return Object.freeze({
+		value,
+		serverValue,
+		isDirty: value !== serverValue,
+	})
+}