@contember/bindx 0.1.43 → 0.1.45

package/src/store/RelationStore.ts

@@ -252,22 +252,6 @@ export class RelationStore {
 		}
 	}
 
-	/**
-	 * Cancels a planned removal for a has-many item.
-	 */
-	cancelHasManyRemoval(key: string, itemId: string): void {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return
-
-		const newPlannedRemovals = new Map(existing.plannedRemovals)
-		newPlannedRemovals.delete(itemId)
-		this.hasManyStates.set(key, {
-			...existing,
-			plannedRemovals: newPlannedRemovals,
-			version: existing.version + 1,
-		})
-	}
-
 	/**
 	 * Plans a connection for a has-many item.
 	 */
@@ -302,22 +286,6 @@ export class RelationStore {
 		}
 	}
 
-	/**
-	 * Cancels a planned connection for a has-many item.
-	 */
-	cancelHasManyConnection(key: string, itemId: string): void {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return
-
-		const newPlannedConnections = new Set(existing.plannedConnections)
-		newPlannedConnections.delete(itemId)
-		this.hasManyStates.set(key, {
-			...existing,
-			plannedConnections: newPlannedConnections,
-			version: existing.version + 1,
-		})
-	}
-
 	/**
 	 * Commits has-many state after successful persist.
 	 */
@@ -419,11 +387,11 @@ export class RelationStore {
 	 * Removes an entity from a has-many relation.
 	 * For newly created entities (via add()), cancels the connection.
 	 * For existing server entities, plans the specified removal type.
-	 * Returns the key if a removal was planned (caller should notify), or null if handled inline.
+	 * Returns true if the state changed (caller should notify), false if it was a no-op.
 	 */
-	removeFromHasMany(key: string, itemId: string, removalType: HasManyRemovalType): 'planned_removal' | 'cancelled_connection' | null {
+	removeFromHasMany(key: string, itemId: string, removalType: HasManyRemovalType): boolean {
 		const existing = this.hasManyStates.get(key)
-		if (!existing) return null
+		if (!existing) return false
 
 		const isCreatedEntity = existing.createdEntities.has(itemId)
 
@@ -458,10 +426,66 @@ export class RelationStore {
 			}
 
 			this.hasManyStates.set(key, newState)
-			return 'cancelled_connection'
+			return true
 		} else {
 			this.planHasManyRemoval(key, itemId, removalType)
-			return 'planned_removal'
+			return true
+		}
+	}
+
+	/**
+	 * Collects the ids of child entities currently reachable through an entity's
+	 * LIVE relations (key prefix "parentType:parentId:"). Used by reachability-based
+	 * create detection to walk the relation graph from roots.
+	 *
+	 * Live edges are:
+	 *   - has-one: currentId, when the relation is not disconnected/deleted
+	 *     (a disconnected relation has a null currentId; a 'deleted' relation is
+	 *     removing its target, so the target is not anchored by it).
+	 *   - has-many: effective members = (serverIds ∪ plannedConnections ∪
+	 *     createdEntities) minus plannedRemovals.
+	 */
+	getLiveChildIds(keyPrefix: string): string[] {
+		const ids = new Set<string>()
+
+		for (const [key, state] of this.relationStates) {
+			if (!key.startsWith(keyPrefix)) continue
+			if (state.currentId !== null && state.state !== 'deleted') {
+				ids.add(state.currentId)
+			}
+		}
+
+		for (const [key, state] of this.hasManyStates) {
+			if (!key.startsWith(keyPrefix)) continue
+			for (const id of state.serverIds) {
+				if (!state.plannedRemovals.has(id)) ids.add(id)
+			}
+			for (const id of state.plannedConnections) {
+				if (!state.plannedRemovals.has(id)) ids.add(id)
+			}
+			for (const id of state.createdEntities) {
+				if (!state.plannedRemovals.has(id)) ids.add(id)
+			}
+		}
+
+		return Array.from(ids)
+	}
+
+	/**
+	 * Removes all relation and has-many state owned by an entity (keys under the
+	 * given owner prefix). Called by removeEntity so a removed entity leaves no
+	 * stale relation state behind.
+	 */
+	removeOwnedRelations(keyPrefix: string): void {
+		for (const key of [...this.relationStates.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.relationStates.delete(key)
+			}
+		}
+		for (const key of [...this.hasManyStates.keys()]) {
+			if (key.startsWith(keyPrefix)) {
+				this.hasManyStates.delete(key)
+			}
 		}
 	}
 

package/src/store/RootRegistry.ts

@@ -0,0 +1,44 @@
+/**
+ * Tracks explicitly-created top-level entities ("roots").
+ *
+ * Reachability-based create detection treats a created entity as a `create`
+ * only when it is reachable from a root through live relations. Roots are:
+ *   - every entity that exists on the server (tracked via EntityMetaStore), and
+ *   - explicitly-created top-level entities that have no persisted parent.
+ *
+ * The first set is derivable from metadata. The second set is NOT derivable
+ * from the relation graph — a top-level `<Entity create>` or a `useEntityList`
+ * add has no parent relation anchoring it, so it must be registered here when
+ * created and unregistered when removed.
+ *
+ * Keys use the same composite format as the rest of the store: "entityType:id".
+ */
+export class RootRegistry {
+	private readonly roots = new Set<string>()
+
+	register(key: string): void {
+		this.roots.add(key)
+	}
+
+	unregister(key: string): void {
+		this.roots.delete(key)
+	}
+
+	keys(): IterableIterator<string> {
+		return this.roots.keys()
+	}
+
+	/**
+	 * Moves a root entry from oldKey to newKey (used after persist rekeys a temp
+	 * id to a server-assigned id).
+	 */
+	rekey(oldKey: string, newKey: string): void {
+		if (this.roots.delete(oldKey)) {
+			this.roots.add(newKey)
+		}
+	}
+
+	clear(): void {
+		this.roots.clear()
+	}
+}

package/src/store/SnapshotStore.ts

@@ -13,6 +13,8 @@ import { TouchedStore } from './TouchedStore.js'
 import { generateTempId } from './entityId.js'
 import { DirtyTracker } from './DirtyTracker.js'
 import { EntitySnapshotStore } from './EntitySnapshotStore.js'
+import { RootRegistry } from './RootRegistry.js'
+import { ReachabilityAnalyzer } from './ReachabilityAnalyzer.js'
 
 export type { HasManyRemovalType, StoredHasManyState, StoredRelationState } from './RelationStore.js'
 export type { EntityMeta } from './EntityMetaStore.js'
@@ -44,6 +46,8 @@ export class SnapshotStore implements SnapshotVersionBumper {
 	private readonly relations = new RelationStore()
 	private readonly meta = new EntityMetaStore()
 	private readonly touched = new TouchedStore()
+	private readonly roots = new RootRegistry()
+	private readonly reachability: ReachabilityAnalyzer
 	private readonly dirtyTracker: DirtyTracker
 
 	/**
@@ -55,7 +59,8 @@ export class SnapshotStore implements SnapshotVersionBumper {
 	private readonly lastPropagatedData = new Map<string, unknown>()
 
 	constructor() {
-		this.dirtyTracker = new DirtyTracker(this.entitySnapshots, this.meta, this.relations)
+		this.reachability = new ReachabilityAnalyzer(this.entitySnapshots, this.meta, this.relations, this.roots)
+		this.dirtyTracker = new DirtyTracker(this.entitySnapshots, this.meta, this.relations, this.reachability)
 	}
 
 	// ==================== Key Generation ====================
@@ -238,14 +243,47 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		this.notifyEntitySubscribers(key)
 	}
 
+	/**
+	 * Removes a single entity and all of its own per-entity state (snapshot,
+	 * metadata, root registration, errors, touched state, propagation tracking,
+	 * and owned relation state).
+	 *
+	 * This does NOT cascade into descendants, and it does NOT strip inbound edges
+	 * (other entities' has-many membership / has-one currentId that point AT the
+	 * removed id). Callers must therefore only remove an entity that is unreachable
+	 * — i.e. no live parent relation references it — so the graph cannot dangle. The
+	 * lazy {@link sweepUnreachableCreated} guarantees this by construction; the React
+	 * unmount cleanup routes through it (via {@link unregisterRootEntity} + a sweep)
+	 * rather than calling removeEntity on a possibly-referenced id.
+	 */
 	removeEntity(entityType: string, id: string): void {
 		const key = this.getEntityKey(entityType, id)
+		const keyPrefix = `${key}:`
+
 		this.entitySnapshots.remove(key)
-		this.meta.clearLoadState(key)
+		this.meta.remove(key)
+		this.roots.unregister(key)
+		this.errors.clearAllErrors(key, keyPrefix)
+		this.touched.clearForEntity(keyPrefix)
 		this.clearPropagatedDataForEntity(entityType, id)
+		this.relations.removeOwnedRelations(keyPrefix)
+
 		this.notifyEntitySubscribers(key)
 	}
 
+	/**
+	 * Whether an entity (looked up by id alone) exists in the store and has never
+	 * been persisted to the server. Used to decide relation-state semantics when a
+	 * has-one target is deleted — deleting a never-persisted target reverts the
+	 * relation to 'disconnected' rather than 'deleted', since there is no server
+	 * row to delete.
+	 */
+	isNeverPersisted(entityId: string): boolean {
+		const key = this.entitySnapshots.keyForId(entityId)
+		if (!key) return false
+		return !this.meta.existsOnServer(key)
+	}
+
 	// ==================== Load State (delegated to EntityMetaStore) ====================
 
 	getLoadState(entityType: string, id: string): { status: LoadStatus; error?: FieldError } | undefined {
@@ -306,9 +344,28 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		this.setEntityData(entityType, id, data, false)
 		this.setExistsOnServer(entityType, id, false)
 
+		// A freshly created entity is pending-persist by default — a root for
+		// reachability-based create detection. It stops being a root the moment a
+		// relation anchors it as a child (see registerParentChild). A top-level
+		// create (<Entity create>, useEntityList add) is never anchored, so it stays
+		// a root and is reported as a `create`.
+		this.roots.register(this.getEntityKey(entityType, id))
+
 		return id
 	}
 
+	/**
+	 * Unregisters a top-level root WITHOUT removing its snapshot. Called by the React
+	 * unmount cleanup (a `<Entity create>` form / `useEntityList` draft) before a
+	 * {@link sweepUnreachableCreated} pass: dropping the root lets the sweep reclaim a
+	 * truly-orphaned create, while a create still anchored by another live relation
+	 * stays reachable and survives. (Un-rooting also happens implicitly via
+	 * {@link registerParentChild} and the rekey in {@link mapTempIdToPersistedId}.)
+	 */
+	unregisterRootEntity(entityType: string, id: string): void {
+		this.roots.unregister(this.getEntityKey(entityType, id))
+	}
+
 	mapTempIdToPersistedId(entityType: string, tempId: string, persistedId: string): void {
 		// Use raw keys (bypass resolveId) since we're the ones creating the mapping
 		const oldKey = `${entityType}:${tempId}`
@@ -319,6 +376,10 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		// Register redirect so future lookups by temp ID resolve to persisted key
 		this.rekeyedEntities.set(oldKey, newKey)
 
+		// Keep root registration consistent across the rekey (the persisted entity
+		// is now a server root via existsOnServer, but keep the registry aligned).
+		this.roots.rekey(oldKey, newKey)
+
 		// Rekey entity snapshot (moves data, updates id field)
 		this.entitySnapshots.rekey(oldKey, newKey, persistedId)
 
@@ -402,18 +463,6 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		this.notifyRelationSubscribers(key)
 	}
 
-	cancelHasManyRemoval(
-		parentType: string,
-		parentId: string,
-		fieldName: string,
-		itemId: string,
-		alias?: string,
-	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		this.relations.cancelHasManyRemoval(key, itemId)
-		this.notifyRelationSubscribers(key)
-	}
-
 	getHasManyPlannedRemovals(
 		parentType: string,
 		parentId: string,
@@ -436,18 +485,6 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		this.notifyRelationSubscribers(key)
 	}
 
-	cancelHasManyConnection(
-		parentType: string,
-		parentId: string,
-		fieldName: string,
-		itemId: string,
-		alias?: string,
-	): void {
-		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		this.relations.cancelHasManyConnection(key, itemId)
-		this.notifyRelationSubscribers(key)
-	}
-
 	getHasManyPlannedConnections(
 		parentType: string,
 		parentId: string,
@@ -513,10 +550,10 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		alias?: string,
 	): void {
 		const key = this.getRelationKey(parentType, parentId, alias ?? fieldName)
-		const result = this.relations.removeFromHasMany(key, itemId, removalType)
-		if (result === 'planned_removal') {
-			this.notifyRelationSubscribers(key)
-		} else if (result === 'cancelled_connection') {
+		// Cancelling the add of a never-persisted child just removes it from the
+		// list; its now-unreachable snapshot is no longer reported as a `create` and
+		// is collected by the lazy memory sweep.
+		if (this.relations.removeFromHasMany(key, itemId, removalType)) {
 			this.notifyRelationSubscribers(key)
 		}
 	}
@@ -807,6 +844,9 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		const parentKey = this.getEntityKey(parentType, parentId)
 		const childKey = this.getEntityKey(childType, childId)
 		this.subscriptions.registerParentChild(parentKey, childKey)
+		// A child anchored by a parent relation is no longer a top-level root; its
+		// reachability now flows through the parent. (No-op for server children.)
+		this.roots.unregister(childKey)
 	}
 
 	unregisterParentChild(parentType: string, parentId: string, childType: string, childId: string): void {
@@ -870,6 +910,26 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		return this.dirtyTracker.getAllDirtyEntities()
 	}
 
+	/**
+	 * Removes the snapshots of created (never-persisted) entities that are no longer
+	 * reachable from any root — the lazy memory sweep that replaces eager purge.
+	 *
+	 * Correctness never depends on this (unreachable creates are already excluded
+	 * from getAllDirtyEntities); it only reclaims memory. Run it off the hot path,
+	 * e.g. once a persist settles. Shared (diamond) children are kept because
+	 * reachability reports them as live as long as any parent references them.
+	 */
+	sweepUnreachableCreated(): void {
+		const reachable = this.reachability.computeReachableCreated()
+		for (const key of [...this.entitySnapshots.keys()]) {
+			if (this.meta.existsOnServer(key)) continue
+			if (reachable.has(key)) continue
+			const separator = key.indexOf(':')
+			if (separator === -1) continue
+			this.removeEntity(key.slice(0, separator), key.slice(separator + 1))
+		}
+	}
+
 	getDirtyFields(entityType: string, entityId: string): string[] {
 		return this.dirtyTracker.getDirtyFields(entityType, entityId)
 	}
@@ -892,6 +952,7 @@ export class SnapshotStore implements SnapshotVersionBumper {
 		this.relations.clear()
 		this.errors.clear()
 		this.touched.clear()
+		this.roots.clear()
 		this.lastPropagatedData.clear()
 
 		this.subscriptions.notify()

package/src/store/SubscriptionManager.ts

@@ -157,6 +157,11 @@ export class SubscriptionManager {
 	): void {
 		// Prevent infinite recursion
 		if (notifiedKeys.has(key)) return
+		// Capture "am I the root invocation" BEFORE adding/recursing — the parent
+		// propagation below grows the shared `notifiedKeys` set, so checking its
+		// size after recursion would misclassify any child-with-parent as non-root
+		// and skip the global notification (see issue #51).
+		const isRoot = notifiedKeys.size === 0
 		notifiedKeys.add(key)
 
 		this.globalVersion++
@@ -179,8 +184,9 @@ export class SubscriptionManager {
 			}
 		}
 
-		// Notify global subscribers (only once, not for each parent)
-		if (notifiedKeys.size === 1) {
+		// Notify global subscribers (only once, from the root invocation — not
+		// again for each parent reached via propagation)
+		if (isRoot) {
 			for (const sub of this.globalSubscribers) {
 				sub()
 			}

package/dist/core/Disposable.d.ts

@@ -1,57 +0,0 @@
-/**
- * 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 declare class DisposableGroup implements Disposable {
-    private disposables;
-    private disposed;
-    /**
-     * Adds a disposable to the group.
-     * If the group is already disposed, the disposable is disposed immediately.
-     */
-    add(disposable: Disposable): void;
-    /**
-     * Adds a callback as a disposable.
-     */
-    addCallback(callback: () => void): void;
-    /**
-     * Adds an unsubscribe function as a disposable.
-     */
-    addUnsubscribe(unsubscribe: () => void): void;
-    /**
-     * Disposes all items in the group.
-     * Each item is disposed even if previous ones throw.
-     */
-    dispose(): void;
-    /**
-     * Checks if the group has been disposed.
-     */
-    isDisposed(): boolean;
-    /**
-     * Gets the number of disposables in the group.
-     */
-    get size(): number;
-}
-/**
- * Creates a disposable from a callback function.
- */
-export declare function createDisposable(callback: () => void): Disposable;
-/**
- * Combines multiple disposables into one.
- */
-export declare function combineDisposables(...disposables: Disposable[]): Disposable;
-/**
- * Type guard to check if something is disposable.
- */
-export declare function isDisposable(value: unknown): value is Disposable;
-//# sourceMappingURL=Disposable.d.ts.map

package/dist/core/Disposable.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../src/core/Disposable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,OAAO,IAAI,IAAI,CAAA;CACf;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACjD,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAajC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAIvC;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,IAAI,GAAG,IAAI;IAI7C;;;OAGG;IACH,OAAO,IAAI,IAAI;IAqBf;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CASjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,WAAW,EAAE,UAAU,EAAE,GAAG,UAAU,CAM3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE"}

package/src/core/Disposable.ts

@@ -1,126 +0,0 @@
-/**
- * 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'
-	)
-}