@contember/bindx 0.1.0

package/src/undo/UndoManager.ts

@@ -0,0 +1,418 @@
+import type { ActionMiddleware } from '../core/ActionDispatcher.js'
+import type { Action } from '../core/actions.js'
+import {
+	isTrackableAction,
+	getAffectedKeys,
+	mergeAffectedKeys,
+	createEmptyAffectedKeys,
+	type StoreAffectedKeys,
+} from '../core/actionClassification.js'
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type {
+	PartialStoreSnapshot,
+	PendingUndoEntry,
+	UndoEntry,
+	UndoManagerConfig,
+	UndoState,
+} from './types.js'
+
+type Subscriber = () => void
+
+/**
+ * Generates a unique ID for undo entries.
+ */
+function generateId(): string {
+	return `undo-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * UndoManager provides undo/redo functionality for the Bindx store.
+ *
+ * Features:
+ * - Automatic debounced grouping of rapid changes
+ * - Manual grouping via beginGroup/endGroup
+ * - Configurable history size
+ * - Block/unblock during persist operations
+ * - React integration via subscribe/getState
+ */
+export class UndoManager {
+	private undoStack: UndoEntry[] = []
+	private redoStack: UndoEntry[] = []
+	private pendingEntry: PendingUndoEntry | null = null
+	private debounceTimer: ReturnType<typeof setTimeout> | null = null
+	private isBlocked = false
+	private manualGroupId: string | null = null
+	private manualGroupLabel: string | undefined = undefined
+	private subscribers = new Set<Subscriber>()
+	private cachedState: UndoState | null = null
+
+	private readonly maxHistorySize: number
+	private readonly debounceMs: number
+
+	constructor(
+		private readonly store: SnapshotStore,
+		config: UndoManagerConfig = {},
+	) {
+		this.maxHistorySize = config.maxHistorySize ?? 100
+		this.debounceMs = config.debounceMs ?? 300
+	}
+
+	/**
+	 * Creates middleware for ActionDispatcher.
+	 * Must be added to dispatcher to enable undo tracking.
+	 */
+	createMiddleware(): ActionMiddleware {
+		return (action: Action) => {
+			this.handleAction(action)
+			// Always allow action to proceed
+			return true
+		}
+	}
+
+	/**
+	 * Handles an action, capturing state for undo if trackable.
+	 */
+	private handleAction(action: Action): void {
+		// Skip if blocked or not trackable
+		if (this.isBlocked || !isTrackableAction(action)) {
+			return
+		}
+
+		const keys = getAffectedKeys(action)
+
+		// Clear redo stack on new action
+		if (this.redoStack.length > 0) {
+			this.redoStack = []
+			this.notifySubscribers()
+		}
+
+		if (this.manualGroupId !== null) {
+			// Manual grouping mode
+			this.handleManualGroupAction(keys)
+		} else {
+			// Auto-debounce mode
+			this.handleDebouncedAction(keys)
+		}
+	}
+
+	/**
+	 * Handles action in manual group mode.
+	 */
+	private handleManualGroupAction(keys: StoreAffectedKeys): void {
+		if (!this.pendingEntry) {
+			// First action in group - capture snapshot
+			const snapshot = this.store.exportPartialSnapshot(keys)
+			this.pendingEntry = {
+				beforeSnapshot: snapshot,
+				affectedKeys: { ...keys, entityKeys: [...keys.entityKeys], relationKeys: [...keys.relationKeys], hasManyKeys: [...keys.hasManyKeys] },
+				timestamp: Date.now(),
+				label: this.manualGroupLabel,
+			}
+		} else {
+			// Merge keys and expand snapshot if needed
+			const newKeys = this.getNewKeys(this.pendingEntry.affectedKeys, keys)
+			if (!this.isEmptyKeys(newKeys)) {
+				// Capture additional state for new keys
+				const additionalSnapshot = this.store.exportPartialSnapshot(newKeys)
+				this.mergeSnapshots(this.pendingEntry.beforeSnapshot, additionalSnapshot)
+				mergeAffectedKeys(this.pendingEntry.affectedKeys, keys)
+			}
+		}
+	}
+
+	/**
+	 * Handles action in debounced auto-group mode.
+	 */
+	private handleDebouncedAction(keys: StoreAffectedKeys): void {
+		// If debounceMs is 0, immediately create individual entries (no grouping)
+		if (this.debounceMs === 0) {
+			const snapshot = this.store.exportPartialSnapshot(keys)
+			this.undoStack.push({
+				id: generateId(),
+				beforeSnapshot: snapshot,
+				affectedKeys: { ...keys, entityKeys: [...keys.entityKeys], relationKeys: [...keys.relationKeys], hasManyKeys: [...keys.hasManyKeys] },
+				timestamp: Date.now(),
+			})
+			this.trimHistory()
+			this.notifySubscribers()
+			return
+		}
+
+		if (this.pendingEntry) {
+			// Extend existing pending entry
+			const newKeys = this.getNewKeys(this.pendingEntry.affectedKeys, keys)
+			if (!this.isEmptyKeys(newKeys)) {
+				const additionalSnapshot = this.store.exportPartialSnapshot(newKeys)
+				this.mergeSnapshots(this.pendingEntry.beforeSnapshot, additionalSnapshot)
+				mergeAffectedKeys(this.pendingEntry.affectedKeys, keys)
+			}
+			this.resetDebounceTimer()
+		} else {
+			// First action - capture snapshot and start timer
+			const snapshot = this.store.exportPartialSnapshot(keys)
+			this.pendingEntry = {
+				beforeSnapshot: snapshot,
+				affectedKeys: { ...keys, entityKeys: [...keys.entityKeys], relationKeys: [...keys.relationKeys], hasManyKeys: [...keys.hasManyKeys] },
+				timestamp: Date.now(),
+			}
+			this.startDebounceTimer()
+			this.notifySubscribers()
+		}
+	}
+
+	/**
+	 * Gets keys that are in source but not in target.
+	 */
+	private getNewKeys(target: StoreAffectedKeys, source: StoreAffectedKeys): StoreAffectedKeys {
+		return {
+			entityKeys: source.entityKeys.filter(k => !target.entityKeys.includes(k)),
+			relationKeys: source.relationKeys.filter(k => !target.relationKeys.includes(k)),
+			hasManyKeys: source.hasManyKeys.filter(k => !target.hasManyKeys.includes(k)),
+		}
+	}
+
+	/**
+	 * Checks if keys object is empty.
+	 */
+	private isEmptyKeys(keys: StoreAffectedKeys): boolean {
+		return keys.entityKeys.length === 0 && keys.relationKeys.length === 0 && keys.hasManyKeys.length === 0
+	}
+
+	/**
+	 * Merges additional snapshot into target.
+	 */
+	private mergeSnapshots(target: PartialStoreSnapshot, source: PartialStoreSnapshot): void {
+		for (const [key, value] of source.entitySnapshots) {
+			if (!target.entitySnapshots.has(key)) {
+				target.entitySnapshots.set(key, value)
+			}
+		}
+		for (const [key, value] of source.relationStates) {
+			if (!target.relationStates.has(key)) {
+				target.relationStates.set(key, value)
+			}
+		}
+		for (const [key, value] of source.hasManyStates) {
+			if (!target.hasManyStates.has(key)) {
+				target.hasManyStates.set(key, value)
+			}
+		}
+		for (const [key, value] of source.entityMetas) {
+			if (!target.entityMetas.has(key)) {
+				target.entityMetas.set(key, value)
+			}
+		}
+	}
+
+	/**
+	 * Starts the debounce timer.
+	 */
+	private startDebounceTimer(): void {
+		this.debounceTimer = setTimeout(() => {
+			this.flushPendingEntry()
+		}, this.debounceMs)
+	}
+
+	/**
+	 * Resets the debounce timer.
+	 */
+	private resetDebounceTimer(): void {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer)
+		}
+		this.startDebounceTimer()
+	}
+
+	/**
+	 * Flushes pending entry to undo stack.
+	 */
+	private flushPendingEntry(): void {
+		if (!this.pendingEntry) return
+
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer)
+			this.debounceTimer = null
+		}
+
+		this.undoStack.push({
+			id: generateId(),
+			label: this.pendingEntry.label,
+			beforeSnapshot: this.pendingEntry.beforeSnapshot,
+			affectedKeys: this.pendingEntry.affectedKeys,
+			timestamp: this.pendingEntry.timestamp,
+		})
+
+		this.pendingEntry = null
+		this.trimHistory()
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Trims history to max size.
+	 */
+	private trimHistory(): void {
+		while (this.undoStack.length > this.maxHistorySize) {
+			this.undoStack.shift()
+		}
+	}
+
+	/**
+	 * Starts a manual group. All actions until endGroup are grouped as one undo entry.
+	 * Returns group ID that must be passed to endGroup.
+	 */
+	beginGroup(label?: string): string {
+		// Flush any pending debounced entry first
+		this.flushPendingEntry()
+
+		const groupId = generateId()
+		this.manualGroupId = groupId
+		this.manualGroupLabel = label
+		return groupId
+	}
+
+	/**
+	 * Ends a manual group and pushes to undo stack.
+	 */
+	endGroup(groupId: string): void {
+		if (this.manualGroupId !== groupId) {
+			console.warn(`UndoManager: endGroup called with wrong groupId. Expected ${this.manualGroupId}, got ${groupId}`)
+			return
+		}
+
+		this.manualGroupId = null
+		this.manualGroupLabel = undefined
+		this.flushPendingEntry()
+	}
+
+	/**
+	 * Undoes the last entry.
+	 */
+	undo(): void {
+		// Flush any pending entry first
+		this.flushPendingEntry()
+
+		if (this.isBlocked || this.undoStack.length === 0) {
+			return
+		}
+
+		const entry = this.undoStack.pop()!
+
+		// Capture current state for redo
+		const currentSnapshot = this.store.exportPartialSnapshot(entry.affectedKeys)
+
+		// Push to redo stack with current state
+		this.redoStack.push({
+			id: entry.id,
+			label: entry.label,
+			beforeSnapshot: currentSnapshot,
+			affectedKeys: entry.affectedKeys,
+			timestamp: Date.now(),
+		})
+
+		// Restore the before snapshot
+		this.store.importPartialSnapshot(entry.beforeSnapshot)
+
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Redoes the last undone entry.
+	 */
+	redo(): void {
+		if (this.isBlocked || this.redoStack.length === 0) {
+			return
+		}
+
+		const entry = this.redoStack.pop()!
+
+		// Capture current state for undo
+		const currentSnapshot = this.store.exportPartialSnapshot(entry.affectedKeys)
+
+		// Push back to undo stack
+		this.undoStack.push({
+			id: entry.id,
+			label: entry.label,
+			beforeSnapshot: currentSnapshot,
+			affectedKeys: entry.affectedKeys,
+			timestamp: Date.now(),
+		})
+
+		// Restore the redo snapshot
+		this.store.importPartialSnapshot(entry.beforeSnapshot)
+
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Blocks undo/redo operations.
+	 * Use during persist to prevent inconsistent state.
+	 */
+	block(): void {
+		// Flush any pending entry before blocking
+		this.flushPendingEntry()
+		this.isBlocked = true
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Unblocks undo/redo operations.
+	 */
+	unblock(): void {
+		this.isBlocked = false
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Clears all undo/redo history.
+	 */
+	clear(): void {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer)
+			this.debounceTimer = null
+		}
+		this.pendingEntry = null
+		this.undoStack = []
+		this.redoStack = []
+		this.manualGroupId = null
+		this.manualGroupLabel = undefined
+		this.notifySubscribers()
+	}
+
+	/**
+	 * Subscribes to state changes.
+	 * Returns unsubscribe function.
+	 */
+	subscribe(callback: Subscriber): () => void {
+		this.subscribers.add(callback)
+		return () => {
+			this.subscribers.delete(callback)
+		}
+	}
+
+	/**
+	 * Gets current state for React integration.
+	 * Returns a cached object to satisfy useSyncExternalStore's referential equality requirement.
+	 */
+	getState(): UndoState {
+		if (!this.cachedState) {
+			this.cachedState = {
+				canUndo: this.undoStack.length > 0 || this.pendingEntry !== null,
+				canRedo: this.redoStack.length > 0,
+				isBlocked: this.isBlocked,
+				undoCount: this.undoStack.length + (this.pendingEntry ? 1 : 0),
+				redoCount: this.redoStack.length,
+			}
+		}
+		return this.cachedState
+	}
+
+	/**
+	 * Notifies all subscribers of state change.
+	 */
+	private notifySubscribers(): void {
+		this.cachedState = null
+		for (const sub of this.subscribers) {
+			sub()
+		}
+	}
+}

package/src/undo/index.ts

@@ -0,0 +1,9 @@
+export { UndoManager } from './UndoManager.js'
+export type {
+	PartialStoreSnapshot,
+	PendingUndoEntry,
+	UndoEntry,
+	UndoManagerConfig,
+	UndoState,
+	StoreAffectedKeys,
+} from './types.js'

package/src/undo/types.ts

@@ -0,0 +1,84 @@
+import type { StoreAffectedKeys } from '../core/actionClassification.js'
+import type { EntitySnapshot } from '../store/snapshots.js'
+import type {
+	StoredRelationState,
+	StoredHasManyState,
+	EntityMeta,
+} from '../store/SnapshotStore.js'
+
+/**
+ * Partial snapshot of store state.
+ * Contains only the data affected by an action or group of actions.
+ */
+export interface PartialStoreSnapshot {
+	/** Entity snapshots (frozen, immutable) */
+	entitySnapshots: Map<string, EntitySnapshot>
+	/** Has-one relation states */
+	relationStates: Map<string, StoredRelationState>
+	/** Has-many list states */
+	hasManyStates: Map<string, StoredHasManyState>
+	/** Entity metadata (existsOnServer, deletion flags) */
+	entityMetas: Map<string, EntityMeta>
+}
+
+/**
+ * A single undo/redo entry.
+ * Contains the snapshot of state BEFORE the action(s) were applied.
+ */
+export interface UndoEntry {
+	/** Unique identifier for this entry */
+	id: string
+	/** Optional human-readable label */
+	label?: string
+	/** Snapshot of state BEFORE the action(s) */
+	beforeSnapshot: PartialStoreSnapshot
+	/** Keys that were affected (for redo snapshot capture) */
+	affectedKeys: StoreAffectedKeys
+	/** When this entry was created */
+	timestamp: number
+}
+
+/**
+ * Pending entry during debounce window.
+ * Accumulates affected keys while waiting for debounce to complete.
+ */
+export interface PendingUndoEntry {
+	/** Snapshot captured before the first action in the group */
+	beforeSnapshot: PartialStoreSnapshot
+	/** Accumulated affected keys */
+	affectedKeys: StoreAffectedKeys
+	/** When the first action occurred */
+	timestamp: number
+	/** Optional label for manual grouping */
+	label?: string
+}
+
+/**
+ * Configuration options for UndoManager.
+ */
+export interface UndoManagerConfig {
+	/** Maximum number of undo entries to keep (default: 100) */
+	maxHistorySize?: number
+	/** Debounce time in milliseconds for auto-grouping (default: 300) */
+	debounceMs?: number
+}
+
+/**
+ * Current state of the undo manager.
+ * Used for React integration via useSyncExternalStore.
+ */
+export interface UndoState {
+	/** Whether undo is available */
+	canUndo: boolean
+	/** Whether redo is available */
+	canRedo: boolean
+	/** Whether undo/redo is currently blocked (e.g., during persist) */
+	isBlocked: boolean
+	/** Number of entries in undo stack */
+	undoCount: number
+	/** Number of entries in redo stack */
+	redoCount: number
+}
+
+// Re-export StoreAffectedKeys for convenience
+export type { StoreAffectedKeys } from '../core/actionClassification.js'

package/src/utils/aliasGenerator.ts

@@ -0,0 +1,56 @@
+import type { HasManyParams } from '../selection/SelectionScope.js'
+
+/**
+ * Generates an alias for a has-many relation based on field name and parameters.
+ *
+ * If no parameters are provided or all are undefined, returns the fieldName as-is.
+ * Otherwise, generates a deterministic alias by hashing the parameters.
+ *
+ * @param fieldName - The original field name
+ * @param params - Optional has-many parameters (filter, orderBy, limit, offset)
+ * @returns The alias to use for this has-many relation
+ *
+ * @example
+ * ```ts
+ * // No params - returns fieldName
+ * generateHasManyAlias('tags') // => 'tags'
+ *
+ * // With filter - generates unique alias
+ * generateHasManyAlias('tags', { filter: { active: true } }) // => 'tags_a7x9k2'
+ *
+ * // Different params - different aliases
+ * generateHasManyAlias('tags', { filter: { active: false } }) // => 'tags_b3m1p8'
+ * ```
+ */
+export function generateHasManyAlias(fieldName: string, params?: HasManyParams): string {
+	if (!params) {
+		return fieldName
+	}
+
+	const { filter, orderBy, limit, offset } = params
+
+	// If all params are undefined, return fieldName
+	if (filter === undefined && orderBy === undefined && limit === undefined && offset === undefined) {
+		return fieldName
+	}
+
+	// Serialize parameters deterministically
+	const serialized = JSON.stringify({
+		f: filter,
+		o: orderBy,
+		l: limit,
+		s: offset,
+	})
+
+	// Simple djb2 hash algorithm
+	let hash = 5381
+	for (let i = 0; i < serialized.length; i++) {
+		hash = ((hash << 5) + hash) + serialized.charCodeAt(i)
+		hash = hash & hash // Convert to 32-bit integer
+	}
+
+	// Convert to base36 and take first 6 characters for compact representation
+	const hashStr = Math.abs(hash).toString(36).slice(0, 6)
+
+	return `${fieldName}_${hashStr}`
+}

package/src/utils/deepEqual.ts

@@ -0,0 +1,33 @@
+/**
+ * Deep equality check for values.
+ * Handles objects, arrays, and primitives.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true
+	if (a === null || b === null) return false
+	if (typeof a !== 'object' || typeof b !== 'object') return false
+
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false
+		for (let i = 0; i < a.length; i++) {
+			if (!deepEqual(a[i], b[i])) return false
+		}
+		return true
+	}
+
+	if (Array.isArray(a) || Array.isArray(b)) return false
+
+	const keysA = Object.keys(a)
+	const keysB = Object.keys(b)
+
+	if (keysA.length !== keysB.length) return false
+
+	for (const key of keysA) {
+		if (!keysB.includes(key)) return false
+		if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {
+			return false
+		}
+	}
+
+	return true
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { deepEqual } from './deepEqual.js'
+export { generateHasManyAlias } from './aliasGenerator.js'