new generic Operator ***SelectMany*** for capturing concatMap, switchMap, mergeMap and exhaustMap

[hansschenker]

Proposal: Add selectMany (Rx.NET-style) as a unified map+flatten operator

TL;DR
Introduce selectMany(project, options?) as a small, explicit wrapper over the existing map+flatten family. It offers a single, discoverable entry point for “Observable of Observables” with a readable strategy parameter:

• sequential → concatMap (preserve order)
• concurrent → mergeMap (optional concurrency)
• latest-wins → switchMap (cancel previous)
• first-wins → exhaustMap (ignore new until current completes)

This mirrors Rx.NET’s SelectMany naming and reduces cognitive overhead without introducing any new semantics.

---

Motivation

Today, users must choose among four operator names for the same pattern: project to an inner stream and then flatten. For many, especially newcomers, the first step is “how do I flatten?” not “which of the four map+flatten names do I recall?”.

A single, ergonomic entry point—selectMany—lets developers write what they mean, then pick the desired flattening behavior via an option. It also provides a familiar bridge for Rx.NET users who instinctively look for SelectMany.

Benefits:

• Discoverability: searching docs for “flatten” or “select many” points to one place.
• Expressiveness: call sites read like English (e.g., strategy: 'latest-wins').
• Zero new semantics: delegates to existing operators under the hood.

---

API (strawman)

export type SelectManyStrategy =
  | 'sequential'   // concatMap
  | 'concurrent'   // mergeMap
  | 'latest-wins'  // switchMap
  | 'first-wins';  // exhaustMap

export interface SelectManyOptions<R, O = R> {
  strategy?: SelectManyStrategy; // default: 'sequential'
  concurrency?: number;          // only for 'concurrent'
  // Optional post-flatten steps (can be omitted if we want a minimal core):
  filter?: (value: R) => boolean;
  map?: (value: R) => O;
}

export function selectMany<T, R, O = R>(
  project: (value: T) => ObservableInput<R>,
  options?: SelectManyOptions<R, O>
): OperatorFunction<T, O>;

Drop-in equivalences

source$.pipe(selectMany(x => inner$(x)))                                // ≈ concatMap
source$.pipe(selectMany(x => inner$(x), { strategy: 'concurrent' }))    // ≈ mergeMap
source$.pipe(selectMany(x => inner$(x), { strategy: 'latest-wins' }))   // ≈ switchMap
source$.pipe(selectMany(x => inner$(x), { strategy: 'first-wins' }))    // ≈ exhaustMap

---

Examples

Users → Todos; latest selection cancels previous:

users$.pipe(
  selectMany(u => fetchTodos$(u.id), {
    strategy: 'latest-wins',
    filter:   t => !t.completed,                       // optional
    map:      t => ({ id: t.id, title: t.title })     // optional
  })
);

Bounded concurrency:

files$.pipe(
  selectMany(f => upload$(f), { strategy: 'concurrent', concurrency: 3 })
);

---

Design Notes

• No new behavior: selectMany simply delegates to concatMap / mergeMap / switchMap / exhaustMap.

• Naming: Uses the widely recognized Rx.NET term SelectMany, which matches the mental model “select many results from each value.”

• Options scope:

  • Minimal: only strategy (and concurrency when 'concurrent').
  • Extended (shown above): allow optional filter/map after flatten to keep common pipelines compact. If API surface is a concern, we can omit these extras from core.

• Type safety: concurrency valid only with 'concurrent'.

---

Bundle & Tree-shaking

One concern: a single file that imports all four flatteners could bloat bundles.

Mitigations (choose any or both):

1. Keep selectMany in its own file with /* @__PURE__ */ annotations and rely on DCE.

2. Offer per-strategy aliases in separate entry points (tree-shakeable):

   • selectManySequential, selectManyConcurrent, selectManyLatestWins, selectManyFirstWins.

If bundle size is still a concern, we can land the minimal API (no post-flatten options) to keep the file small.

---

Alternatives Considered

• Do nothing: Keep the four existing operators only—status quo is fine for experienced users but raises the learning curve.
• Re-introduce flatMap: Historically an alias to mergeMap; doesn’t solve discoverability for the other strategies.
• Name it chain / bind / flatSelect: Functional but less familiar to the Rx community than SelectMany.

---

Backward Compatibility

• 100% backward compatible; no changes to existing operators or behaviors.
• This is an additive convenience that can be documented alongside the existing four.

---

Implementation Sketch (thin wrapper)

import { ObservableInput, OperatorFunction } from '../types';
import { concatMap } from './concatMap';
import { mergeMap } from './mergeMap';
import { switchMap } from './switchMap';
import { exhaustMap } from './exhaustMap';
// (Optional) post-flatten steps:
// import { filter as rxFilter } from './filter';
// import { map as rxMap } from './map';

export function selectMany<T, R, O = R>(
  project: (value: T) => ObservableInput<R>,
  opts: { strategy?: 'sequential'|'concurrent'|'latest-wins'|'first-wins'; concurrency?: number; /* filter?, map? */ } = {}
): OperatorFunction<T, O> {
  const { strategy = 'sequential', concurrency = Infinity } = opts;

  const flatten =
    strategy === 'sequential'  ? concatMap(project) :
    strategy === 'concurrent'  ? mergeMap(project, concurrency) :
    strategy === 'latest-wins' ? switchMap(project) :
    strategy === 'first-wins'  ? exhaustMap(project) :
    (() => { throw new Error(`Unknown strategy: ${String(strategy)}`); })();

  return source => source.pipe(flatten) as any; // (add filter/map here if included)
}

Marble tests would mirror each underlying operator’s semantics (ordering, cancellation, concurrency), plus a typed test ensuring concurrency is gated to 'concurrent'.

---

Open Questions for Maintainers

1. Scope: Do you prefer the minimal API (only strategy) or are you open to the optional post-flatten filter/map?
2. Naming: Any objections to using the Rx.NET name SelectMany?
3. Docs: Should selectMany live on the same page as the four flatteners, or on its own page with cross-links?
4. Tree-shaking: Would you prefer separate per-strategy entry points to guarantee minimal bundles?
5. Status: If added, should this be “recommended for newcomers” in docs, while keeping the four specialized operators as advanced/performant choices?

---

Next Steps

If there’s interest, I can open a PR with:

• implementation + tests (marbles),
• docs page with a behavior table and “Before/After” examples,
• (optional) separate entry points for per-strategy aliases.

Thanks for considering! Happy to iterate based on feedback.