Merge pull request #28 from zeixcom/next

Bugfix for propagation to effects (FLAG_CHECK first)

Author: estherbrunner

ARCHITECTURE.md

@@ -106,14 +106,14 @@ The first four flags (`CLEAN`/`CHECK`/`DIRTY`/`RUNNING`) are used by the core gr
 
 `FLAG_RELINK` is used exclusively by composite signal types (Store, List, Collection, deriveCollection) that manage their own child signals. When a structural mutation adds or removes child signals, the node is flagged `FLAG_DIRTY | FLAG_RELINK`. On the next `get()`, the composite signal's fast path reads the flag: if `FLAG_RELINK` is set, it forces a tracked `refresh()` after rebuilding the value so that `recomputeMemo()` can call `link()` for new child signals and `trimSources()` for removed ones. This avoids the previous approach of nulling `node.sources`/`node.sourcesTail`, which orphaned edges in upstream sink lists. `FLAG_RELINK` is always cleared by `recomputeMemo()`, which assigns `node.flags = FLAG_RUNNING` (clearing all bits) at the start of recomputation.
 
-### The `propagate(node)` Function
+### The `propagate(node, newFlag?)` Function
 
-When a source value changes, `propagate()` walks its sink list:
+When a source value changes, `propagate()` walks its sink list. The `newFlag` parameter defaults to `FLAG_DIRTY` but callers may pass `FLAG_CHECK` for speculative invalidation (e.g., watched callbacks where the source value may not have actually changed).
 
-- **Memo/Task sinks** (have `sinks` field): Flagged `DIRTY`. Their own sinks are recursively flagged `CHECK`. If the node has an in-flight `AbortController`, it is aborted immediately.
-- **Effect sinks** (no `sinks` field): Flagged `DIRTY` and pushed onto the `queuedEffects` array for later execution.
+- **Memo/Task sinks** (have `sinks` field): Flagged with `newFlag` (typically `DIRTY`). Their own sinks are recursively flagged `CHECK`. If the node has an in-flight `AbortController`, it is aborted immediately. Short-circuits if the node already carries an equal or higher flag.
+- **Effect sinks** (no `sinks` field): Flagged with `newFlag` and pushed onto the `queuedEffects` array. An effect is only enqueued once — subsequent propagations escalate the flag (e.g., `CHECK` → `DIRTY`) without re-enqueuing. The flag is assigned (not OR'd) to clear `FLAG_RUNNING`, preserving the existing pattern where a state update inside a running effect triggers a re-run.
 
-The two-level flagging (`DIRTY` for direct dependents, `CHECK` for transitive) avoids unnecessary recomputation. A `CHECK` node only recomputes if, upon inspection during `refresh()`, one of its sources turns out to have actually changed.
+The two-level flagging (`DIRTY` for direct dependents, `CHECK` for transitive) avoids unnecessary recomputation. A `CHECK` node only recomputes if, upon inspection during `refresh()`, one of its sources turns out to have actually changed. This applies equally to memo, task, and effect nodes.
 
 ### The `refresh(node)` Function
 
@@ -141,7 +141,7 @@ If `FLAG_RUNNING` is encountered, a `CircularDependencyError` is thrown.
 
 ### The `flush()` Function
 
-`flush()` iterates over `queuedEffects`, calling `refresh()` on each effect that is still `DIRTY`. A `flushing` guard prevents re-entrant flushes. Effects that were enqueued during the flush (due to async resolution or nested state changes) are processed in the same pass, since `flush()` reads the array length dynamically.
+`flush()` iterates over `queuedEffects`, calling `refresh()` on each effect that is still `DIRTY` or `CHECK`. A `flushing` guard prevents re-entrant flushes. Effects that were enqueued during the flush (due to async resolution or nested state changes) are processed in the same pass, since `flush()` reads the array length dynamically. Effects with only `FLAG_CHECK` enter `refresh()`, which walks their sources — if no source value actually changed, the effect is cleaned without running.
 
 ### Effect Lifecycle
 
@@ -209,7 +209,7 @@ The `error` field preserves thrown errors: if `fn` throws, the error is stored a
 
 **Reducer pattern**: The `prev` parameter enables state accumulation across recomputations without writable state.
 
-**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` marks the node `FLAG_DIRTY`, propagates to sinks, and flushes — triggering re-evaluation of the memo's `fn` without changing any tracked dependency. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where the memo re-derives its value in response to external events.
+**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` calls `propagate(node)` on the memo itself, which marks it `FLAG_DIRTY` and propagates `FLAG_CHECK` to downstream sinks, then flushes. During flush, downstream effects verify the memo via `refresh()` — if the memo's `equals` function determines the recomputed value is unchanged, the effect is cleaned without running. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where a memo re-derives its value in response to external events, with the `equals` check respected at every level of the graph.
 
 ### Task (`src/nodes/task.ts`)
 
@@ -221,7 +221,7 @@ During dependency tracking, only the synchronous preamble of `fn` is tracked (be
 
 `isPending()` returns `true` while a computation is in flight. `abort()` cancels the current computation manually. Errors are preserved like Memo, but old values are retained on errors (the last successful result remains accessible).
 
-**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` marks the node dirty and triggers re-execution, which aborts any in-flight computation via the existing `AbortController` mechanism before starting a new one.
+**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` calls `propagate(node)` on the task itself, which marks it dirty, aborts any in-flight computation eagerly via the `AbortController`, and propagates `FLAG_CHECK` to downstream sinks. Effects only re-run if the task's resolved value actually changes.
 
 ### Effect (`src/nodes/effect.ts`)
 

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.18.4
+
+### Fixed
+
+- **Watched `invalidate()` now respects `equals` at every graph level**: Previously, calling `invalidate()` from a Memo or Task `watched` callback propagated `FLAG_DIRTY` directly to effect sinks, causing unconditional re-runs even when the recomputed value was unchanged. Now `invalidate()` delegates to `propagate(node)`, which marks the node itself `FLAG_DIRTY` and propagates `FLAG_CHECK` to downstream sinks. During flush, effects verify their sources via `refresh()` — if the memo's `equals` function determines the value is unchanged, the effect is cleaned without running. This eliminates unnecessary effect executions for watched memos with custom equality or stable return values.
+
+### Changed
+
+- **`propagate()` supports `FLAG_CHECK` for effect nodes**: The effect branch of `propagate()` now respects the `newFlag` parameter instead of unconditionally setting `FLAG_DIRTY`. Effects are enqueued only on first notification; subsequent propagations escalate the flag (e.g., `CHECK` → `DIRTY`) without re-enqueuing.
+- **`flush()` processes `FLAG_CHECK` effects**: The flush loop now calls `refresh()` on effects with either `FLAG_DIRTY` or `FLAG_CHECK`, enabling the check-sources-first path for effects.
+- **Task `invalidate()` aborts eagerly**: Task watched callbacks now abort in-flight computations immediately during `propagate()` rather than deferring to `recomputeTask()`, consistent with the normal dependency-change path.
+
 ## 0.18.3
 
 ### Added

CLAUDE.md

@@ -126,7 +126,7 @@ The generic constraint `T extends {}` is crucial - it excludes `null` and `undef
 
 Computed signals implement smart memoization:
 - **Dependency Tracking**: Automatically tracks which signals are accessed during computation via `link()`
-- **Stale Detection**: Flag-based dirty checking (CLEAN, CHECK, DIRTY) — only recalculates when dependencies actually change
+- **Stale Detection**: Flag-based dirty checking (CLEAN, CHECK, DIRTY) — only recalculates when dependencies actually change. The `equals` check is respected at every graph level: when a memo recomputes to the same value, downstream memos *and* effects are cleaned without running.
 - **Async Support**: `createTask` handles Promise-based computations with automatic AbortController cancellation
 - **Error Handling**: Preserves error states and prevents cascade failures
 - **Reducer Capabilities**: Access to previous value enables state accumulation and transitions
@@ -274,7 +274,7 @@ const processed = todoList
 **Memo (`createMemo`)**:
 - Synchronous derived computations with memoization
 - Reducer pattern with previous value access
-- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver)
+- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver). Calling `invalidate()` marks the memo dirty and propagates `FLAG_CHECK` to sinks — effects only re-run if the memo's `equals` check determines the value actually changed.
 
 ```typescript
 const doubled = createMemo(() => count.get() * 2)
@@ -295,7 +295,7 @@ const runningTotal = createMemo(prev => prev + currentValue.get(), { value: 0 })
 
 **Task (`createTask`)**:
 - Async computations with automatic cancellation
-- Optional `watched(invalidate)` callback for lazy external invalidation
+- Optional `watched(invalidate)` callback for lazy external invalidation. Calling `invalidate()` eagerly aborts any in-flight computation and propagates `FLAG_CHECK` to sinks.
 
 ```typescript
 const userData = createTask(async (prev, abort) => {

README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.18.3
+Version 0.18.4
 
 **Cause & Effect** is a reactive state management primitives library for TypeScript. It provides the foundational building blocks for managing complex, dynamic, composite, and asynchronous state — correctly and performantly — in a unified signal graph.
 

index.dev.js

@@ -199,10 +199,12 @@ function propagate(node, newFlag = FLAG_DIRTY) {
     for (let e = node.sinks;e; e = e.nextSink)
       propagate(e.sink, FLAG_CHECK);
   } else {
-    if (flags & FLAG_DIRTY)
+    if ((flags & (FLAG_DIRTY | FLAG_CHECK)) >= newFlag)
       return;
-    node.flags = FLAG_DIRTY;
-    queuedEffects.push(node);
+    const wasQueued = flags & (FLAG_DIRTY | FLAG_CHECK);
+    node.flags = newFlag;
+    if (!wasQueued)
+      queuedEffects.push(node);
   }
 }
 function setState(node, next) {
@@ -354,7 +356,7 @@ function flush() {
   try {
     for (let i = 0;i < queuedEffects.length; i++) {
       const effect = queuedEffects[i];
-      if (effect.flags & FLAG_DIRTY)
+      if (effect.flags & (FLAG_DIRTY | FLAG_CHECK))
         refresh(effect);
     }
     queuedEffects.length = 0;
@@ -797,9 +799,7 @@ function createMemo(fn, options) {
     if (activeSink) {
       if (!node.sinks)
         node.stop = watched(() => {
-          node.flags |= FLAG_DIRTY;
-          for (let e = node.sinks;e; e = e.nextSink)
-            propagate(e.sink);
+          propagate(node);
           if (batchDepth === 0)
             flush();
         });
@@ -848,9 +848,7 @@ function createTask(fn, options) {
     if (activeSink) {
       if (!node.sinks)
         node.stop = watched(() => {
-          node.flags |= FLAG_DIRTY;
-          for (let e = node.sinks;e; e = e.nextSink)
-            propagate(e.sink);
+          propagate(node);
           if (batchDepth === 0)
             flush();
         });

index.js

@@ -1,6 +1,6 @@
 /**
  * @name Cause & Effect
- * @version 0.18.3
+ * @version 0.18.4
  * @author Esther Brunner
  */
 

index.ts

@@ -1,6 +1,6 @@
 {
 	"name": "@zeix/cause-effect",
-	"version": "0.18.3",
+	"version": "0.18.4",
 	"author": "Esther Brunner",
 	"type": "module",
 	"main": "index.js",

package.json

@@ -292,11 +292,12 @@ function propagate(node: SinkNode, newFlag = FLAG_DIRTY): void {
 		for (let e = node.sinks; e; e = e.nextSink)
 			propagate(e.sink, FLAG_CHECK)
 	} else {
-		if (flags & FLAG_DIRTY) return
+		if ((flags & (FLAG_DIRTY | FLAG_CHECK)) >= newFlag) return
 
 		// Enqueue effect for later execution
-		node.flags = FLAG_DIRTY
-		queuedEffects.push(node as EffectNode)
+		const wasQueued = flags & (FLAG_DIRTY | FLAG_CHECK)
+		node.flags = newFlag
+		if (!wasQueued) queuedEffects.push(node as EffectNode)
 	}
 }
 
@@ -471,7 +472,7 @@ function flush(): void {
 	try {
 		for (let i = 0; i < queuedEffects.length; i++) {
 			const effect = queuedEffects[i]
-			if (effect.flags & FLAG_DIRTY) refresh(effect)
+			if (effect.flags & (FLAG_DIRTY | FLAG_CHECK)) refresh(effect)
 		}
 		queuedEffects.length = 0
 	} finally {
@@ -601,6 +602,7 @@ export {
 	createScope,
 	DEFAULT_EQUALITY,
 	SKIP_EQUALITY,
+	FLAG_CHECK,
 	FLAG_CLEAN,
 	FLAG_DIRTY,
 	FLAG_RELINK,

src/graph.ts

@@ -110,9 +110,7 @@ function createMemo<T extends {}>(
 				if (activeSink) {
 					if (!node.sinks)
 						node.stop = watched(() => {
-							node.flags |= FLAG_DIRTY
-							for (let e = node.sinks; e; e = e.nextSink)
-								propagate(e.sink)
+							propagate(node as unknown as SinkNode)
 							if (batchDepth === 0) flush()
 						})
 					link(node, activeSink)