[phillipc]

Fixes #438.

Stacked on #414's branch (414-if-binding-evaluating-to-false-delays-invocation-of-kodescendantscomplete).

Why

ForEachBinding dropped array changes that were made synchronously from inside its own callbacks (typically afterRender, e.g. afterRender: $parent.onRender pushing or removing items). After that, firstLastNodesList no longer matched the array, the DOM drifted out of sync, and the next delete threw TypeError: Cannot read properties of undefined (reading 'first'). This happened in sync and async mode. Details and a reproduction are in #438.

While investigating this, as turned out to always extend the current context in ForEachBinding. Unlike the template-based foreach and with, it ignored options.createChildContextWithAs, even though the foreach docs (Note 7) describe that option as the switch.

Changes

Re-entrant array changes (packages/binding.foreach/src/foreach.ts)

• processQueue() now works on a snapshot of changeQueue. Changes registered during a pass go to a fresh queue and are scheduled through animateFrame once the pass completes without throwing. Previously finally wiped them. If a pass throws, the pending changes are kept and flushed with the next array change.
• beforeQueueFlush / afterQueueFlush receive the batch that is actually being processed.
• The arrayChange subscription is set up before the initial render, so changes made during the initial afterRender are no longer missed.

as + createChildContextWithAs

• With the option enabled, foreach: { data, as: 'x' } creates a child context per item: $data is the item, $parent the outer data, and observable items are unwrapped with the observable as $rawData. The default (false, KO 3.5 behavior) is unchanged.

Cleanup

• setSync(false) drops the vendor-prefixed requestAnimationFrame fallbacks and keeps the setTimeout fallback for runtimes without rAF (Node, Bun).
• Call sites use options.global instead of a hard-coded window. .call(...) is kept so that a custom, unbound animateFrame keeps working.

Tests

New specs in packages/binding.foreach/spec/eachBehavior.ts:

• afterRender › with $parent:
  • $parent resolution in nested, virtual-element, recycled-nodeset, and async foreach.
  • Regression tests for pushing or removing items from afterRender, including during the initial render, in a nested $parent setup, and in async mode. All four fail without the fix.
  • Tests that pin the KO 3.5 compatible behavior discussed in foreach: array changes made from afterRender are dropped, later deletes throw "reading 'first'" #438: as without a child context by default, whitespace text nodes in nodes, and this not being the view model. The this test only asserts "not the view model", so the exact value is not locked in.
• `as` parameter › with options.createChildContextWithAs = true: child context, $parent at root and nested, $rawData unwrapping, $index and $list. Three of these four fail without the change; the $index/$list test is a guard.

bun run verify passes: Biome, tsc, build, ESM check, and 5481 tests (browser + happy-dom).

Docs

• foreach docs Note 7: explains that by default $parent with as is not the foreach parent.
• agents/guide.md: notes on as/$parent, whitespace nodes, this, and array changes made from callbacks.
• verified-behaviors.json and the generated markdown are updated.
• Changesets for @tko/binding.foreach (patch).

Note: bun run build in tko.io/ currently fails locally on the Starlight sidebar config (autogenerate with label, removed in Starlight v0.39). The same failure occurs on the base branch without this PR's changes.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: b2adccd4-703a-4baf-ada1-aebcc3884a91

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}