Cocoa Beans 0.0.54-beta0 Help

🪐 Flat Mapping Collection Observable

Available Since 0.0.50

Introduction

flatMapEach is the per-element analogue of 🖼️ Flat Map Observable for collections. Each element of the source is mapped to an Observable<R>, and the derived collection contains the current value of each element's observable.

Use this when the items in your collection expose observable properties — e.g. a player's display name or an entity's health — and you want a live view of one of those properties across the whole collection.

ListObservable<DisplayPlayer> players = Observable.list(); ListObservable<String> displayNames = players.flatMapEach(DisplayPlayer::displayName); // updates when: // - players are added/removed // - any tracked player's displayName changes

Usage

@Test void flatMapEachSample() { DisplayPlayer kfir = new DisplayPlayer("kfir", Observable.mutable("kfir")); DisplayPlayer lior = new DisplayPlayer("lior", Observable.mutable("lior")); ListObservable<DisplayPlayer> players = Observable.list(); players.add(kfir); players.add(lior); // flatMapEach exposes the current value of each element's inner observable ListObservable<String> displayNames = players.flatMapEach(DisplayPlayer::displayName); assertEquals(List.of("kfir", "lior"), displayNames.get()); // updates when any tracked element's inner observable changes kfir.displayName().set("Kfir Notro"); assertEquals(List.of("Kfir Notro", "lior"), displayNames.get()); // updates when the source collection changes DisplayPlayer voigon = new DisplayPlayer("voigon", Observable.mutable("voigon")); players.add(voigon); assertEquals(List.of("Kfir Notro", "lior", "voigon"), displayNames.get()); players.remove(kfir); assertEquals(List.of("lior", "voigon"), displayNames.get()); // mutating an element that is no longer tracked does NOT propagate kfir.displayName().set("ghost"); assertEquals(List.of("lior", "voigon"), displayNames.get()); }

Behavior

  • Subscribes to each element's inner observable while the element is present in the source.

  • When an element leaves the source, its inner subscription is released.

  • Multiple elements may share the same inner observable — it is observed once and stays observed as long as any referencing element is still in the source.

  • The mapper is invoked at most once per element per source change, not on every inner-value update.

  • Cached: get() reuses the previous result until the source changes or a tracked inner observable changes.

Notes per collection type

Source

Result

Element duplication

ListObservable<E>

ListObservable<R>

Order and multiplicity preserved — each occurrence resolves to its inner observable's current value

SetObservable<E>

SetObservable<R>

The source already deduplicates by element

Advantages

  • 👁 Two-layer reactivity: outer collection + inner observable properties

  • 🔒 No observer leaks: subscriptions are released when elements leave

  • 🤝 Sharing-friendly: elements sharing an inner observable share the subscription

  • ⛓ Composable: combines naturally with filter and mapEach

Last modified: 09 August 2025