diff --git a/.github/skills/add-documentation/SKILL.md b/.github/skills/add-documentation/SKILL.md new file mode 100644 index 000000000..69ac28012 --- /dev/null +++ b/.github/skills/add-documentation/SKILL.md @@ -0,0 +1,269 @@ +--- +name: add-documentation +description: Use when adding or updating XML documentation for any public API in DynamicData, including new operators, changed behavior, batch documentation passes, or PR reviewer requests for improved docs. Covers extension methods, public classes, interfaces, enums, and any member visible in the published API reference. +--- + +# Add Documentation + +## Overview + +Write publication-quality XML documentation for DynamicData public APIs. Every behavioral claim must be traced from the implementation source, not guessed from naming conventions. The documentation will be extracted as HTML and published on the ReactiveUI docs site. + +## When to Use + +- New operator or public API added +- Existing operator's behavior changed +- Batch documentation pass across a file +- PR reviewer requests improved documentation +- Any public type, interface, enum, or member needs docs + +## Core Rule: Additive Only + +Never remove existing useful information from comments. After making changes, diff against main to confirm nothing substantive was lost. + +## Unified Template + +Start from this template for any primary overload. Delete sections that do not apply. + +```xml +/// +/// [1-3 sentences: what it does, why you'd use it. No behavioral details.] +/// +/// The type of items. +/// The type of the key. +/// The source to [verb: filter, transform, sort, etc.]. +/// An that determines sort order. +/// [What it emits and what each emission represents.] +/// Thrown when is null. +/// +/// [When to use. How it differs from alternatives. Multiple paragraphs fine.] +/// +/// +/// +/// +/// +/// +/// +/// EventBehavior +/// +/// Add[specific outcome, bold output reasons] +/// Update[specific outcome] +/// Remove[specific outcome, mention cleanup] +/// Refresh[specific outcome, trace carefully] +/// +/// AddRange[specific outcome] +/// Replace[list equivalent of Update] +/// RemoveRange[specific outcome] +/// Moved[specific outcome] +/// Clear[specific outcome] +/// +/// OnError[forwarded? swallowed? conditional?] +/// OnCompleted[immediate? waits for children?] +/// +/// +/// +/// Source changeset handling (parent events): +/// +/// EventBehavior +/// Add[subscribes to child / creates state] +/// Update[disposes old, subscribes to new] +/// Remove[disposes, emits downstream removes] +/// Refresh[no effect / re-evaluates] +/// +/// Per-item observable handling: +/// +/// EmissionBehavior +/// First value[what appears downstream] +/// Subsequent values[updates? replacements?] +/// Error[terminates? swallowed?] +/// Completed[freezes? removed?] +/// +/// +/// Worth noting: [Non-obvious behavior, edge cases, disposal semantics.] +/// +/// +/// +/// +/// +``` + +For **secondary overloads** in an overload set: +```xml + +/// +/// A that [specific difference]. +/// This overload [what differs]. Delegates to . + + + + +``` + +## Process + +### 1. Analyze the Implementation + +Read the actual source code. Trace each code path for every change reason the operator handles. + +Key questions: +- What does each change reason produce downstream? Name the exact output. +- Are there conditional outcomes? (e.g., Filter's Update has four possible results) +- Does the operator create per-item subscriptions? When created/disposed? +- Are errors from child subscriptions forwarded or swallowed? +- Does OnCompleted wait for child subscriptions? + +Refresh behavior varies significantly between operators: some re-evaluate (Filter), some forward as-is (Transform by default), some drop (FilterImmutable), some convert to other change types. But all change reasons deserve the same careful tracing. + +### 2. Choose What to Include + +| The method... | Template sections to use | +|---|---| +| Extends `IObservable`, produces `IObservable` | Single event table (cache or list rows) | +| Has multiple input sources or per-item observables | Multi-source tables (parent + child) | +| Extends `ISourceCache`/`ISourceList`, returns void | Single table, framed as "produced" | +| Produces non-changeset output (`IObservable`, `bool`, etc.) | Single table, framed as subscription lifecycle | +| Is a class, interface, enum, or non-extension member | Summary, params, returns, remarks (no event table) | + +### 3. Apply Quality Rules + +**Params**: Every `` must read as natural English with the type linked via `` woven into the sentence. No type is exempt from linking (including enums, `Optional`, `Change`, `IChangeSet`, standard library types like `IComparer`, `TimeSpan`, `IScheduler`). Use `` / `` / `` for C# keywords. + +Param writing rules: +- **Reads as English.** Read it aloud. If it sounds wrong, it IS wrong. +- **Starts with an article** ("The", "A", "An") or a condition ("When", "If"). +- **Links the actual parameter type** from the method signature. Use ``. Get the generic type arguments right (e.g., `IComparer{TObject}` not `IComparer{T}` when the param type is `IComparer`). +- **Describes the purpose**, not just the type. Every param description must answer: "what does the caller use this for?" +- **No redundancy with the type name.** The type `IChangeSet` already says "changeset", so don't add "changeset stream" after it. The type `IObservable` already says "observable", so don't add "observable" after it. The type `IComparer` already says "comparer", so don't add "comparer" after it. +- **No double articles.** "The source [type] the left stream" has two articles fighting each other. +- **Combined nested crefs** for observable changeset types. Write `IObservable{IChangeSet{TObject, TKey}}` as one cref. NEVER split into `IObservable{T}` + "of" + `IChangeSet{...}`. +- **For deeply nested generics** (3+ nesting levels), use `{T}` in the cref and describe the actual type in prose. +- **For `params` array parameters**, do not include `[]` in the cref. +- **For `Optional.None`**, use ``. + +```xml + + + +/// The source of . + + +/// The source changeset stream. + + +/// The . + + +/// The comparer used for sorting. + + +/// The source the left input. + + + + +/// The source to filter. +/// The source to transform. +/// The source to bind. +/// The to add items to. + + +/// The left to join. +/// The right to join. + + +/// The that will receive the changes. +/// The output that will be populated with the results. + + +/// The that determines sort order. +/// An optional for determining item equality. + + +/// A that projects each source item into a destination item. +/// A predicate that determines which items to include. +/// A that extracts the join key from each right item. + + +/// An optional for scheduling expiry timers. +/// The that controls reset threshold and binding behavior. + + +/// When , re-invokes the transform factory on Refresh changes instead of forwarding them. +/// When , invokes the callback for all tracked items when the subscription is disposed. +``` + +**SeeAlso**: Bidirectional for overload sets. Link safe/async/immutable variants, similar operators, complementary operators, commonly confused operators. + +**Type references**: All types use ``, including enums, structs, and standard library types. Method/event/property names use `...`. Internal types must not appear; describe behavior instead. + +**Tone**: No em dashes. No emoji. No filler words (comprehensive, robust, seamlessly, leverage, utilize, facilitate). Be specific: "an **Update** is emitted" not "the change is propagated". Use "Worth noting" for non-obvious behavior. + +### 4. Verify + +```bash +dotnet build src/DynamicData/DynamicData.csproj --no-restore -c Release --framework net9.0 +``` +- 0 errors, no new CS1574 warnings +- No em dashes (Unicode 0x2014) +- No "The source." remaining +- Spot-check 3-5 operators against implementation +- Diff against main: confirm nothing lost + +## Before and After + +**BEFORE** (old-style): +```xml +/// +/// Filters the specified source. +/// +/// The source. +/// The filter. +/// An observable which emits change sets. +``` + +**AFTER** (publication-quality): +```xml +/// +/// Filters items from the source changeset stream using a static predicate. +/// Only items satisfying are included downstream. +/// +/// The source of . +/// A predicate. Items returning true are included. +/// A changeset stream containing only items satisfying . +/// +/// Use this overload when the predicate is fixed for the subscription's lifetime. +/// +/// EventBehavior +/// AddPredicate evaluated. If passes, Add emitted. Otherwise dropped. +/// UpdateRe-evaluated. Both pass: Update. New passes only: Add. Old passed only: Remove. Neither: dropped. +/// RemoveIf downstream, Remove emitted. Otherwise dropped. +/// RefreshRe-evaluated. Now passes: Add. Still passes: Refresh. No longer passes: Remove. Still fails: dropped. +/// OnErrorForwarded. +/// OnCompletedForwarded. +/// +/// Worth noting: Refresh re-evaluation can promote or demote items. +/// +/// +/// +/// +``` + +## Batch Application + +1. Dispatch parallel **read-only** agents to analyze implementations (group by family) +2. Apply edits via **single agent or yourself** (multiple agents editing one file clobber each other) +3. Build, audit metrics, spot-check accuracy +4. Diff against main for lost details + +## Common Mistakes + +| Mistake | Fix | +|---------|-----| +| Guessing behavior from method name | Read the implementation | +| `IComparer` for a type | `` | +| Referencing internal types | Describe behavior instead | +| One-way seealso links | Bidirectional | +| Multiple agents editing same file | One editor at a time | +| Removing existing information | Additive only; diff against main | +| Only cache rows for list operators | List needs AddRange, RemoveRange, Moved, Clear | +| Params missing type links | Every param links its type | diff --git a/src/DynamicData/Cache/ObservableCacheEx.SortAndBind.cs b/src/DynamicData/Cache/ObservableCacheEx.SortAndBind.cs index 06c14e0d4..9ce7130f2 100644 --- a/src/DynamicData/Cache/ObservableCacheEx.SortAndBind.cs +++ b/src/DynamicData/Cache/ObservableCacheEx.SortAndBind.cs @@ -18,9 +18,10 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. + /// The source to sort and bind. + /// The output that will be populated with the sorted results. /// An observable which will emit change sets. + /// Creates a and delegates to . public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, out ReadOnlyObservableCollection readOnlyObservableCollection) @@ -38,10 +39,11 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// Bind and sort default options. + /// The source to sort and bind. + /// The output that will be populated with the sorted results. + /// The with default settings. /// An observable which will emit change sets. + /// Creates a and delegates to . public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -60,9 +62,10 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. + /// The source to sort and bind. + /// The to bind sorted results to. /// An observable which will emit change sets. + /// This is the primary Bind overload for paged data. It applies paged changeset mutations directly to the target list. public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, IList targetList) @@ -75,10 +78,11 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. - /// Bind and sort default options. + /// The source to sort and bind. + /// The to bind sorted results to. + /// The with default settings. /// An observable which will emit change sets. + /// This overload accepts to control reset threshold behavior. public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, IList targetList, @@ -92,9 +96,10 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. + /// The source to sort and bind. + /// The output that will be populated with the sorted results. /// An observable which will emit change sets. + /// Creates a and delegates to . public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, out ReadOnlyObservableCollection readOnlyObservableCollection) @@ -112,10 +117,11 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// Bind and sort default options. + /// The source to sort and bind. + /// The output that will be populated with the sorted results. + /// The with default settings. /// An observable which will emit change sets. + /// Creates a and delegates to . public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -134,9 +140,10 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. + /// The source to sort and bind. + /// The to bind sorted results to. /// An observable which will emit change sets. + /// This is the primary Bind overload for virtualized data. It applies virtualized changeset mutations directly to the target list. public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, IList targetList) @@ -149,10 +156,11 @@ public static partial class ObservableCacheEx /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. - /// Bind and sort default options. + /// The source to sort and bind. + /// The to bind sorted results to. + /// The with default settings. /// An observable which will emit change sets. + /// This overload accepts to control reset threshold behavior. public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable>> source, IList targetList, @@ -161,14 +169,8 @@ public static partial class ObservableCacheEx where TKey : notnull => new BindVirtualized(source, targetList, options).Run(); - /// - /// Bind sorted data to the specified collection, for an object which implements IComparable>. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The list to bind to. - /// An observable which will emit change sets. + /// + /// This overload uses for types implementing . public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList) @@ -176,15 +178,8 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(targetList, DynamicDataOptions.SortAndBind); - /// - /// Bind sorted data to the specified collection, for an object which implements IComparable>. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The list to bind to. - /// Bind and sort default options. - /// An observable which will emit change sets. + /// + /// This overload uses for types implementing . public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList, @@ -193,15 +188,7 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(targetList, Comparer.Default, options); - /// - /// Bind sorted data to the specified collection. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The list to bind to. - /// The comparer to order the resulting dataset. - /// An observable which will emit change sets. + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList, @@ -211,15 +198,34 @@ public static partial class ObservableCacheEx source.SortAndBind(targetList, comparer, DynamicDataOptions.SortAndBind); /// - /// Bind sorted data to the specified collection. + /// Sorts the source changeset using and applies incremental changes + /// directly to , keeping it sorted in-place. + /// Combines the behavior of Sort and Bind into a single optimized step. /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. - /// The comparer to order the resulting dataset. - /// Bind and sort default options. + /// The source to sort and bind. + /// The to bind sorted results to. Items are inserted, removed, and moved in-place to maintain sort order. + /// The that determines sort order. + /// The controlling reset threshold and initial capacity. /// An observable which will emit change sets. + /// + /// + /// This operator is the preferred replacement for the .Sort().Bind() chain. + /// It applies sort logic and collection mutations in a single pass, avoiding intermediate allocations. + /// + /// + /// EventBehavior + /// AddItem inserted at the correct sorted position in . + /// UpdateOld item removed and new item inserted at its sorted position. + /// RemoveItem removed from . + /// RefreshSort position is re-evaluated. If the position changed, the item is moved in-place. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: Large batches may trigger a full list reset (clear + re-add) instead of incremental moves, controlled by . This fires CollectionChanged with Reset action, which can be more efficient for UI virtualization but causes a visual flicker. + /// + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList, @@ -229,15 +235,7 @@ public static partial class ObservableCacheEx where TKey : notnull => new SortAndBind(source, comparer, options, targetList).Run(); - /// - /// Bind sorted data to the specified collection, using an observable of comparers to switch sort order. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The list to bind to. - /// An observable of comparers which enables the sort order to be changed.> - /// An observable which will emit change sets. + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList, @@ -247,15 +245,33 @@ public static partial class ObservableCacheEx source.SortAndBind(targetList, comparerChanged, DynamicDataOptions.SortAndBind); /// - /// Bind sorted data to the specified collection, using an observable of comparers to switch sort order. + /// Sorts the source changeset and applies incremental changes directly to , + /// re-sorting when the comparer observable emits a new comparer. /// /// The type of the object. /// The type of the key. - /// The source. - /// The list to bind to. - /// An observable of comparers which enables the sort order to be changed.> - /// Bind and sort default options. + /// The source to sort and bind. + /// The to bind sorted results to. Items are inserted, removed, and moved in-place to maintain sort order. + /// An that emits new comparers to re-sort with. + /// The controlling reset threshold and initial capacity. /// An observable which will emit change sets. + /// + /// + /// When emits a new comparer, all items are re-sorted and the target list is updated. + /// No data is emitted until the first comparer arrives. + /// + /// + /// EventBehavior + /// AddItem inserted at the correct sorted position in . + /// UpdateOld item removed and new item inserted at its sorted position. + /// RemoveItem removed from . + /// RefreshSort position is re-evaluated. If the position changed, the item is moved in-place. + /// Comparer changedFull re-sort of all items. The target list is updated to reflect the new order. + /// OnErrorForwarded to the downstream observer. + /// + /// Worth noting: No data is emitted until the comparer observable produces its first value. Large batches or comparer changes may trigger a full list reset depending on . + /// + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, IList targetList, @@ -265,14 +281,8 @@ public static partial class ObservableCacheEx where TKey : notnull => new SortAndBind(source, comparerChanged, options, targetList).Run(); - /// - /// Bind sorted data to the specified readonly observable collection for an object which implements IComparable>. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// An observable which will emit change sets. + /// + /// This overload uses for types implementing . public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection) @@ -280,15 +290,8 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(out readOnlyObservableCollection, Comparer.Default, DynamicDataOptions.SortAndBind); - /// - /// Bind sorted data to the specified readonly observable collection for an object which implements IComparable>. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// Bind and sort default options. - /// An observable which will emit change sets. + /// + /// This overload uses for types implementing . public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -297,15 +300,7 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(out readOnlyObservableCollection, Comparer.Default, options); - /// - /// Bind sorted data to the specified readonly observable collection. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// The comparer to order the resulting dataset. - /// An observable which will emit change sets. + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -314,16 +309,11 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(out readOnlyObservableCollection, comparer, DynamicDataOptions.SortAndBind); - /// - /// Bind sorted data to the specified readonly observable collection. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// The comparer to order the resulting dataset. - /// Bind and sort default options. - /// An observable which will emit change sets. + /// + /// The source to sort and bind. + /// The output that will be populated with the sorted results. + /// The that determines sort order. + /// The controlling reset threshold and initial capacity. public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -342,15 +332,7 @@ public static partial class ObservableCacheEx return new SortAndBind(source, comparer, options, observableCollection).Run(); } - /// - /// Bind sorted data to the specified readonly observable collection, using an observable of comparers to switch sort order. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// An observable of comparers which enables the sort order to be changed. - /// An observable which will emit change sets. + /// public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, @@ -359,16 +341,11 @@ public static partial class ObservableCacheEx where TKey : notnull => source.SortAndBind(out readOnlyObservableCollection, comparerChanged, DynamicDataOptions.SortAndBind); - /// - /// Bind sorted data to the specified readonly observable collection, using an observable of comparers to switch sort order. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// An observable of comparers which enables the sort order to be changed.> - /// Bind and sort default options. - /// An observable which will emit change sets. + /// + /// The source to sort and bind. + /// The output that will be populated with the sorted results. + /// An that emits new comparers to re-sort with. + /// The controlling reset threshold and initial capacity. public static IObservable> SortAndBind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TObject, TKey>( this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, diff --git a/src/DynamicData/Cache/ObservableCacheEx.VirtualiseAndPage.cs b/src/DynamicData/Cache/ObservableCacheEx.VirtualiseAndPage.cs index d4a5f060c..d5a4bd979 100644 --- a/src/DynamicData/Cache/ObservableCacheEx.VirtualiseAndPage.cs +++ b/src/DynamicData/Cache/ObservableCacheEx.VirtualiseAndPage.cs @@ -1,4 +1,4 @@ -// Copyright (c) 2011-2025 Roland Pheasant. All rights reserved. +// Copyright (c) 2011-2025 Roland Pheasant. All rights reserved. // Roland Pheasant licenses this file to you under the MIT license. // See the LICENSE file in the project root for full license information. @@ -12,16 +12,8 @@ namespace DynamicData; /// public static partial class ObservableCacheEx { - /// - /// Sort and virtualize the underlying data from the specified source. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The comparer to order the resulting dataset. - /// The virtualizing requests. - /// An observable which will emit virtual change sets. - /// source. + /// + /// This overload uses default . public static IObservable>> SortAndVirtualize(this IObservable> source, IComparer comparer, IObservable virtualRequests) @@ -29,16 +21,8 @@ public static IObservable>> So where TKey : notnull => source.SortAndVirtualize(comparer, virtualRequests, new SortAndVirtualizeOptions()); - /// - /// Sort and virtualize the underlying data from the specified source. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// An observable of comparers which enables the sort order to be changed.> - /// The virtualizing requests. - /// An observable which will emit virtual change sets. - /// source. + /// + /// This overload uses default . public static IObservable>> SortAndVirtualize( this IObservable> source, IObservable> comparerChanged, @@ -53,16 +37,35 @@ public static IObservable>> So } /// - /// Sort and virtualize the underlying data from the specified source. + /// Sorts unsorted data using , then returns only items within the + /// virtual window defined by . /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer to order the resulting dataset. - /// The virtualizing requests. - /// Addition optimization options for virtualization. + /// The source to paginate. + /// The that determines sort order. + /// The that controls which window of sorted items to include. + /// The for controlling virtualization behavior. /// An observable which will emit virtual change sets. /// source. + /// + /// + /// Combines sorting and index-based windowing. Only items within the current virtual window are emitted. + /// Use the observable comparer overload if you need to change sort order at runtime. + /// + /// + /// EventBehavior + /// AddIf the new item's sorted position falls within the window, an Add is emitted. Items pushed out of the window produce a Remove. + /// UpdateIf the updated item is within the window, an Update is emitted. Sort position changes may cause items to enter or leave the window. + /// RemoveIf the removed item was within the window, a Remove is emitted. Items shifted into the window produce an Add. + /// RefreshSort position is re-evaluated. Window membership may change. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No data is emitted until produces its first value. Changing the window can cause a full recalculation of visible items. + /// + /// + /// public static IObservable>> SortAndVirtualize( this IObservable> source, IComparer comparer, @@ -78,16 +81,35 @@ public static IObservable>> So } /// - /// Sort and virtualize the underlying data from the specified source. + /// Sorts unsorted data, then returns only the items within the virtual window defined by + /// (start index + size). Re-sorts when the comparer observable emits. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable of comparers which enables the sort order to be changed.> - /// The virtualizing requests. - /// Addition optimization options for virtualization. + /// The source to paginate. + /// An that emits new comparers to re-sort with. + /// The that controls which window of sorted items to include. + /// The for controlling virtualization behavior. /// An observable which will emit virtual change sets. /// source. + /// + /// + /// Combines sorting and index-based windowing in a single operator. Only items within the + /// current virtual window are emitted downstream. The window is defined by a start index and size. + /// + /// + /// EventBehavior + /// AddIf the new item's sorted position falls within the window, an Add is emitted. Items pushed out of the window produce a Remove. + /// UpdateIf the updated item is within the window, an Update is emitted. Sort position changes may cause items to enter or leave the window. + /// RemoveIf the removed item was within the window, a Remove is emitted. Items shifted into the window produce an Add. + /// RefreshSort position is re-evaluated. Window membership may change. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No data is emitted until both the comparer observable and virtualRequests have produced their first values. Changing the window or comparer can cause a full recalculation of visible items. + /// + /// + /// public static IObservable>> SortAndVirtualize( this IObservable> source, IObservable> comparerChanged, @@ -107,8 +129,8 @@ public static IObservable>> So /// /// The type of the object. /// The type of the key. - /// The source. - /// The virtualising requests. + /// The source to paginate. + /// The that controls which window of sorted items to include. /// An observable which will emit virtual change sets. /// source. [Obsolete(Constants.VirtualizeIsObsolete)] @@ -123,16 +145,25 @@ public static IObservable> Virtualise - /// Limits the size of the result set to the specified number, ordering by the comparer. + /// Returns the top items from the source, sorted by . + /// Equivalent to SortAndVirtualize with a fixed window starting at index 0. /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer. - /// The size. + /// The source to limit. + /// The that determines sort order. + /// The maximum number of items to return. /// An observable which will emit virtual change sets. /// source. /// size;Size should be greater than zero. + /// + /// + /// Internally delegates to + /// with a fixed of (0, size). + /// + /// Worth noting: When the Nth item is displaced by a new item with higher sort priority, the displaced item is emitted as a Remove and the new item as an Add. + /// + /// public static IObservable>> Top(this IObservable> source, IComparer comparer, int size) where TObject : notnull where TKey : notnull @@ -153,8 +184,8 @@ public static IObservable>> To /// /// The type of the object. /// The type of the key. - /// The source. - /// The size. + /// The source to paginate. + /// The maximum number of items to include. /// An observable which will emit virtual change sets. /// source. /// size;Size should be greater than zero. @@ -173,16 +204,8 @@ public static IObservable> Top(t return new Virtualise(source, Observable.Return(new VirtualRequest(0, size))).Run(); } - /// - /// Sort and page the underlying data from the specified source. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The comparer to order the resulting dataset. - /// The virtualizing requests. - /// An observable which will emit virtual change sets. - /// source. + /// + /// This overload uses default . public static IObservable>> SortAndPage(this IObservable> source, IComparer comparer, IObservable pageRequests) @@ -190,16 +213,8 @@ public static IObservable>> SortA where TKey : notnull => source.SortAndPage(comparer, pageRequests, new SortAndPageOptions()); - /// - /// Sort and page the underlying data from the specified source. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// An observable of comparers which enables the sort order to be changed.> - /// The virtualizing requests. - /// An observable which will emit virtual change sets. - /// source. + /// + /// This overload uses default . public static IObservable>> SortAndPage( this IObservable> source, IObservable> comparerChanged, @@ -214,16 +229,34 @@ public static IObservable>> SortA } /// - /// Sort and page the underlying data from the specified source. + /// Sorts unsorted data using , then pages the result using + /// . /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer to order the resulting dataset. - /// The virtualizing requests. - /// Addition optimization options for virtualization. - /// An observable which will emit virtual change sets. + /// The source to paginate. + /// The that determines sort order. + /// The that controls which page of sorted items to include. + /// The for controlling paging behavior. + /// An observable which will emit paged change sets. /// source. + /// + /// + /// Combines sorting and page-based windowing. Only items on the current page are emitted. + /// Use the observable comparer overload if you need to change sort order at runtime. + /// + /// + /// EventBehavior + /// AddIf the new item's sorted position falls on the current page, an Add is emitted. Items pushed off the page produce a Remove. + /// UpdateIf the updated item is on the current page, an Update is emitted. Sort position changes may move items on or off the page. + /// RemoveIf the removed item was on the current page, a Remove is emitted. Items shifted onto the page produce an Add. + /// RefreshSort position is re-evaluated. Page membership may change. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No data is emitted until produces its first value. Page numbers are 1-based. Requesting a page beyond the data range results in an empty page. + /// + /// public static IObservable>> SortAndPage( this IObservable> source, IComparer comparer, @@ -239,16 +272,34 @@ public static IObservable>> SortA } /// - /// Sort and page the underlying data from the specified source. + /// Sorts unsorted data, then pages the result using page number and page size from + /// . Re-sorts when the comparer observable emits. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable of comparers which enables the sort order to be changed.> - /// The virtualizing requests. - /// Addition optimization options for virtualization. - /// An observable which will emit virtual change sets. + /// The source to paginate. + /// An that emits new comparers to re-sort with. + /// The that controls which page of sorted items to include. + /// The for controlling paging behavior. + /// An observable which will emit paged change sets. /// source. + /// + /// + /// Combines sorting and page-based windowing in a single operator. Only items on the current page + /// are emitted downstream. The page is defined by a 1-based page number and page size. + /// + /// + /// EventBehavior + /// AddIf the new item's sorted position falls on the current page, an Add is emitted. Items pushed off the page produce a Remove. + /// UpdateIf the updated item is on the current page, an Update is emitted. Sort position changes may move items on or off the page. + /// RemoveIf the removed item was on the current page, a Remove is emitted. Items shifted onto the page produce an Add. + /// RefreshSort position is re-evaluated. Page membership may change. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No data is emitted until both the comparer observable and pageRequests have produced their first values. Page numbers are 1-based. Requesting a page beyond the data range results in an empty page. + /// + /// public static IObservable>> SortAndPage( this IObservable> source, IObservable> comparerChanged, @@ -268,8 +319,8 @@ public static IObservable>> SortA /// /// The type of the object. /// The type of the key. - /// The source. - /// The page requests. + /// The source to paginate. + /// The that controls which page of sorted items to include. /// An observable which emits change sets. [Obsolete(Constants.PageIsObsolete)] public static IObservable> Page(this IObservable> source, IObservable pageRequests) diff --git a/src/DynamicData/Cache/ObservableCacheEx.cs b/src/DynamicData/Cache/ObservableCacheEx.cs index 4edf35285..e532d15d1 100644 --- a/src/DynamicData/Cache/ObservableCacheEx.cs +++ b/src/DynamicData/Cache/ObservableCacheEx.cs @@ -28,18 +28,32 @@ public static partial class ObservableCacheEx private const bool DefaultResortOnSourceRefresh = true; /// - /// Inject side effects into the stream using the specified adaptor. + /// Injects a side effect into the changeset stream by calling . + /// for every changeset, then forwarding it downstream unchanged. /// - /// The type of the object. + /// The type of items in the cache. /// The type of the key. - /// The source. - /// The adaptor. - /// An observable which will emit change sets. - /// - /// source - /// or - /// destination. - /// + /// The source to observe and adapt. + /// The whose Adapt method is called for each changeset. + /// An observable that emits the same changesets as , after the adaptor has processed each one. + /// + /// + /// This is a thin wrapper around Rx's Do operator. The adaptor receives each changeset + /// as a side effect; the changeset itself is forwarded downstream unmodified. + /// + /// + /// EventBehavior + /// AddPassed to the adaptor, then forwarded. + /// UpdatePassed to the adaptor, then forwarded. + /// RemovePassed to the adaptor, then forwarded. + /// RefreshPassed to the adaptor, then forwarded. + /// OnErrorForwarded to the downstream observer. The adaptor is not called. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// or is . + /// + /// public static IObservable> Adapt(this IObservable> source, IChangeSetAdaptor adaptor) where TObject : notnull where TKey : notnull @@ -50,19 +64,10 @@ public static IObservable> Adapt(this I return source.Do(adaptor.Adapt); } - /// - /// Inject side effects into the stream using the specified sorted adaptor. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The adaptor. - /// An observable which will emit change sets. - /// - /// source - /// or - /// destination. - /// + /// + /// The source to observe and adapt. + /// The whose Adapt method is called for each changeset. + /// This overload operates on . Delegates to Rx's Do operator. public static IObservable> Adapt(this IObservable> source, ISortedChangeSetAdaptor adaptor) where TObject : notnull where TKey : notnull @@ -74,13 +79,26 @@ public static IObservable> Adapt(this I } /// - /// Adds or updates the cache with the specified item. + /// Adds or updates the cache with the specified item, producing a changeset with a single Add + /// (if the key is new) or Update (if the key already exists). /// /// The type of the object. /// The type of the key. - /// The source. - /// The item. - /// source. + /// The to add or update items in. + /// The item to add or update. + /// + /// Convenience method that wraps a single-item mutation inside . + /// + /// EventBehavior + /// AddProduced when the key does not already exist in the cache. + /// UpdateProduced when the key already exists. The previous value is included in the changeset. + /// RemoveNot produced by this method. + /// RefreshNot produced by this method. + /// + /// + /// is . + /// + /// public static void AddOrUpdate(this ISourceCache source, TObject item) where TObject : notnull where TKey : notnull @@ -90,15 +108,11 @@ public static void AddOrUpdate(this ISourceCache s source.Edit(updater => updater.AddOrUpdate(item)); } - /// - /// Adds or updates the cache with the specified item. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The item. - /// The equality comparer used to determine whether a new item is the same as an existing cached item. - /// source. + /// + /// The to add or update items in. + /// The item to add or update. + /// The used to determine whether a new item is the same as an existing cached item. When equal, the update is skipped. + /// This overload uses to suppress no-op updates when the new value equals the existing one. public static void AddOrUpdate(this ISourceCache source, TObject item, IEqualityComparer equalityComparer) where TObject : notnull where TKey : notnull @@ -108,16 +122,10 @@ public static void AddOrUpdate(this ISourceCache s source.Edit(updater => updater.AddOrUpdate(item, equalityComparer)); } - /// - /// - /// Adds or updates the cache with the specified items. - /// - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The items. - /// source. + /// + /// The to add or update items in. + /// The of items to add or update. + /// Batch overload. All items are added/updated inside a single call, producing one changeset. public static void AddOrUpdate(this ISourceCache source, IEnumerable items) where TObject : notnull where TKey : notnull @@ -127,17 +135,11 @@ public static void AddOrUpdate(this ISourceCache s source.Edit(updater => updater.AddOrUpdate(items)); } - /// - /// - /// Adds or updates the cache with the specified items. - /// - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The items. - /// The equality comparer used to determine whether a new item is the same as an existing cached item. - /// source. + /// + /// The to add or update items in. + /// The of items to add or update. + /// The used to determine whether a new item is the same as an existing cached item. When equal, the update is skipped. + /// Batch overload with equality comparison. All items are added/updated inside a single call. public static void AddOrUpdate(this ISourceCache source, IEnumerable items, IEqualityComparer equalityComparer) where TObject : notnull where TKey : notnull @@ -147,15 +149,11 @@ public static void AddOrUpdate(this ISourceCache s source.Edit(updater => updater.AddOrUpdate(items, equalityComparer)); } - /// - /// Adds or updates the cache with the specified item / key pair. - /// - /// The type of the object. - /// The type of the key. - /// The source cache. - /// The item to add or update. - /// The key to add or update. - /// source. + /// + /// The to add or update items in. + /// The item to add or update. + /// The key to associate with the item. + /// This overload operates on , which requires an explicit key parameter. public static void AddOrUpdate(this IIntermediateCache source, TObject item, TKey key) where TObject : notnull where TKey : notnull @@ -172,10 +170,11 @@ public static void AddOrUpdate(this IIntermediateCache /// The type of the object. /// The type of the key. - /// The source. - /// The others. + /// The source to combine. + /// The additional streams to combine with. /// An observable which emits change sets. /// source or others. + /// public static IObservable> And(this IObservable> source, params IObservable>[] others) where TObject : notnull where TKey : notnull @@ -192,7 +191,7 @@ public static IObservable> And(this IOb /// /// The type of the object. /// The type of the key. - /// The source. + /// The of streams to combine. /// An observable which emits change sets. /// /// source @@ -214,7 +213,7 @@ public static IObservable> And(this ICo /// /// The type of the object. /// The type of the key. - /// The source. + /// The of streams to combine. /// An observable which emits change sets. public static IObservable> And(this IObservableList>> sources) where TObject : notnull @@ -231,7 +230,7 @@ public static IObservable> And(this IOb /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> And(this IObservableList> sources) where TObject : notnull @@ -248,7 +247,7 @@ public static IObservable> And(this IOb /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> And(this IObservableList> sources) where TObject : notnull @@ -260,13 +259,14 @@ public static IObservable> And(this IOb } /// - /// Converts the source to an read only observable cache. + /// Wraps an in a read-only facade, hiding the mutable API. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable cache. - /// source. + /// The to operate on. + /// A read-only . + /// is . + /// public static IObservableCache AsObservableCache(this IObservableCache source) where TObject : notnull where TKey : notnull @@ -277,14 +277,24 @@ public static IObservableCache AsObservableCache(t } /// - /// Converts the source to a readonly observable cache. + /// Materializes a changeset stream into a queryable, read-only . + /// The cache subscribes to the source on first access and maintains a live snapshot of all items. /// /// The type of the object. /// The type of the key. - /// The source. - /// if set to true all methods are synchronised. There is no need to apply locking when the consumer can be sure the read / write operations are already synchronised. - /// An observable cache. - /// source. + /// The source to materialize into a read-only cache. + /// If (default), all cache operations are synchronized. Set to when the caller guarantees single-threaded access. + /// A read-only observable cache that reflects the current state of the pipeline. + /// + /// + /// Disposing the returned cache unsubscribes from the source stream. The cache's Connect() + /// method provides a changeset stream of its own, which re-emits the current state on each new subscriber. + /// + /// When is , a is used internally. + /// + /// is . + /// + /// public static IObservableCache AsObservableCache(this IObservable> source, bool applyLocking = true) where TObject : notnull where TKey : notnull @@ -302,34 +312,48 @@ public static IObservableCache AsObservableCache(t #if SUPPORTS_ASYNC_DISPOSABLE /// /// - /// Automatically disposes items within the source collection, upon removal of the collection or teardown of the operator. - /// - /// - /// Individual items are disposed after removal or replacement changes have been sent downstream. - /// All items previously-published on the stream are disposed after the stream finalizes. - /// This includes both upstream completion or failure, or downstream un-subscription. + /// Disposes items implementing or when they are removed or replaced, + /// and disposes all tracked items when the stream completes, errors, or the subscription is disposed. /// /// - /// Disposal is supported for both and items. - /// Items implementing neither of these interfaces are unaffected by this operator. + /// Individual items are disposed after the changeset has been forwarded downstream, so downstream operators + /// see the removal before disposal occurs. Items implementing neither disposal interface are ignored. /// /// - /// The type of items in the source collection. - /// The type of key values used to uniquely identify items in the source collection. - /// A stream of changes from the source collection. + /// The type of items in the cache. + /// The type of the key. + /// The source to track for async disposal on removal. /// /// - /// An action to be invoked upon each subscription to this operator, allowing the consumer access to the "disposalsCompleted" stream for that subscription. + /// Invoked once per subscription, providing an that signals when all + /// calls have finished. The signal emits a single value + /// and then completes. + /// + /// + /// This is delivered on a separate channel from the main changeset stream so it can be observed even + /// if the source stream errors. /// + /// + /// A stream that forwards all changesets from unchanged. + /// /// - /// The "disposalsCompleted" stream allows the consumer to properly observe the asynchronous disposal of any items that are disposed by the operator. This stream will emit a single value, and then complete, upon successfull completion of all invocations performed by the operator. + /// Change reason handling: + /// + /// EventBehavior + /// AddTracks the item. No disposal. + /// UpdateDisposes the previous value (if it differs by reference from the current). Tracks the new value. + /// RemoveDisposes the removed item. + /// RefreshPassed through. No disposal. + /// /// /// - /// Providing these notifications within a downstream channel separate from the main collection change stream ensures that these notifications can be observed even in the event of a failure within the operator, or within stream. + /// On stream completion, error, or subscription disposal, all items still in the cache are disposed. + /// items are disposed synchronously; items + /// are dispatched via the signal. /// - /// - /// A stream containing copies of all changes observed from . - /// Throws for and . + /// + /// or is . + /// public static IObservable> AsyncDisposeMany( this IObservable> source, Action> disposalsCompletedAccessor) @@ -345,11 +369,12 @@ public static IObservable> AsyncDisposeMany /// The object of the change set. /// The key of the change set. - /// The source observable. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements have successive property changes. - /// When observing on multiple property changes, apply a throttle to prevent excessive refresh invocations. - /// The scheduler. + /// The source to monitor for property-driven refresh signals. + /// An optional buffer duration. Batches multiple refresh signals into a single changeset, improving performance when many elements change in quick succession. This greatly increases performance when many elements have successive property changes. + /// An optional throttle applied to each item's property change notifications, preventing excessive refresh invocations. + /// An optional for scheduling work. /// An observable change set with additional refresh changes. + /// public static IObservable> AutoRefresh(this IObservable> source, TimeSpan? changeSetBuffer = null, TimeSpan? propertyChangeThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged where TKey : notnull @@ -376,11 +401,11 @@ public static IObservable> AutoRefresh( /// The object of the change set. /// The key of the change set. /// The type of the property. - /// The source observable. - /// Specify a property to observe changes. When it changes a Refresh is invoked. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements have successive property changes. - /// When observing on multiple property changes, apply a throttle to prevent excessive refresh invocations. - /// The scheduler. + /// The source to monitor for property-driven refresh signals. + /// A that specify a property to observe changes. When it changes a Refresh is invoked. + /// An optional buffer duration. Batches multiple refresh signals into a single changeset, improving performance when many elements change in quick succession. This greatly increases performance when many elements have successive property changes. + /// An optional throttle applied to each item's property change notifications, preventing excessive refresh invocations. + /// An optional for scheduling work. /// An observable change set with additional refresh changes. public static IObservable> AutoRefresh(this IObservable> source, Expression> propertyAccessor, TimeSpan? changeSetBuffer = null, TimeSpan? propertyChangeThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged @@ -408,11 +433,12 @@ public static IObservable> AutoRefreshThe object of the change set. /// The key of the change set. /// The type of evaluation. - /// The source observable change set. - /// An observable which acts on items within the collection and produces a value when the item should be refreshed. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements require a refresh. - /// The scheduler. + /// The source to monitor for observable-driven refresh signals. + /// The observable which acts on items within the collection and produces a value when the item should be refreshed. + /// An optional buffer duration. Batches multiple refresh signals into a single changeset, improving performance when many elements change in quick succession. This greatly increases performance when many elements require a refresh. + /// An optional for scheduling work. /// An observable change set with additional refresh changes. + /// public static IObservable> AutoRefreshOnObservable(this IObservable> source, Func> reevaluator, TimeSpan? changeSetBuffer = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => source.AutoRefreshOnObservable((t, _) => reevaluator(t), changeSetBuffer, scheduler); @@ -423,11 +449,14 @@ public static IObservable> AutoRefreshOnObservableThe object of the change set. /// The key of the change set. /// The type of evaluation. - /// The source observable change set. - /// An observable which acts on items within the collection and produces a value when the item should be refreshed. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements require a refresh. - /// The scheduler. + /// The source to monitor for observable-driven refresh signals. + /// The observable which acts on items within the collection and produces a value when the item should be refreshed. + /// An optional buffer duration. Batches multiple refresh signals into a single changeset, improving performance when many elements change in quick succession. This greatly increases performance when many elements require a refresh. + /// An optional for scheduling work. /// An observable change set with additional refresh changes. + /// + /// Worth noting: Per-item observable errors are silently ignored (not forwarded to the downstream observer). Only source stream errors propagate. + /// public static IObservable> AutoRefreshOnObservable(this IObservable> source, Func> reevaluator, TimeSpan? changeSetBuffer = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -439,17 +468,34 @@ public static IObservable> AutoRefreshOnObservable - /// Batches the updates for the specified time period. + /// Collects changesets emitted within a time window and merges them into a single changeset. + /// Uses Rx's Buffer operator followed by . /// /// The type of the object. /// The type of the key. - /// The source. - /// The time span. - /// The scheduler. - /// An observable which emits change sets. - /// source - /// or - /// scheduler. + /// The source to batch. + /// The time window for batching. + /// The scheduler for timing. Defaults to . + /// An observable that emits merged changesets, one per time window. + /// + /// + /// All changesets received during the time window are concatenated into a single changeset. + /// This is useful for reducing UI update frequency when the source emits many rapid changes. + /// + /// + /// EventBehavior + /// AddBuffered and included in the merged changeset at the end of the time window. + /// UpdateBuffered and included in the merged changeset. + /// RemoveBuffered and included in the merged changeset. + /// RefreshBuffered and included in the merged changeset. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedAny remaining buffered changes are flushed, then completion is forwarded. + /// + /// Worth noting: The merged changeset may contain contradictory changes (e.g., Add then Remove for the same key). Downstream operators handle this correctly, but raw inspection of the changeset may be surprising. + /// + /// is . + /// + /// public static IObservable> Batch(this IObservable> source, TimeSpan timeSpan, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -459,66 +505,55 @@ public static IObservable> Batch(this I return source.Buffer(timeSpan, scheduler ?? GlobalConfig.DefaultScheduler).FlattenBufferResult(); } - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// The scheduler. - /// An observable which emits change sets. - /// source. + /// + /// This overload delegates to the primary overload with initialPauseState: false. public static IObservable> BatchIf(this IObservable> source, IObservable pauseIfTrueSelector, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => BatchIf(source, pauseIfTrueSelector, false, scheduler); - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// if set to true [initial pause state]. - /// The scheduler. - /// An observable which emits change sets. - /// source. + /// + /// This overload delegates to the primary overload with default initialPauseState: false. public static IObservable> BatchIf(this IObservable> source, IObservable pauseIfTrueSelector, bool initialPauseState = false, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => new BatchIf(source, pauseIfTrueSelector, null, initialPauseState, scheduler: scheduler).Run(); - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// Specify a time to ensure the buffer window does not stay open for too long. On completion buffering will cease. - /// The scheduler. - /// An observable which emits change sets. - /// source. + /// + /// This overload omits initialPauseState (defaults to ) but accepts a timeout. public static IObservable> BatchIf(this IObservable> source, IObservable pauseIfTrueSelector, TimeSpan? timeOut = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => BatchIf(source, pauseIfTrueSelector, false, timeOut, scheduler); /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. + /// Conditionally buffers changesets while a pause signal is active, then flushes all buffered + /// changes as a single merged changeset when the signal resumes. /// /// The type of the object. /// The type of the key. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// if set to true [initial pause state]. - /// Specify a time to ensure the buffer window does not stay open for too long. On completion buffering will cease. - /// The scheduler. - /// An observable which emits change sets. - /// source. + /// The source to conditionally buffer. + /// An that when , buffering begins. When , the buffer is flushed. + /// If , starts in a paused (buffering) state. + /// A that maximum time the buffer stays open. When elapsed, the buffer is flushed regardless of pause state. + /// The for timeout timing. + /// An observable that emits changesets, buffered or passthrough depending on pause state. + /// + /// + /// While paused, incoming changesets are accumulated. On resume (or timeout), all buffered changesets + /// are merged into a single changeset and emitted. While not paused, changesets pass through immediately. + /// + /// + /// EventBehavior + /// AddBuffered while paused; forwarded immediately while active. + /// UpdateBuffered while paused; forwarded immediately while active. + /// RemoveBuffered while paused; forwarded immediately while active. + /// RefreshBuffered while paused; forwarded immediately while active. + /// OnErrorForwarded to the downstream observer. Buffered data is lost. + /// OnCompletedForwarded. Any remaining buffered data is flushed before completion. + /// + /// Worth noting: If the source completes while paused, buffered data IS flushed before OnCompleted. However, if the source errors while paused, buffered data is lost. + /// + /// or is . + /// + /// public static IObservable> BatchIf(this IObservable> source, IObservable pauseIfTrueSelector, bool initialPauseState = false, TimeSpan? timeOut = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -529,19 +564,13 @@ public static IObservable> BatchIf(this return new BatchIf(source, pauseIfTrueSelector, timeOut, initialPauseState, scheduler: scheduler).Run(); } - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// if set to true [initial pause state]. - /// Specify a time observable. The buffer will be emptied each time the timer produces a value and when it completes. On completion buffering will cease. - /// The scheduler. - /// An observable which emits change sets. - /// source. + /// + /// The source to conditionally buffer. + /// An that controls buffering: begins buffering, flushes the buffer. + /// If , starts in a paused (buffering) state. + /// An optional timer. The buffer is flushed each time the timer produces a value, and buffering ceases when it completes. + /// An optional for scheduling work. + /// This overload accepts an explicit timer observable instead of a timeout. public static IObservable> BatchIf(this IObservable> source, IObservable pauseIfTrueSelector, bool initialPauseState = false, IObservable? timer = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => new BatchIf(source, pauseIfTrueSelector, null, initialPauseState, timer, scheduler).Run(); @@ -551,11 +580,12 @@ public static IObservable> BatchIf(this /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. + /// The source to bind to a collection. + /// The that will receive the changes. /// The number of changes before a reset notification is triggered. /// An observable which will emit change sets. /// source. + /// public static IObservable> Bind(this IObservable> source, IObservableCollection destination, int refreshThreshold = BindingOptions.DefaultResetThreshold) where TObject : notnull where TKey : notnull @@ -578,9 +608,9 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. - /// The binding options. + /// The source to bind to a collection. + /// The that will receive the changes. + /// The that controls binding behavior. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, IObservableCollection destination, BindingOptions options) @@ -597,9 +627,9 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. - /// The updater. + /// The source to bind to a collection. + /// The that will receive the changes. + /// The that applies changes to the bound collection. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, IObservableCollection destination, IObservableCollectionAdaptor updater) @@ -628,9 +658,9 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// The binding options. + /// The source to bind to a collection. + /// The output that will be populated with the results. + /// The that controls binding behavior. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, BindingOptions options) @@ -649,11 +679,11 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. + /// The source to bind to a collection. + /// The output that will be populated with the results. /// The number of changes before a reset notification is triggered. - /// Use replace instead of remove / add for updates. NB: Some platforms to not support replace notifications for binding. - /// Specify an adaptor to change the algorithm to update the target collection. + /// When , uses Replace instead of Remove/Add for updates in the bound collection. Not all platforms support replace notifications. + /// An optional that controls how the target collection is updated. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, int resetThreshold = BindingOptions.DefaultResetThreshold, bool useReplaceForUpdates = BindingOptions.DefaultUseReplaceForUpdates, IObservableCollectionAdaptor? adaptor = null) @@ -685,8 +715,8 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. + /// The source to bind to a collection. + /// The that will receive the changes. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, IObservableCollection destination) @@ -704,9 +734,9 @@ public static IObservable> Bind(t /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. - /// The binding options. + /// The source to bind to a collection. + /// The that will receive the changes. + /// The that controls binding behavior. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, IObservableCollection destination, BindingOptions options) @@ -725,9 +755,9 @@ public static IObservable> Bind(t /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. - /// The updater. + /// The source to bind to a collection. + /// The that will receive the changes. + /// The that applies changes to the bound collection. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, IObservableCollection destination, ISortedObservableCollectionAdaptor updater) @@ -756,9 +786,9 @@ public static IObservable> Bind(t /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. - /// The binding options. + /// The source to bind to a collection. + /// The output that will be populated with the results. + /// The that controls binding behavior. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, BindingOptions options) @@ -779,11 +809,11 @@ public static IObservable> Bind(this IO /// /// The type of the object. /// The type of the key. - /// The source. - /// The resulting read only observable collection. + /// The source to bind to a collection. + /// The output that will be populated with the results. /// The number of changes before a reset event is called on the observable collection. - /// Use replace instead of remove / add for updates. NB: Some platforms to not support replace notifications for binding. - /// Specify an adaptor to change the algorithm to update the target collection. + /// When , uses Replace instead of Remove/Add for updates in the bound collection. Not all platforms support replace notifications. + /// An that specify an adaptor to change the algorithm to update the target collection. /// An observable which will emit change sets. /// source. public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, int resetThreshold = BindingOptions.DefaultResetThreshold, bool useReplaceForUpdates = BindingOptions.DefaultUseReplaceForUpdates, ISortedObservableCollectionAdaptor? adaptor = null) @@ -813,8 +843,8 @@ public static IObservable> Bind(this IO /// /// The object type. /// The key type. - /// The source. - /// The target binding list. + /// The source to bind to a collection. + /// The that will receive the changes. /// The reset threshold. /// An observable which will emit change sets. /// @@ -837,8 +867,8 @@ public static IObservable> Bind(this IO /// /// The object type. /// The key type. - /// The source. - /// The target binding list. + /// The source to bind to a collection. + /// The that will receive the changes. /// The reset threshold. /// An observable which will emit change sets. /// @@ -859,14 +889,24 @@ public static IObservable> Bind(this IO #endif /// - /// Buffers changes for an initial period only. After the period has elapsed, not further buffering occurs. + /// Buffers the initial burst of changesets for the specified duration, merges them into a single + /// changeset, then passes all subsequent changesets through without buffering. /// /// The object type. /// The type of the key. - /// The source change set. - /// The period to buffer, measure from the time that the first item arrives. - /// The scheduler to buffer on. - /// An observable which emits change sets. + /// The source to buffer during the initial loading period. + /// The time window to buffer, measured from when the first changeset arrives. + /// The scheduler for timing. Defaults to . + /// An observable that emits one merged changeset for the initial burst, then passthrough for the rest. + /// + /// + /// Useful for aggregating the initial snapshot (which may arrive as many small changesets) into a + /// single changeset for efficient downstream processing, while leaving subsequent live updates untouched. + /// + /// Internally uses , Rx Buffer, and . + /// + /// + /// public static IObservable> BufferInitial(this IObservable> source, TimeSpan initialBuffer, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull => source.DeferUntilLoaded().Publish( @@ -878,15 +918,28 @@ public static IObservable> BufferInitial - /// Cast the object to the specified type. - /// Alas, I had to add the converter due to type inference issues. + /// Casts each item in the changeset to a new type using the provided converter function. + /// Equivalent to + /// but named for discoverability when a simple type cast or conversion is needed. /// - /// The type of the object. + /// The type of the source object. /// The type of the key. - /// The type of the destination. - /// The source. - /// The conversion factory. - /// An observable which emits change sets. + /// The type of the destination object. + /// The source to cast. + /// The conversion function applied to each item. + /// An observable changeset of converted items. + /// + /// + /// EventBehavior + /// AddCalls and emits an Add with the converted item. + /// UpdateCalls on the new value and emits an Update. + /// RemoveEmits a Remove. The converter is not called. + /// RefreshForwarded as Refresh. The converter is not called. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// public static IObservable> Cast(this IObservable> source, Func converter) where TSource : notnull where TKey : notnull @@ -898,14 +951,27 @@ public static IObservable> Cast - /// Changes the primary key. + /// Re-keys each item in the changeset by applying to the current item. + /// The original change reason is preserved; only the key is remapped. /// /// The type of the object. /// The type of the source key. /// The type of the destination key. - /// The source. - /// The key selector eg. (item) => newKey. - /// An observable which emits change sets. + /// The source to re-key. + /// The that computes the destination key from the item, e.g. (item) => item.NewId. + /// An observable changeset with items re-keyed using . + /// + /// + /// EventBehavior + /// Add is called on the item. An Add is emitted with the destination key. + /// Update is called on the current item. An Update is emitted with the destination key. If the key selector produces a different destination key for the updated value than it did for the original value, downstream consumers will see an Update for a key that may not match the original Add. + /// Remove is called on the item. A Remove is emitted with the destination key. + /// Refresh is called on the item. A Refresh is emitted with the destination key. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// public static IObservable> ChangeKey(this IObservable> source, Func keySelector) where TObject : notnull where TSourceKey : notnull @@ -922,16 +988,11 @@ public static IObservable> ChangeKey - /// Changes the primary key. - /// - /// The type of the object. - /// The type of the source key. - /// The type of the destination key. - /// The source. - /// The key selector eg. (key, item) => newKey. - /// An observable which emits change sets. - /// source. + /// + /// + /// This overload also provides the source key to , + /// allowing the destination key to be derived from both the item and its original key. + /// public static IObservable> ChangeKey(this IObservable> source, Func keySelector) where TObject : notnull where TSourceKey : notnull @@ -949,12 +1010,21 @@ public static IObservable> ChangeKey - /// Clears all data. + /// Removes all items from the cache, producing a changeset with a Remove for every item. /// /// The type of the object. /// The type of the key. - /// The source. - /// source. + /// The to clear. + /// + /// + /// EventBehavior + /// AddNot produced by this operation. + /// UpdateNot produced by this operation. + /// RemoveA Remove is emitted for every item currently in the cache. + /// RefreshNot produced by this operation. + /// + /// + /// is . public static void Clear(this ISourceCache source) where TObject : notnull where TKey : notnull @@ -964,13 +1034,7 @@ public static void Clear(this ISourceCache source) source.Edit(updater => updater.Clear()); } - /// - /// Clears all items from the cache. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// source. + /// public static void Clear(this IIntermediateCache source) where TObject : notnull where TKey : notnull @@ -980,13 +1044,7 @@ public static void Clear(this IIntermediateCache s source.Edit(updater => updater.Clear()); } - /// - /// Clears all data. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// source. + /// public static void Clear(this LockFreeObservableCache source) where TObject : notnull where TKey : notnull @@ -996,13 +1054,25 @@ public static void Clear(this LockFreeObservableCache - /// Clones the changes into the specified collection. + /// Applies each change from the source changeset to the specified collection as a side effect. + /// The changeset is forwarded downstream unchanged. /// /// The type of the object. /// The type of the key. - /// The source. - /// The target. - /// An observable which emits change sets. + /// The source to clone. + /// The target collection to which changes are applied. + /// An observable that forwards all changesets from unchanged. + /// + /// + /// EventBehavior + /// AddThe item is added to . Forwarded as Add. + /// UpdateThe previous item is removed from and the current item is added. Forwarded as Update. + /// RemoveThe item is removed from . Forwarded as Remove. + /// RefreshIgnored ( has no concept of refresh). Forwarded as Refresh. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// public static IObservable> Clone(this IObservable> source, ICollection target) where TObject : notnull where TKey : notnull @@ -1041,14 +1111,13 @@ public static IObservable> Clone(this I } /// - /// Convert the object using the specified conversion function. - /// This is a lighter equivalent of Transform and is designed to be used with non-disposable objects. + /// Obsolete: use instead. /// /// The type of the object. /// The type of the key. /// The type of the destination. - /// The source. - /// The conversion factory. + /// The source to convert. + /// The conversion factory. /// An observable which emits change sets. [Obsolete("This was an experiment that did not work. Use Transform instead")] public static IObservable> Convert(this IObservable> source, Func conversionFactory) @@ -1068,12 +1137,26 @@ public static IObservable> Convert - /// Defer the subscription until the stream has been inflated with data. + /// Suppresses all emissions until the first non-empty changeset arrives, then replays that changeset and all subsequent ones. + /// If the source never produces a non-empty changeset, the stream waits indefinitely. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change sets. + /// The source to defer until the first changeset arrives. + /// An observable that begins emitting changesets once the first non-empty changeset is received. + /// + /// + /// EventBehavior + /// AddForwarded as Add once the initial non-empty changeset has been received. + /// UpdateForwarded as Update once loaded. + /// RemoveForwarded as Remove once loaded. + /// RefreshForwarded as Refresh once loaded. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: Blocks indefinitely if the cache or stream never receives any data. Ensure the source will eventually emit at least one changeset. + /// + /// public static IObservable> DeferUntilLoaded(this IObservable> source) where TObject : notnull where TKey : notnull @@ -1083,13 +1166,7 @@ public static IObservable> DeferUntilLoaded(source).Run(); } - /// - /// Defer the subscription until the stream has been inflated with data. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// An observable which emits change sets. + /// public static IObservable> DeferUntilLoaded(this IObservableCache source) where TObject : notnull where TKey : notnull @@ -1100,17 +1177,40 @@ public static IObservable> DeferUntilLoaded - /// Disposes each item when no longer required. /// - /// Individual items are disposed after removal or replacement changes have been sent downstream. - /// All items previously-published on the stream are disposed after the stream finalizes. + /// Disposes items implementing when they are removed or replaced, + /// and disposes all tracked items when the stream completes, errors, or the subscription is disposed. + /// + /// + /// Individual items are disposed after the changeset has been forwarded downstream, so downstream operators + /// see the removal before disposal occurs. Items that do not implement are ignored. /// /// /// The type of the object. /// The type of the key. - /// The source. - /// A continuation of the original stream. - /// source. + /// The source to track for disposal on removal. + /// A stream that forwards all changesets from unchanged. + /// + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddTracks the item. No disposal. + /// UpdateDisposes the previous value (if it differs by reference from the current). Tracks the new value. + /// RemoveDisposes the removed item. + /// RefreshPassed through. No disposal. + /// + /// + /// + /// On stream completion, error, or subscription disposal, all remaining tracked items are disposed. + /// All disposal is synchronous via . + /// For items that implement , use instead. + /// + /// + /// is . + /// + /// + /// public static IObservable> DisposeMany(this IObservable> source) where TObject : notnull where TKey : notnull @@ -1126,13 +1226,15 @@ public static IObservable> DisposeMany( /// The type object from which the distinct values are selected. /// The type of the key. /// The type of the value. - /// The source. - /// The value selector. + /// The source to extract distinct values. + /// The value selector. /// An observable which will emit distinct change sets. /// /// Due to it's nature only adds or removes can be returned. + /// Worth noting: Reference counting assumes value equality is transitive. Mutable value objects with inconsistent Equals implementations can corrupt ref counts. /// /// source. + /// public static IObservable> DistinctValues(this IObservable> source, Func valueSelector) where TObject : notnull where TKey : notnull @@ -1144,16 +1246,14 @@ public static IObservable> DistinctValues>(observer => new DistinctCalculator(source, valueSelector).Run().SubscribeSafe(observer)); } - /// - /// Loads the cache with the specified items in an optimised manner i.e. calculates the differences between the old and new items - /// in the list and amends only the differences. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The items to add, update or delete. - /// The equality comparer used to determine whether a new item is the same as an existing cached item. - /// source. + /// + /// The to diff and update. + /// The representing the complete desired state to diff against the cache. + /// An used to determine whether a new item is the same as an existing cached item. + /// + /// This overload uses an instead of a delegate + /// to determine item equality. + /// public static void EditDiff(this ISourceCache source, IEnumerable allItems, IEqualityComparer equalityComparer) where TObject : notnull where TKey : notnull @@ -1166,15 +1266,24 @@ public static void EditDiff(this ISourceCache sour } /// - /// Loads the cache with the specified items in an optimised manner i.e. calculates the differences between the old and new items - /// in the list and amends only the differences. + /// Diffs a complete snapshot of items against the current cache contents, producing the minimal set of + /// Add, Update, and Remove changes needed to bring the cache in sync with the snapshot. /// /// The type of the object. /// The type of the key. - /// The source. - /// The items to compare and add, update or delete. - /// Expression to determine whether an item's value is equal to the old value (current, previous) => current.Version == previous.Version. - /// source. + /// The to diff and update. + /// The representing the complete desired state. + /// The that returns when the current and previous items are considered equal, e.g. (current, previous) => current.Version == previous.Version. + /// + /// + /// EventBehavior + /// AddItems in whose key is not in the cache produce an Add. + /// UpdateItems present in both and the cache that differ (per ) produce an Update. + /// RemoveItems in the cache whose key is not in produce a Remove. + /// RefreshNot produced by this operation. + /// + /// + /// , , or is . public static void EditDiff(this ISourceCache source, IEnumerable allItems, Func areItemsEqual) where TObject : notnull where TKey : notnull @@ -1188,15 +1297,29 @@ public static void EditDiff(this ISourceCache sour } /// - /// Converts an Observable of Enumerable to an Observable ChangeSet that updates when the enumerables changes. Counterpart operator to . + /// Converts an of into a changeset stream by diffing each + /// emission against the previous one. Each emission replaces the entire dataset. + /// Counterpart to . /// /// The type of the object. /// The type of the key. - /// The source. - /// Key Selection Function for the ChangeSet. - /// Optional instance to use for comparing values. - /// An observable cache. - /// source. + /// The source to convert into a keyed changeset stream. + /// The that extracts the unique key from each item. + /// An optional for comparing items. Uses default equality if . + /// An observable changeset representing the incremental differences between successive snapshots. + /// + /// + /// EventBehavior + /// AddItems in the new snapshot whose key was not in the previous snapshot produce an Add. + /// UpdateItems present in both snapshots that differ (per ) produce an Update. + /// RemoveItems in the previous snapshot whose key is absent from the new snapshot produce a Remove. + /// RefreshNot produced by this operator. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// or is . + /// public static IObservable> EditDiff(this IObservable> source, Func keySelector, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -1208,15 +1331,27 @@ public static IObservable> EditDiff(thi } /// - /// Converts an Observable Optional to an Observable ChangeSet that adds/removes/updates as the optional changes. + /// Converts an of into a changeset stream that tracks + /// a single item: Some produces an Add or Update, and None produces a Remove. /// /// The type of the object. /// The type of the key. - /// The source. - /// Key Selection Function for the ChangeSet. - /// Optional instance to use for comparing values. - /// An observable changeset. - /// source. + /// The source to convert into a keyed changeset stream. + /// The that extracts the unique key from each item. + /// An optional for comparing items. Uses default equality if . + /// An observable changeset tracking the single optional item. + /// + /// + /// EventBehavior + /// AddEmitted when the source produces Some(value) and no item was previously tracked. + /// UpdateEmitted when the source produces Some(value) and an item was already tracked with a different value (per ). + /// RemoveEmitted when the source produces None and an item was previously tracked. + /// RefreshNot produced by this operator. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// or is . public static IObservable> EditDiff(this IObservable> source, Func keySelector, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -1228,12 +1363,24 @@ public static IObservable> EditDiff(thi } /// - /// Ensures there are no duplicated keys in the observable changeset. + /// Validates that each changeset contains no duplicate keys. + /// If duplicates are detected, an is emitted via OnError. /// - /// The source change set. /// The type of the object. /// The type of the key. - /// A changeset which guarantees a key is only present at most once in the changeset. + /// The source to validate for unique keys. + /// A changeset stream guaranteed to contain unique keys per changeset. + /// + /// + /// EventBehavior + /// AddForwarded as Add if the key is unique within the changeset. + /// UpdateForwarded as Update if the key is unique within the changeset. + /// RemoveForwarded as Remove if the key is unique within the changeset. + /// RefreshForwarded as Refresh if the key is unique within the changeset. + /// OnErrorForwarded. Also emitted with if duplicate keys are detected in a changeset. + /// OnCompletedForwarded to the downstream observer. + /// + /// public static IObservable> EnsureUniqueKeys(this IObservable> source) where TObject : notnull where TKey : notnull @@ -1249,14 +1396,15 @@ public static IObservable> EnsureUniqueKeys /// The type of the object. /// The type of the key. - /// The source. - /// The others. + /// The source to combine. + /// The additional streams to combine with. /// An observable which emits change sets. /// /// source /// or /// others. /// + /// public static IObservable> Except(this IObservable> source, params IObservable>[] others) where TObject : notnull where TKey : notnull @@ -1277,7 +1425,7 @@ public static IObservable> Except(this /// /// The type of the object. /// The type of the key. - /// The sources. + /// The of streams to combine. /// An observable which emits change sets. /// /// source @@ -1299,7 +1447,7 @@ public static IObservable> Except(this /// /// The type of the object. /// The type of the key. - /// The source. + /// The of streams to combine. /// An observable which emits change sets. public static IObservable> Except(this IObservableList>> sources) where TObject : notnull @@ -1316,7 +1464,7 @@ public static IObservable> Except(this /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> Except(this IObservableList> sources) where TObject : notnull @@ -1333,7 +1481,7 @@ public static IObservable> Except(this /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> Except(this IObservableList> sources) where TObject : notnull @@ -1345,19 +1493,28 @@ public static IObservable> Except(this } /// - /// Automatically removes items from the stream after the time specified by - /// the timeSelector elapses. Return null if the item should never be removed. + /// Schedules automatic removal of items after the timeout returned by . + /// If returns , the item never expires. /// /// The type of the object. /// The type of the key. - /// The source. - /// The time selector. - /// An observable which emits change sets. - /// - /// source - /// or - /// timeSelector. - /// + /// The source to apply time-based expiration to. + /// An optional that returns the expiration timeout for each item, or for no expiration. + /// An observable changeset that includes timer-driven Remove changes for expired items. + /// + /// When a timer fires, a Remove is emitted for the expired item. + /// + /// EventBehavior + /// AddSchedules a removal timer based on . Forwarded as Add. + /// UpdateResets the removal timer for the item. Forwarded as Update. + /// RemoveCancels the removal timer. Forwarded as Remove. + /// RefreshForwarded as Refresh. No timer change. + /// OnErrorForwarded. All pending timers are cancelled. + /// OnCompletedForwarded. All pending timers are cancelled. + /// + /// Worth noting: A return from means "never expire". Update changes reset the expiration timer. + /// + /// or is . public static IObservable> ExpireAfter( this IObservable> source, Func timeSelector) @@ -1367,21 +1524,10 @@ public static IObservable> ExpireAfter( source: source, timeSelector: timeSelector); - /// - /// Automatically removes items from the stream after the time specified by - /// the timeSelector elapses. Return null if the item should never be removed. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The time selector. - /// The scheduler. - /// An observable which emits change sets. - /// - /// source - /// or - /// timeSelector. - /// + /// + /// The source to apply time-based expiration to. + /// An optional that returns the expiration timeout for each item, or for no expiration. + /// The used to schedule expiration timers. public static IObservable> ExpireAfter( this IObservable> source, Func timeSelector, @@ -1393,21 +1539,14 @@ public static IObservable> ExpireAfter( timeSelector: timeSelector, scheduler: scheduler); - /// - /// Automatically removes items from the stream on the next poll after the time specified by - /// the time selector elapses. - /// - /// The type of the object. - /// The type of the key. - /// The cache. - /// The time selector. Return null if the item should never be removed. - /// The polling interval. if this value is specified, items are expired on an interval. - /// This will result in a loss of accuracy of the time which the item is expired but is less computationally expensive. - /// - /// An observable of enumerable of the key values which has been removed. - /// source - /// or - /// timeSelector. + /// + /// The source to apply time-based expiration to. + /// An optional that returns the expiration timeout for each item, or for no expiration. + /// An optional polling interval. If specified, items are expired on a polling interval rather than per-item timers. Less accurate but more efficient when many items share similar expiration times. + /// + /// This overload uses periodic polling instead of per-item timers. Expired items are removed on the next + /// poll after their timeout elapses, which trades accuracy for reduced timer overhead. + /// public static IObservable> ExpireAfter( this IObservable> source, Func timeSelector, @@ -1419,22 +1558,11 @@ public static IObservable> ExpireAfter( timeSelector: timeSelector, pollingInterval: pollingInterval); - /// - /// Automatically removes items from the stream on the next poll after the time specified by - /// the time selector elapses. - /// - /// The type of the object. - /// The type of the key. - /// The cache. - /// The time selector. Return null if the item should never be removed. - /// The polling interval. if this value is specified, items are expired on an interval. - /// This will result in a loss of accuracy of the time which the item is expired but is less computationally expensive. - /// - /// The scheduler. - /// An observable of enumerable of the key values which has been removed. - /// source - /// or - /// timeSelector. + /// + /// The source to apply time-based expiration to. + /// An optional that returns the expiration timeout for each item, or for no expiration. + /// An optional if specified, items are expired on a polling interval rather than per-item timers. + /// The used to schedule polling and expiration timers. public static IObservable> ExpireAfter( this IObservable> source, Func timeSelector, @@ -1449,21 +1577,22 @@ public static IObservable> ExpireAfter( scheduler: scheduler); /// - /// Automatically removes items from the cache after the time specified by - /// the time selector elapses. + /// Automatically removes items from the after the timeout returned + /// by . Returns an observable of the removed key-value pairs (not a changeset stream). /// /// The type of the object. /// The type of the key. - /// The cache. - /// The time selector. Return null if the item should never be removed. - /// A polling interval. Since multiple timer subscriptions can be expensive, - /// it may be worth setting the interval. - /// - /// The scheduler. - /// An observable of enumerable of the key values which has been removed. - /// source - /// or - /// timeSelector. + /// The to operate on. + /// An optional that returns the expiration timeout for each item, or for no expiration. + /// An optional if specified, items are expired on a polling interval rather than per-item timers. + /// The scheduler used to schedule expiration timers. Defaults to if . + /// An observable that emits the key-value pairs of items removed from the cache by expiration. + /// + /// Unlike the stream-based overloads, this operates directly on the + /// and returns the removed items as collections, + /// not as a changeset stream. + /// + /// or is . public static IObservable>> ExpireAfter( this ISourceCache source, Func timeSelector, @@ -1478,14 +1607,30 @@ public static IObservable>> ExpireAfter< scheduler: scheduler); /// - /// Filters the specified source. + /// Filters items from the source changeset stream using a static predicate. + /// Only items that satisfy are included downstream. /// /// The type of the object. /// The type of the key. - /// The source. - /// The filter. - /// By default empty changeset notifications are suppressed for performance reasons. Set to false to publish empty changesets. Doing so can be useful for monitoring loading status. - /// An observable which emits change sets. + /// The source to filter. + /// The predicate used to determine whether each item is included. + /// When (default), empty changesets are suppressed for performance. Set to to emit empty changesets, which can be useful for monitoring loading status. + /// An observable changeset containing only items that satisfy . + /// + /// + /// EventBehavior + /// AddThe predicate is evaluated. If it passes, an Add is emitted. Otherwise the item is dropped. + /// UpdateFour outcomes: if both old and new values pass, an Update is emitted. If only the new value passes, an Add is emitted. If only the old value passed, a Remove is emitted. If neither passes, the change is dropped. + /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. + /// RefreshThe predicate is re-evaluated. If the item now passes but previously did not, an Add is emitted. If it still passes, a Refresh is forwarded. If it no longer passes, a Remove is emitted. If it still fails, the change is dropped. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: Refresh events trigger re-evaluation, which can promote or demote items. Pair with for property-change-driven filtering. + /// + /// + /// + /// public static IObservable> Filter( this IObservable> source, Func filter, @@ -1497,15 +1642,11 @@ public static IObservable> Filter( filter: filter, suppressEmptyChangeSets: suppressEmptyChangeSets); - /// - /// Creates a filtered stream which can be dynamically filtered. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// Observable to change the underlying predicate. - /// By default empty changeset notifications are suppressed for performance reasons. Set to false to publish empty changesets. Doing so can be useful for monitoring loading status. - /// An observable which emits change sets. + /// + /// + /// This overload does not accept a reapplyFilter signal. It is equivalent to calling the + /// full dynamic overload with as the reapply observable. + /// public static IObservable> Filter( this IObservable> source, IObservable> predicateChanged, @@ -1518,19 +1659,34 @@ public static IObservable> Filter( suppressEmptyChangeSets: suppressEmptyChangeSets); /// - /// Creates a filtered stream which can be dynamically filtered, based on state values passed through to a static filtering predicate. + /// Creates a dynamically filtered stream where the filter predicate depends on external state. + /// Each emission from triggers a full re-filtering of all items. /// /// The type of the object. /// The type of the key. /// The type of state value required by . - /// The source. - /// A stream of state values to be passed to . - /// A static predicate to be used to determine which items should be included or excluded by the filter. - /// By default empty changeset notifications are suppressed for performance reasons. Set to false to publish empty changesets. Doing so can be useful for monitoring loading status. - /// An observable which emits change sets. - /// Throws for , , and . + /// The source to filter. + /// The stream of state values to be passed to . + /// The predicate that receives the current state and an item, returning to include or to exclude. + /// When (default), empty changesets are suppressed for performance. Set to to emit empty changesets. + /// An observable changeset containing only items satisfying for the latest state. + /// , , or is . /// - /// Usually, should emit an initial value, immediately upon subscription. This is because cannot be invoked until the first state value is received, and accordingly, the operator will treat all items as excluded until then. Each value emitted by will trigger a full re-filtering of the entire collection. + /// + /// should emit an initial value immediately upon subscription. + /// Until the first state value arrives, no items pass the filter (all items are excluded). + /// Each subsequent state emission triggers a full re-evaluation of every item in the collection. + /// + /// + /// EventBehavior + /// AddEvaluated against the current state. If it passes, an Add is emitted. Otherwise dropped. + /// UpdateRe-evaluated. Four outcomes as with the static overload. + /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. + /// RefreshRe-evaluated against the current state. May produce Add, Refresh, Remove, or be dropped. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: should emit an initial value immediately. Each emission triggers a full re-evaluation of all items, which can be expensive for large collections. /// public static IObservable> Filter( this IObservable> source, @@ -1546,16 +1702,17 @@ public static IObservable> Filter(), suppressEmptyChangeSets: suppressEmptyChangeSets); - /// - /// Creates a filtered stream which can be dynamically filtered. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// Observable to change the underlying predicate. - /// Observable to re-evaluate whether the filter still matches items. Use when filtering on mutable values. - /// By default empty changeset notifications are suppressed for performance reasons. Set to false to publish empty changesets. Doing so can be useful for monitoring loading status. - /// An observable which emits change sets. + /// + /// The source to filter. + /// The that emits new predicates. Each emission replaces the current predicate and triggers a full re-evaluation of all items. + /// The that, when it emits, triggers a full re-evaluation of all items against the current predicate. Useful when filtering on mutable item properties. + /// When (default), empty changesets are suppressed for performance. + /// + /// In addition to the per-item behavior described in the static overload, + /// emissions from replace the predicate and trigger full re-filtering, + /// while emissions from re-evaluate all items against the current predicate. + /// Worth noting: No items are included until the predicate observable emits its first value. + /// public static IObservable> Filter( this IObservable> source, IObservable> predicateChanged, @@ -1576,8 +1733,8 @@ public static IObservable> Filter( /// /// The type of collection items to be filtered. /// The type of the key values of each collection item. - /// The source stream of collection items to be filtered. - /// The filtering predicate to be applied to each item. + /// The source to filter (items assumed immutable). + /// The filtering predicate to be applied to each item. /// A flag indicating whether the created stream should emit empty changesets. Empty changesets are suppressed by default, for performance. Set to ensure that a downstream changeset occurs for every upstream changeset. /// A stream of collection changesets where upstream collection items are filtered by the given predicate. /// @@ -1591,6 +1748,15 @@ public static IObservable> Filter( /// Your filtering predicate runs quickly, and does not heavily allocate memory /// /// Note that, because filtering is purely deterministic, Refresh operations are transparently ignored by this operator. + /// + /// EventBehavior + /// AddThe predicate is evaluated. If it passes, an Add is emitted. Otherwise the item is dropped. + /// UpdateFour outcomes: if both old and new values pass, an Update is emitted. If only the new value passes, an Add is emitted. If only the old value passed, a Remove is emitted. If neither passes, the change is dropped. + /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. + /// RefreshDropped. Because items are assumed immutable, there is nothing to re-evaluate. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// /// public static IObservable> FilterImmutable( this IObservable> source, @@ -1610,16 +1776,49 @@ public static IObservable> FilterImmutable - /// Filters the stream of changes according to an Observable bool that is created for each item using the specified factory function. + /// Filters items using a per-item that controls inclusion. + /// Each item's observable is created by and toggles the item in or out of the downstream stream. /// /// The type of the object. /// The type of the key. - /// The source. - /// Factory function used to create the observable bool that controls whether that given item passes the filter or not. - /// Optional time to buffer changes from the observable bools. - /// Optional scheduler to use when buffering the changes. - /// An observable changeset that only contains items whose corresponding observable bool has emitted true as its most recent value. - /// One of the given parameters was null. + /// The source to filter using per-item observables. + /// A factory that creates an for each item and its key. When the observable emits , the item is included; when , it is excluded. + /// A that optional time window to buffer inclusion changes from per-item observables before re-evaluating. + /// An that optional scheduler used for buffering. + /// An observable changeset containing only items whose per-item observable most recently emitted . + /// + /// + /// Source changeset handling (parent events): + /// + /// + /// EventBehavior + /// AddSubscribes to the per-item observable. The item is not included downstream until the observable emits its first . + /// UpdateDisposes the old item's observable subscription and subscribes to the new item's observable. Inclusion state is reset; the new observable must emit before the item reappears. + /// RemoveDisposes the item's observable subscription. If the item was included downstream, a Remove is emitted. + /// RefreshForwarded as Refresh if the item is currently included downstream. Otherwise dropped. + /// + /// + /// Per-item observable handling (filter observable events): + /// + /// + /// EmissionBehavior + /// First The item is included: an Add is emitted downstream. + /// (was included)The item is excluded: a Remove is emitted downstream. + /// (was excluded)The item is re-included: an Add is emitted downstream. + /// (was included)No effect (already included). + /// (was excluded)No effect (already excluded). + /// ErrorTerminates the entire output stream. + /// CompletedThe item remains in its current inclusion state. No further toggling is possible for this item. + /// + /// + /// Worth noting: Items are invisible downstream until their per-item observable emits at least one . + /// If an item's observable never emits, the item never appears. The parameter batches + /// rapid inclusion changes from per-item observables into a single re-evaluation, reducing changeset chatter. + /// + /// + /// or is . + /// + /// public static IObservable> FilterOnObservable(this IObservable> source, Func> filterFactory, TimeSpan? buffer = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -1630,17 +1829,10 @@ public static IObservable> FilterOnObservable(source, filterFactory, buffer, scheduler).Run(); } - /// - /// Filters the stream of changes according to an Observable bool that is created for each item using the specified factory function. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// Factory function used to create the observable bool that controls whether that given item passes the filter or not. - /// Optional time to buffer changes from the observable bools. - /// Optional scheduler to use when buffering the changes. - /// An observable changeset that only contains items whose corresponding observable bool has emitted true as its most recent value. - /// One of the given parameters was null. + /// + /// + /// This overload does not provide the key to ; only the item is passed. + /// public static IObservable> FilterOnObservable(this IObservable> source, Func> filterFactory, TimeSpan? buffer = null, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -1652,13 +1844,12 @@ public static IObservable> FilterOnObservable - /// Ensure that finally is always called. Thanks to Lee Campbell for this. + /// Obsolete: do not use. This can cause unhandled exception issues. Use the standard Rx Finally operator instead. /// /// The type contained within the observables. - /// The source. - /// The finally action. + /// The source to attach a finally action to. + /// The to invoke when the subscription terminates. /// An observable which has always a finally action applied. - /// source. [Obsolete("This can cause unhandled exception issues so do not use")] public static IObservable FinallySafe(this IObservable source, Action finallyAction) { @@ -1669,13 +1860,15 @@ public static IObservable FinallySafe(this IObservable source, Action f } /// - /// Flattens an update collection to it's individual items. + /// Unwraps each into individual + /// values via . /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change set values on a flatten result. - /// source. + /// The source to flatten into individual changes. + /// An observable of individual values. + /// is . + /// public static IObservable> Flatten(this IObservable> source) where TObject : notnull where TKey : notnull @@ -1686,12 +1879,14 @@ public static IObservable> Flatten(this IOb } /// - /// Convert the result of a buffer operation to a single change set. + /// Merges a list of changesets (typically from an Rx Buffer operation) into a single changeset + /// by concatenating all changes. Empty buffers are filtered out. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change sets. + /// The source to flatten. + /// An observable changeset combining all changes from each buffer into a single emission. + /// is . public static IObservable> FlattenBufferResult(this IObservable>> source) where TObject : notnull where TKey : notnull @@ -1702,13 +1897,30 @@ public static IObservable> FlattenBufferResult - /// Provides a call back for each change. + /// Invokes for every individual in each changeset, + /// regardless of change reason. The changeset is forwarded downstream unchanged. /// /// The type of the object. /// The type of the key. - /// The source. - /// The action. - /// An observable which will perform the action on each item. + /// The source to observe each individual change in. + /// The action to invoke for each change. Receives the full struct, including , , , and . + /// A stream that forwards all changesets from unchanged. + /// + /// + /// All change reasons (Add, Update, Remove, Refresh) trigger the callback. + /// Use , + /// , + /// , or + /// + /// to target a specific reason. + /// + /// + /// Implemented via Rx's Do operator on the changeset stream. + /// Exceptions thrown in propagate as OnError to the subscriber. No try-catch is applied. + /// + /// + /// or is . + /// public static IObservable> ForEachChange(this IObservable> source, Action> action) where TObject : notnull where TKey : notnull @@ -1719,20 +1931,12 @@ public static IObservable> ForEachChange changes.ForEach(action)); } - /// - /// Joins the left and right observable data sources, taking any left or right values and matching them, provided that the left or the right has a value. - /// This is the equivalent of SQL full join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the optional left and right values into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> FullJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, Optional, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -1749,19 +1953,48 @@ public static IObservable> FullJoin - /// Joins the left and right observable data sources, taking any left or right values and matching them, provided that the left or the right has a value. - /// This is the equivalent of SQL full join. + /// Joins two changeset streams, producing a result for every key that appears on either side (or both). + /// Both sides are because a given key may only exist on one side at any point. + /// Equivalent to SQL FULL OUTER JOIN. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, optional left, and optional right into a destination object. Example: (key, left, right) => new Result(key, left, right). + /// An observable changeset keyed by . + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddEmits with the left value and the matching right (or if no right exists). + /// UpdateRe-invokes with the new left value and current right (if any). + /// RemoveIf a right match still exists, re-invokes the selector with left as . If neither side remains, removes the joined result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddEmits with the matching left (or ) and the right value. + /// UpdateRe-invokes selector with current left (if any) and the new right value. + /// RemoveIf a left match still exists, re-invokes the selector with right as . If neither side remains, removes the joined result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> FullJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, Optional, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -1777,20 +2010,12 @@ public static IObservable> FullJoin(left, right, rightKeySelector, resultSelector).Run(); } - /// - /// Groups the right data source and joins the resulting group to the left data source, matching these using the specified key selector. Results are included when the left or the right has a value. - /// This is the equivalent of SQL full join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the optional left value and the right group into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> FullJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, IGrouping, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -1807,19 +2032,49 @@ public static IObservable> FullJoinMany - /// Groups the right data source and joins the resulting group to the left data source, matching these using the specified key selector. Results are included when the left or the right has a value. - /// This is the equivalent of SQL full join. + /// Groups right-side items by their mapped key, then full-joins each group to the left source. + /// A result is produced for every key that appears on either side (or both). The left value is + /// because only the right side may have entries for a given key. + /// Equivalent to SQL FULL OUTER JOIN with the right side grouped. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, optional left value, and the right group into a destination object. Example: (key, left, group) => new Result(key, left, group). + /// An observable changeset keyed by . + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddEmits with the left value and the current right group for that key (may be empty). + /// UpdateRe-invokes with the new left value and current right group. + /// RemoveIf the right group is non-empty, re-invokes with left as . If both sides are empty, removes the result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddUpdates the right group, then re-invokes selector with the current left (if any) and the updated group. + /// UpdateUpdates the right group and re-invokes selector. + /// RemoveUpdates the right group. If the group becomes empty and no left exists, removes the result. Otherwise re-invokes selector. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> FullJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, IGrouping, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -1836,17 +2091,15 @@ public static IObservable> FullJoinMany - /// Groups the source on the value returned by group selector factory. - /// A group is included for each item in the resulting group source. + /// Groups items from the source changeset, producing groups only for group keys present in . + /// Useful for parent-child relationships where parents and children come from different streams. /// /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector factory. - /// - /// A distinct stream used to determine the result. - /// + /// The source to group. + /// The group selector factory. + /// An of used to determine which groups appear in the result. /// /// Useful for parent-child collection when the parent and child are soured from different streams. /// @@ -1864,14 +2117,38 @@ public static IObservable> Group - /// Groups the source on the value returned by group selector factory. + /// Groups items from the source changeset by a key extracted via . + /// Each group is an observable sub-cache that receives changes for its members. /// /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector key. - /// An observable which will emit group change sets. + /// The source to group. + /// A that extracts the group key from each item. + /// An observable that emits group changesets. Each group exposes a sub-cache of its members. + /// + /// + /// Items are assigned to groups based on the value returned by . + /// Groups are created on demand when the first item is assigned, and removed when their last member is removed. + /// + /// + /// EventBehavior + /// AddThe group key is evaluated. The item is added to the corresponding group (creating the group if new). An Add is emitted to the group's sub-cache. + /// UpdateThe group key is re-evaluated. If unchanged, an Update is emitted within the same group. If the key changed, the item is removed from the old group (emitting Remove) and added to the new group (emitting Add). An empty old group is removed. + /// RemoveThe item is removed from its group. If the group becomes empty, the group itself is removed from the output. + /// RefreshThe group key is re-evaluated. If unchanged, a Refresh is forwarded within the group. If the key changed, the item moves between groups (Remove from old, Add to new). + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// Worth noting: Each group is a live sub-cache that can be subscribed to independently. Subscribers + /// to a group receive only changes for items in that group. When a group is removed (becomes empty), + /// its sub-cache completes. + /// + /// + /// + /// + /// public static IObservable> Group(this IObservable> source, Func groupSelectorKey) where TObject : notnull where TKey : notnull @@ -1883,23 +2160,12 @@ public static IObservable> Group(source, groupSelectorKey, null).Run(); } - /// - /// Groups the source on the value returned by group selector factory. - /// - /// The type of the object. - /// The type of the key. - /// The type of the group key. - /// The source. - /// The group selector key. - /// Invoke to the for the grouping to be re-evaluated. - /// An observable which will emit group change sets. - /// - /// source - /// or - /// groupSelectorKey - /// or - /// groupController. - /// + /// + /// The source to group. + /// A that extracts the group key from each item. + /// An that, when it emits, all items are re-evaluated against the group selector, potentially moving items between groups. + /// An observable that emits group changesets. + /// This overload adds a signal. When it fires, every item in the cache is re-grouped using the current selector, which is useful when the grouping depends on mutable item state. public static IObservable> Group(this IObservable> source, Func groupSelectorKey, IObservable regrouper) where TObject : notnull where TKey : notnull @@ -1913,22 +2179,34 @@ public static IObservable> Group - /// Groups the source on the value returned by the latest value from the group selector factory observable. + /// Groups items using a dynamically changing group selector function. + /// Each time emits a new selector, all items are re-grouped. /// /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector key observable. - /// Fires when the current Grouping Selector needs to re-evaluate all the items in the cache. - /// An observable which will emit group change sets. - /// - /// source - /// or - /// groupSelectorKey - /// or - /// groupController. - /// + /// The source to group. + /// The that emits group selector functions. Each emission triggers a full re-grouping of all items. + /// An that optional signal to force re-evaluation of all items against the current selector. + /// An observable that emits group changesets. + /// + /// + /// Unlike the static-selector overload, this accepts an observable of selector functions. When a new selector + /// arrives, every item is re-evaluated and may move between groups. The optional + /// signal triggers re-evaluation without changing the selector (useful when item properties that affect grouping change). + /// + /// + /// EventBehavior + /// AddThe current selector determines the group. Item is added to the group (group created if new). + /// UpdateGroup key re-evaluated. Item may move between groups if the key changed. + /// RemoveItem removed from its group. Empty groups are removed. + /// RefreshGroup key re-evaluated. Item may move between groups. + /// OnErrorForwarded from source or from . + /// OnCompletedForwarded when the source completes. + /// + /// + /// + /// public static IObservable> Group(this IObservable> source, IObservable> groupSelectorKeyObservable, IObservable? regrouper = null) where TObject : notnull where TKey : notnull @@ -1940,23 +2218,11 @@ public static IObservable> Group(source, groupSelectorKeyObservable, regrouper).Run(); } - /// - /// Groups the source on the value returned by the latest value from the group selector factory observable. - /// - /// The type of the object. - /// The type of the key. - /// The type of the group key. - /// The source. - /// The group selector key observable. - /// Fires when the current Grouping Selector needs to re-evaluate all the items in the cache. - /// An observable which will emit group change sets. - /// - /// source - /// or - /// groupSelectorKey - /// or - /// groupController. - /// + /// + /// The source to group. + /// The of selector functions that take only the item (not the key). + /// An optional signal to force re-evaluation. + /// This overload accepts a selector that does not receive the key. Delegates to the overload accepting Func<TObject, TKey, TGroupKey>. public static IObservable> Group(this IObservable> source, IObservable> groupSelectorKeyObservable, IObservable? regrouper = null) where TObject : notnull where TKey : notnull @@ -1968,14 +2234,52 @@ public static IObservable> Group - /// Groups the source by the latest value from their observable created by the given factory. + /// Groups items where each item's group key is determined by a per-item observable. + /// The observable is created by for each item. /// /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector key. - /// An observable which will emit group change sets. + /// The source to group using per-item observables. + /// A factory that creates a group key observable for each item and its key. + /// An observable that emits group changesets. Each group is a live sub-cache of its members. + /// + /// + /// Unlike which evaluates + /// the group key synchronously, this operator defers group assignment until the per-item observable emits. + /// + /// + /// Source changeset handling (parent events): + /// + /// + /// EventBehavior + /// AddSubscribes to the per-item group key observable. The item is not placed in any group until the observable emits its first group key. + /// UpdateDisposes the old item's group key subscription and subscribes to the new item's observable. The item is removed from its current group until the new observable emits. + /// RemoveDisposes the item's group key subscription. The item is removed from its current group. Empty groups are removed. + /// RefreshNo effect on subscriptions. The item remains in its current group. + /// + /// + /// Per-item observable handling (group key observable events): + /// + /// + /// EmissionBehavior + /// First valueThe item is placed into the group matching the emitted key. An Add appears in that group's sub-cache. If the group is new, the group itself is added to the output. + /// New value (different key)The item moves: Remove from the old group, Add to the new group. If the old group becomes empty, it is removed from the output. + /// Same value (unchanged key)No effect (filtered by DistinctUntilChanged). + /// ErrorTerminates the entire output stream. + /// CompletedThe item remains in its current group. No further group key changes are possible for this item. + /// + /// + /// Worth noting: Items are invisible (not in any group) until their per-item observable emits at least one + /// group key. If an item's observable never emits, the item never appears in any group. Per-item observable errors + /// terminate the entire stream. The output completes when the source completes and all per-item observables have + /// also completed. + /// + /// + /// + /// + /// + /// public static IObservable> GroupOnObservable(this IObservable> source, Func> groupObservableSelector) where TObject : notnull where TKey : notnull @@ -1993,8 +2297,8 @@ public static IObservable> GroupOnObse /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector key. + /// The source to group using per-item observables. + /// The group selector key. /// An observable which will emit group change sets. public static IObservable> GroupOnObservable(this IObservable> source, Func> groupObservableSelector) where TObject : notnull @@ -2013,10 +2317,10 @@ public static IObservable> GroupOnObse /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The property selector used to group the items. - /// A time span that indicates the throttle to wait for property change events. - /// The scheduler. + /// The source to group by a property value. + /// The property selector used to group the items. + /// An optional a time span that indicates the throttle to wait for property change events. + /// An optional for scheduling work. /// An observable which will emit immutable group change sets. public static IObservable> GroupOnProperty(this IObservable> source, Expression> propertySelector, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged @@ -2036,10 +2340,10 @@ public static IObservable> GroupOnProp /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The property selector used to group the items. - /// A time span that indicates the throttle to wait for property change events. - /// The scheduler. + /// The source to group by a property value with immutable snapshots. + /// The property selector used to group the items. + /// An optional a time span that indicates the throttle to wait for property change events. + /// An optional for scheduling work. /// An observable which will emit immutable group change sets. public static IObservable> GroupOnPropertyWithImmutableState(this IObservable> source, Expression> propertySelector, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged @@ -2053,22 +2357,35 @@ public static IObservable> Gr } /// - /// Groups the source on the value returned by group selector factory. Each update produces immutable grouping. + /// Groups items by , emitting immutable group snapshots instead of mutable sub-caches. + /// Each group change contains a frozen copy of the group's state at that point in time. /// /// The type of the object. /// The type of the key. /// The type of the group key. - /// The source. - /// The group selector key. - /// Invoke to the for the grouping to be re-evaluated. - /// An observable which will emit immutable group change sets. - /// - /// source - /// or - /// groupSelectorKey - /// or - /// groupController. - /// + /// The source to group with immutable snapshots. + /// A that extracts the group key from each item. + /// An that optional signal to force re-evaluation of all items against the group selector. + /// An observable that emits immutable group changesets. + /// + /// + /// Behaves identically to + /// in terms of how items are assigned to groups, but each group emission is an immutable snapshot. + /// This makes it safe for parallel processing and eliminates race conditions on group state. + /// The tradeoff is higher memory usage, since each change produces a new snapshot of the affected group. + /// + /// + /// EventBehavior + /// AddItem added to its group. An immutable snapshot of the group is emitted. + /// UpdateIf group key unchanged, group snapshot re-emitted. If changed, item moves between groups; both affected groups emit new snapshots. + /// RemoveItem removed from group. Updated snapshot emitted. Empty groups are removed. + /// RefreshGroup key re-evaluated. If changed, item moves; affected group snapshots emitted. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// + /// + /// public static IObservable> GroupWithImmutableState(this IObservable> source, Func groupSelectorKey, IObservable? regrouper = null) where TObject : notnull where TKey : notnull @@ -2085,7 +2402,7 @@ public static IObservable> Gr /// /// The object of the change set. /// The key of the change set. - /// The source observable which emits change sets. + /// The source to suppress same-reference updates in. /// An observable which emits change sets and ignores equal value changes. public static IObservable> IgnoreSameReferenceUpdate(this IObservable> source) where TObject : notnull @@ -2097,8 +2414,8 @@ public static IObservable> IgnoreSameReferenceUpdate /// The type of the object. /// The type of the key. - /// The source. - /// The ignore function (current,previous)=>{ return true to ignore }. + /// The source to selectively suppress updates in. + /// The ignore function (current,previous)=>{ return true to ignore }. /// An observable which emits change sets and ignores updates equal to the lambda. public static IObservable> IgnoreUpdateWhen(this IObservable> source, Func ignoreFunction) where TObject : notnull @@ -2124,8 +2441,8 @@ public static IObservable> IgnoreUpdateWhen /// The type of the object. /// The type of the key. - /// The source. - /// The include function (current,previous)=>{ return true to include }. + /// The source to selectively include updates in. + /// The include function (current,previous)=>{ return true to include }. /// An observable which emits change sets and ignores updates equal to the lambda. public static IObservable> IncludeUpdateWhen(this IObservable> source, Func includeFunction) where TObject : notnull @@ -2142,20 +2459,12 @@ public static IObservable> IncludeUpdateWhen - /// Joins the left and right observable data sources, taking values when both left and right values are present - /// This is the equivalent of SQL inner join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the left and right values into a destination object. The composite key is not provided in this overload. + /// Overload that omits the composite key from the result selector. Delegates to . public static IObservable> InnerJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2172,19 +2481,48 @@ public static IObservable> IncludeUpdateWhen - /// Groups the right data source and joins the to the left and the right sources, taking values when both left and right values are present - /// This is the equivalent of SQL inner join. + /// Joins two changeset streams, producing a result only for keys that exist on both sides simultaneously. + /// When either side loses its value for a key, the joined result is removed. Equivalent to SQL INNER JOIN. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the composite key, left value, and right value into a destination object. Example: ((leftKey, rightKey), left, right) => new Result(leftKey, rightKey, left, right). + /// An observable changeset keyed by a composite (TLeftKey, TRightKey) tuple. + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddIf a matching right value exists, invokes and emits an Add. If no right match, no emission. + /// UpdateIf a matching right exists, re-invokes the selector and emits an Update. + /// RemoveRemoves all joined results involving the removed left key. + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddIf a matching left value exists, invokes the selector and emits an Add. + /// UpdateIf a matching left exists, re-invokes the selector and emits an Update. + /// RemoveRemoves the joined result for this right key (if it was downstream). + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// The output is keyed by a (TLeftKey, TRightKey) composite tuple, since a single left item may match multiple right items. + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> InnerJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func<(TLeftKey leftKey, TRightKey rightKey), TLeft, TRight, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2200,20 +2538,12 @@ public static IObservable> IncludeUpdateWhen(left, right, rightKeySelector, resultSelector).Run(); } - /// - /// Groups the right data source and joins the resulting group to the left data source, matching these using the specified key selector. Results are included when the left and right have matching values. - /// This is the equivalent of SQL inner join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the left value and the right group into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> InnerJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2230,19 +2560,48 @@ public static IObservable> InnerJoinMany - /// Groups the right data source and joins the resulting group to the left data source, matching these using the specified key selector. Results are included when the left and right have matching values. - /// This is the equivalent of SQL inner join. + /// Groups right-side items by their mapped key, then inner-joins each group to the left source. + /// A result is produced only when a left item and at least one right item share the same key. + /// Equivalent to SQL INNER JOIN with the right side grouped. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, left value, and right group into a destination object. Example: (key, left, group) => new Result(key, left, group). + /// An observable changeset keyed by . + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddIf a non-empty right group exists for this key, invokes and emits an Add. Otherwise no emission. + /// UpdateIf a right group exists, re-invokes the selector and emits an Update. + /// RemoveRemoves the joined result (if it was downstream). + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddUpdates the right group. If a matching left exists and the group was previously empty, emits an Add. If already joined, emits an Update. + /// UpdateUpdates the right group and re-invokes the selector if a matching left exists. + /// RemoveUpdates the right group. If the group becomes empty, removes the joined result. + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> InnerJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2259,29 +2618,34 @@ public static IObservable> InnerJoinMany - /// Invokes Refresh method for an object which implements IEvaluateAware. + /// Calls Evaluate() on items that implement when a Refresh change arrives. + /// Other change reasons are forwarded without invoking Evaluate. /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change sets. + /// The source to trigger re-evaluation on. + /// An observable that emits the same changesets as , unchanged. + /// + /// + /// EventBehavior + /// AddForwarded unchanged. + /// UpdateForwarded unchanged. + /// RemoveForwarded unchanged. + /// RefreshCalls Evaluate() on the item, then forwards the change. + /// OnErrorForwarded to subscribers. + /// OnCompletedForwarded to subscribers. + /// + /// public static IObservable> InvokeEvaluate(this IObservable> source) where TObject : IEvaluateAware where TKey : notnull => source.Do(changes => changes.Where(u => u.Reason == ChangeReason.Refresh).ForEach(u => u.Current.Evaluate())); - /// - /// Joins the left and right observable data sources, taking all left values and combining any matching right values. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the left value and the optional right into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> LeftJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2298,18 +2662,48 @@ public static IObservable> LeftJoin - /// Joins the left and right observable data sources, taking all left values and combining any matching right values. + /// Joins two changeset streams, producing a result for every left-side key. The right side is + /// because a matching right item may or may not exist. All left items + /// appear in the output regardless. Equivalent to SQL LEFT OUTER JOIN. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, left value, and optional right into a destination object. Example: (key, left, right) => new Result(key, left, right). + /// An observable changeset keyed by . + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddAlways emits. Invokes with the left value and matching right (or ). + /// UpdateRe-invokes the selector with the new left value and current right (if any). + /// RemoveRemoves the joined result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddIf a matching left exists, re-invokes the selector (right transitions from None to Some) and emits an Update. + /// UpdateIf a matching left exists, re-invokes the selector with the new right value. + /// RemoveIf a matching left exists, re-invokes the selector (right transitions from Some to None) and emits an Update. + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> LeftJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2325,20 +2719,12 @@ public static IObservable> LeftJoin(left, right, rightKeySelector, resultSelector).Run(); } - /// - /// Groups the right data source and joins the two sources matching them using the specified key selector, taking all left values and combining any matching right values. - /// This is the equivalent of SQL left join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the left value and the right group into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> LeftJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2355,19 +2741,48 @@ public static IObservable> LeftJoinMany - /// Groups the right data source and joins the two sources matching them using the specified key selector, taking all left values and combining any matching right values. - /// This is the equivalent of SQL left join. + /// Groups right-side items by their mapped key, then left-joins each group to the left source. + /// A result is produced for every left-side key. The right group may be empty if no right items match. + /// Equivalent to SQL LEFT OUTER JOIN with the right side grouped. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, left value, and right group into a destination object. Example: (key, left, group) => new Result(key, left, group). + /// An observable changeset keyed by . + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddAlways emits. Invokes with the left value and the current right group (which may be empty). + /// UpdateRe-invokes the selector with the new left value and current right group. + /// RemoveRemoves the joined result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddUpdates the right group. If a matching left exists, re-invokes the selector and emits an Update. + /// UpdateUpdates the right group and re-invokes the selector if a matching left exists. + /// RemoveUpdates the right group. If a matching left exists, re-invokes the selector (group may now be empty). + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> LeftJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -2384,16 +2799,27 @@ public static IObservable> LeftJoinMany - /// Applies a size limiter to the number of records which can be included in the - /// underlying cache. When the size limit is reached the oldest items are removed. + /// Applies a FIFO size limit to the changeset stream. When the number of items exceeds , + /// the oldest items are evicted and emitted as Remove changes. /// /// The type of the object. /// The type of the key. - /// The source. - /// The size. - /// An observable which emits change sets. - /// source. - /// size cannot be zero. + /// The source to apply size limits to. + /// The maximum number of items allowed. Must be greater than zero. + /// An observable changeset stream with size-limited contents. + /// + /// + /// EventBehavior + /// AddForwarded. If the cache exceeds the size limit, the oldest items are emitted as Remove changes. + /// UpdateForwarded unchanged. + /// RemoveForwarded unchanged. + /// RefreshForwarded unchanged. + /// OnErrorForwarded to subscribers. + /// OnCompletedForwarded to subscribers. + /// + /// + /// is . + /// is zero or negative. public static IObservable> LimitSizeTo(this IObservable> source, int size) where TObject : notnull where TKey : notnull @@ -2409,17 +2835,17 @@ public static IObservable> LimitSizeTo( } /// - /// Limits the number of records in the cache to the size specified. When the size is reached - /// the oldest items are removed from the cache. + /// Operates directly on a , removing the oldest items when the cache + /// exceeds . Returns an observable of the evicted key-value pairs (not a changeset stream). /// /// The type of the object. /// The type of the key. - /// The source. - /// The size limit. - /// The scheduler. - /// An observable which emits the key value pairs. - /// source. - /// Size limit must be greater than zero. + /// The to operate on. + /// The maximum number of items allowed. Must be greater than zero. + /// An optional for observing changes. Defaults to . + /// An observable that emits batches of evicted key-value pairs whenever the cache exceeds the size limit. + /// is . + /// is zero or negative. public static IObservable>> LimitSizeTo(this ISourceCache source, int sizeLimit, IScheduler? scheduler = null) where TObject : notnull where TKey : notnull @@ -2454,18 +2880,39 @@ public static IObservable>> LimitSizeTo< } /// - /// Dynamically merges the observable which is selected from each item in the stream, and un-merges the item - /// when it is no longer part of the stream. + /// Subscribes to a child observable for each item in the source cache changeset stream and merges all child + /// emissions into a single . When an item is added, + /// creates its child subscription. When updated, the previous child subscription is disposed and a new one is created. + /// When removed, its child subscription is disposed. Refresh changes have no effect on subscriptions. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The source. - /// The observable selector. - /// An observable which emits the transformed value. - /// source - /// or - /// observableSelector. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of values emitted by child observables. + /// The source whose items each produce an observable. + /// A factory function that produces a child observable for each source item. + /// An observable that emits values from all active child observables, interleaved by arrival order. + /// + /// + /// This operator does not produce changesets. It produces a flat stream of + /// values, similar to Rx SelectMany but lifecycle-aware: child subscriptions track items entering and + /// leaving the source cache. + /// + /// + /// EventBehavior + /// AddCalls to create a child observable and subscribes to it. Emissions from the child flow into the merged output. + /// UpdateDisposes the previous child subscription and creates a new one for the updated item. + /// RemoveDisposes the child subscription for the removed item. + /// RefreshNo effect on subscriptions. The child observable continues unchanged. + /// OnErrorErrors from child observables are silently swallowed (the child is unsubscribed). Errors from the source changeset stream terminate the merged output. + /// OnCompletedThe output completes only when the source completes and all active child observables have also completed. + /// + /// Worth noting: The output is a plain , not a changeset stream. If you need merged changesets, use instead. + /// + /// or is null. + /// + /// + /// + /// public static IObservable MergeMany(this IObservable> source, Func> observableSelector) where TObject : notnull where TKey : notnull @@ -2476,19 +2923,9 @@ public static IObservable MergeMany(t return new MergeMany(source, observableSelector).Run(); } - /// - /// Dynamically merges the observable which is selected from each item in the stream, and un-merges the item - /// when it is no longer part of the stream. - /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The source. - /// The observable selector. - /// An observable which emits the transformed value. - /// source - /// or - /// observableSelector. + /// + /// The source whose items each produce an observable. + /// A factory function that receives both the item and its key, and returns a child observable. public static IObservable MergeMany(this IObservable> source, Func> observableSelector) where TObject : notnull where TKey : notnull @@ -2500,13 +2937,53 @@ public static IObservable MergeMany(t } /// - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges multiple changeset streams that arrive dynamically into a single unified changeset stream. + /// Each inner stream emitted by the outer observable is subscribed and its changes forwarded downstream. + /// When multiple sources provide the same key, the first source to add it retains priority unless a + /// comparer-based overload is used. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// An that emits changeset streams. Each inner stream is subscribed as it appears. + /// A unified changeset stream containing changes from all active source streams. + /// + /// + /// Each inner changeset stream is independently tracked in its own cache. When multiple sources provide the same key, + /// this overload uses first-in-wins semantics: the value from whichever source added the key first is + /// the one published downstream. To control which value wins for duplicate keys, use an overload that + /// accepts an , which selects the lowest-ordered value across all sources. + /// An can be provided separately to suppress no-op updates when + /// the new value equals the currently published value for a key. + /// + /// + /// Overload families: MergeChangeSets has 16 overloads organized along three axes: + /// (1) Source type: dynamic (IObservable<IObservable<IChangeSet>>, sources arrive at runtime), + /// pair (source + other, exactly two streams), or static (, all sources known up front). + /// (2) Conflict resolution: none (first-in-wins), (lowest-ordered wins), + /// (suppresses duplicate updates), or both. + /// (3) Completion: static overloads accept a completable flag; when , the output never completes + /// even after all sources finish (useful for "live" merge scenarios). + /// + /// + /// EventBehavior + /// AddIf no source has previously provided this key, an Add is emitted downstream. If another source already holds this key, the new value is tracked internally but not emitted (first-in-wins). With a comparer, the lowest-ordered value across all sources is selected and published instead. + /// UpdateIf the updating source currently owns the downstream value for this key, an Update is emitted. If a comparer is provided and the update causes a different source's value to become the best candidate, an Update is emitted with that other source's value. + /// RemoveIf the removed value was the one published downstream, the operator scans all remaining sources for the same key. If another source still holds that key, an Update is emitted with the replacement value (selected by comparer if provided, otherwise the next available). If no other source holds the key, a Remove is emitted. + /// RefreshIf the refreshed item matches the currently published value, the Refresh is forwarded. With a comparer, all sources are re-evaluated first; if a different value now wins, an Update is emitted instead of the Refresh. + /// OnErrorAn error from any source (outer or inner) terminates the entire merged output. + /// OnCompletedFor dynamic overloads, the output completes when the outer observable completes and all subscribed inner observables have also completed. For static overloads, completion depends on the completable parameter (default ). + /// + /// + /// Worth noting: When a source removes a key that was published downstream, the fallback to another + /// source's value is emitted as an Update (not an Add). This can be surprising if you expect + /// a Remove followed by an Add. Also, errors from any single inner source terminate the entire merged + /// stream, so consider error handling within individual sources if isolation is needed. + /// + /// + /// is . + /// + /// + /// public static IObservable> MergeChangeSets(this IObservable>> source) where TObject : notnull where TKey : notnull @@ -2517,14 +2994,16 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges dynamic cache changeset streams into a single output, using a comparer to resolve key conflicts. + /// When multiple sources provide the same key, the item ordering lowest according to + /// is published downstream. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// An that emits changeset streams. Each inner stream is subscribed as it appears. + /// An that comparer to determine which value wins when multiple sources provide the same key. The lowest-ordered value is published. + /// A unified changeset stream containing changes from all active source streams. + /// or is null. public static IObservable> MergeChangeSets(this IObservable>> source, IComparer comparer) where TObject : notnull where TKey : notnull @@ -2536,14 +3015,16 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges dynamic cache changeset streams into a single output, using an equality comparer to suppress + /// redundant updates. When an incoming value for a key is equal (per ) + /// to the currently published value, the update is suppressed. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// An that emits changeset streams. Each inner stream is subscribed as it appears. + /// An that equality comparer to detect duplicate values for the same key, suppressing no-op updates. + /// A unified changeset stream containing changes from all active source streams. + /// or is null. public static IObservable> MergeChangeSets(this IObservable>> source, IEqualityComparer equalityComparer) where TObject : notnull where TKey : notnull @@ -2555,15 +3036,16 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges dynamic cache changeset streams into a single output, using both a comparer for key conflict resolution + /// and an equality comparer to suppress redundant updates. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// An that emits changeset streams. Each inner stream is subscribed as it appears. + /// An that equality comparer to detect duplicate values for the same key, suppressing no-op updates. + /// An that comparer to determine which value wins when multiple sources provide the same key. The lowest-ordered value is published. + /// A unified changeset stream containing changes from all active source streams. + /// , , or is null. public static IObservable> MergeChangeSets(this IObservable>> source, IEqualityComparer equalityComparer, IComparer comparer) where TObject : notnull where TKey : notnull @@ -2576,16 +3058,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges both observable changesets into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Convenience overload that merges exactly two cache changeset streams into a single output. + /// Uses first-in-wins semantics for key conflicts. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSet. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The second to merge with . + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when both streams complete. If , the output never completes. + /// A unified changeset stream containing changes from both sources. + /// or is null. public static IObservable> MergeChangeSets(this IObservable> source, IObservable> other, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2597,17 +3080,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges both observable changesets into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Convenience overload that merges exactly two cache changeset streams, using a comparer for key conflict resolution. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSet. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The second to merge with . + /// An that comparer to determine which value wins when both sources provide the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when both streams complete. If , the output never completes. + /// A unified changeset stream containing changes from both sources. + /// , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IObservable> other, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2620,17 +3103,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges both observable changesets into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Convenience overload that merges exactly two cache changeset streams, using an equality comparer to suppress redundant updates. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSet. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The second to merge with . + /// An that equality comparer to detect duplicate values for the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when both streams complete. If , the output never completes. + /// A unified changeset stream containing changes from both sources. + /// , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IObservable> other, IEqualityComparer equalityComparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2643,18 +3126,18 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges both observable changesets into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Convenience overload that merges exactly two cache changeset streams, using both a comparer and an equality comparer. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSet. - /// instance to determine if two elements are the same. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The second to merge with . + /// An that equality comparer to detect duplicate values for the same key. + /// An that comparer to determine which value wins when both sources provide the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when both streams complete. If , the output never completes. + /// A unified changeset stream containing changes from both sources. + /// , , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IObservable> other, IEqualityComparer equalityComparer, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2668,16 +3151,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges the source changeset and the collection of other changesets together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges with additional changeset streams into a single output. + /// Uses first-in-wins semantics for key conflicts. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The additional streams to merge with . + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all streams complete. If , the output never completes. + /// A unified changeset stream containing changes from all sources. + /// or is null. public static IObservable> MergeChangeSets(this IObservable> source, IEnumerable>> others, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2689,17 +3173,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges the source changeset and the collection of other changesets together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges with additional changeset streams, using a comparer for key conflict resolution. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSets. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The additional streams to merge with . + /// An that comparer to determine which value wins when multiple sources provide the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all streams complete. If , the output never completes. + /// A unified changeset stream containing changes from all sources. + /// , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IEnumerable>> others, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2712,17 +3196,17 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges the source changeset and the collection of other changesets together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges with additional changeset streams, using an equality comparer to suppress redundant updates. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSets. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The additional streams to merge with . + /// An that equality comparer to detect duplicate values for the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all streams complete. If , the output never completes. + /// A unified changeset stream containing changes from all sources. + /// , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IEnumerable>> others, IEqualityComparer equalityComparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2735,18 +3219,18 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. Merges the source changeset and the collection of other changesets together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges with additional changeset streams, using both a comparer and an equality comparer. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSets. - /// instance to determine if two elements are the same. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// The additional streams to merge with . + /// An that equality comparer to detect duplicate values for the same key. + /// An that comparer to determine which value wins when multiple sources provide the same key. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all streams complete. If , the output never completes. + /// A unified changeset stream containing changes from all sources. + /// , , , or is null. public static IObservable> MergeChangeSets(this IObservable> source, IEnumerable>> others, IEqualityComparer equalityComparer, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2760,15 +3244,27 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges a fixed collection of cache changeset streams into a single unified output. All source streams are + /// subscribed when the output observable is subscribed to. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all source streams have completed. If , the output never completes. + /// A unified changeset stream containing changes from all source streams. + /// + /// + /// When multiple sources provide items with the same key, this overload uses first-in-wins semantics: + /// the first source to provide a key retains priority. Removing that source's item allows the next + /// available value for that key (if any) to surface. To control which value wins, use an overload + /// that accepts an . + /// + /// + /// An error from any source terminates the entire merged output. + /// + /// + /// is null. public static IObservable> MergeChangeSets(this IEnumerable>> source, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2779,16 +3275,18 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges a fixed collection of cache changeset streams into a single output, using a comparer for key conflict + /// resolution. When multiple sources provide the same key, the item ordering lowest according to + /// is published downstream. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// An that comparer to determine which value wins when multiple sources provide the same key. The lowest-ordered value is published. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all source streams have completed. If , the output never completes. + /// A unified changeset stream containing changes from all source streams. + /// or is null. public static IObservable> MergeChangeSets(this IEnumerable>> source, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2800,16 +3298,18 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges a fixed collection of cache changeset streams into a single output, using an equality comparer to + /// suppress redundant updates. When an incoming value for a key is equal (per ) + /// to the currently published value, the update is suppressed. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// An that equality comparer to detect duplicate values for the same key, suppressing no-op updates. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all source streams have completed. If , the output never completes. + /// A unified changeset stream containing changes from all source streams. + /// or is null. public static IObservable> MergeChangeSets(this IEnumerable>> source, IEqualityComparer equalityComparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2821,17 +3321,18 @@ public static IObservable> MergeChangeSets - /// Operator similar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events that correctly handles multiple Keys. + /// Merges a fixed collection of cache changeset streams into a single output, using both a comparer for key + /// conflict resolution and an equality comparer to suppress redundant updates. /// - /// The type of the object. - /// The type of the key. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// instance to determine which element to emit if the same key is emitted from multiple changesets. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the changesets. + /// The type of the key identifying items. + /// The source to merge. + /// An that equality comparer to detect duplicate values for the same key, suppressing no-op updates. + /// An that comparer to determine which value wins when multiple sources provide the same key. The lowest-ordered value is published. + /// An optional used when subscribing to the source streams. + /// If (default), the output completes when all source streams have completed. If , the output never completes. + /// A unified changeset stream containing changes from all source streams. + /// , , or is null. public static IObservable> MergeChangeSets(this IEnumerable>> source, IEqualityComparer equalityComparer, IComparer comparer, IScheduler? scheduler = null, bool completable = true) where TObject : notnull where TKey : notnull @@ -2844,17 +3345,20 @@ public static IObservable> MergeChangeSets - /// Operator similar to MergeMany except it is ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// For each item in the source cache, subscribes to a child cache changeset stream and merges all child changes + /// into a single flattened output. This overload requires a comparer for resolving destination key conflicts. + /// The selector receives only the item, not its key. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that comparer to resolve key conflicts when multiple child streams provide items with the same destination key. The lowest-ordered item wins. + /// A merged changeset stream containing items from all active child streams. + /// or is null. + /// public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer comparer) where TObject : notnull where TKey : notnull @@ -2867,17 +3371,18 @@ public static IObservable> MergeManyCh } /// - /// Operator similar to MergeMany except it is ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// For each item in the source cache, subscribes to a child cache changeset stream and merges all child changes + /// into a single flattened output. This overload requires a comparer for resolving destination key conflicts. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child cache changeset stream. + /// An that comparer to resolve key conflicts when multiple child streams provide items with the same destination key. The lowest-ordered item wins. + /// A merged changeset stream containing items from all active child streams. + /// , , or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer comparer) where TObject : notnull where TKey : notnull @@ -2892,18 +3397,19 @@ public static IObservable> MergeManyCh } /// - /// Operator similar to MergeMany except it is ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// For each item in the source cache, subscribes to a child cache changeset stream and merges all child changes + /// into a single flattened output. The selector receives only the item, not its key. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that optional equality comparer to suppress updates when the incoming child value equals the current value for a destination key. + /// An that optional comparer to resolve key conflicts when multiple child streams provide items with the same destination key. The lowest-ordered item wins. + /// A merged changeset stream containing items from all active child streams. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TObject : notnull where TKey : notnull @@ -2917,18 +3423,65 @@ public static IObservable> MergeManyCh } /// - /// Operator similar to MergeMany except it is ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// For each item in the source cache, subscribes to a child changeset stream and merges all child + /// changes into a single flattened output stream. Child subscriptions track the parent item lifecycle: + /// created on Add, replaced on Update, disposed on Remove. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source (parent) cache. + /// The type of the key identifying parent items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a parent item and its key, and returns a child cache changeset stream. Called once per parent Add/Update. + /// An that optional equality comparer to suppress no-op child updates. When a child key's new value equals the current value per this comparer, the update is not emitted. + /// An that optional comparer to resolve child key conflicts when multiple parents contribute children with the same destination key. The lowest-ordered child value wins. Without a comparer, the first parent to provide a key retains priority. + /// A merged changeset stream containing all child items from all active parent subscriptions. + /// + /// + /// This is the changeset-aware counterpart to . + /// Where MergeMany produces a flat IObservable<T>, MergeManyChangeSets produces an IObservable<IChangeSet> + /// that tracks the full lifecycle of child items, including key conflict resolution across parents. + /// + /// + /// Parent-side change handling (source changeset events): + /// + /// + /// EventBehavior + /// AddCalls with the new parent item to obtain a child changeset stream, then subscribes. As the child stream emits changesets, those child items are merged into the output. The downstream observer sees Add changes for each new child item. + /// UpdateDisposes the previous parent's child subscription (removing all of its contributed child items from the output as Remove changes), then creates a new child subscription for the updated parent. The new child's items appear as Add changes. + /// RemoveDisposes the parent's child subscription. All child items contributed by that parent are emitted as Remove changes in the output. If another parent also provides a child with the same destination key, that parent's value is promoted as an Update (not an Add). + /// RefreshNo effect on the child subscription. The parent's child stream continues unchanged. + /// + /// + /// Child-side change handling (changes arriving from child changeset streams): + /// + /// + /// EventBehavior + /// AddIf the destination key is new, an Add is emitted. If another parent already contributed a child with the same key, the conflict is resolved by (lowest wins) or first-in-wins if no comparer. The losing value is tracked internally but not emitted. + /// UpdateIf this parent currently owns the destination key downstream, an Update is emitted. With a comparer, all parents are re-evaluated for that key; a different parent's value may win, producing an Update to that value instead. + /// RemoveIf this parent's value was the one published downstream for that destination key, the operator scans other parents for the same key. If found, an Update is emitted with the replacement. If not, a Remove is emitted. + /// RefreshIf the child item is the one currently published downstream, the Refresh is forwarded. With a comparer, all parents are re-evaluated first; if a different value now wins, an Update is emitted instead. + /// + /// + /// Error and completion: + /// + /// + /// EventBehavior + /// OnErrorAn error from the source (parent) stream or from any child changeset stream terminates the entire output. Unlike , child errors are NOT swallowed. + /// OnCompletedThe output completes when the source (parent) stream completes and all active child changeset streams have also completed. + /// + /// + /// Worth noting: When multiple parents contribute children with the same destination key, only one value is published + /// downstream at a time. The controls which value wins; without it, the first parent to add the key + /// retains priority. Removing a parent that owned a contested key causes the next-best value (per comparer or next available) + /// to surface as an Update, not an Add. The independently controls whether a child + /// Update for an already-published key is suppressed when the new value equals the old. + /// + /// + /// or is . + /// + /// + /// public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TObject : notnull where TKey : notnull @@ -2942,19 +3495,21 @@ public static IObservable> MergeManyCh } /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. + /// Source-priority variant of MergeManyChangeSets with a required . + /// Uses to resolve destination key conflicts by source priority. + /// The selector receives only the item, not its key. + /// Source priorities are always re-evaluated on Refresh (default behavior). /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. Lower-ordered source wins. + /// An that fallback comparer to resolve destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, IComparer childComparer) where TObject : notnull where TKey : notnull @@ -2968,19 +3523,20 @@ public static IObservable> MergeManyCh } /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. + /// Source-priority variant of MergeManyChangeSets with a required . + /// Uses to resolve destination key conflicts by source priority. + /// Source priorities are always re-evaluated on Refresh (default behavior). /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. Lower-ordered source wins. + /// An that fallback comparer to resolve destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, IComparer childComparer) where TObject : notnull where TKey : notnull @@ -2988,20 +3544,20 @@ public static IObservable> MergeManyCh where TDestinationKey : notnull => source.MergeManyChangeSets(observableSelector, sourceComparer, DefaultResortOnSourceRefresh, equalityComparer: null, childComparer); /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. - /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional boolean to indicate whether or not a refresh event in the parent stream should re-evaluate item priorities. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// Source-priority variant of MergeManyChangeSets with a required and + /// explicit control. The selector receives only the item. + /// + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. + /// If , a Refresh in the source stream re-evaluates source priorities. If , Refresh events are ignored for priority recalculation. + /// An that fallback comparer to resolve destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, bool resortOnSourceRefresh, IComparer childComparer) where TObject : notnull where TKey : notnull @@ -3015,20 +3571,20 @@ public static IObservable> MergeManyCh } /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. + /// Source-priority variant of MergeManyChangeSets with a required and + /// explicit control. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional boolean to indicate whether or not a refresh event in the parent stream should re-evaluate item priorities. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. + /// If , a Refresh in the source stream re-evaluates source priorities. If , Refresh events are ignored for priority recalculation. + /// An that fallback comparer to resolve destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, bool resortOnSourceRefresh, IComparer childComparer) where TObject : notnull where TKey : notnull @@ -3036,20 +3592,21 @@ public static IObservable> MergeManyCh where TDestinationKey : notnull => source.MergeManyChangeSets(observableSelector, sourceComparer, resortOnSourceRefresh, equalityComparer: null, childComparer); /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. - /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional instance to determine if two elements are the same. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// Source-priority variant of MergeManyChangeSets. Uses to resolve + /// destination key conflicts. The selector receives only the item, not its key. + /// Source priorities are always re-evaluated on Refresh (default behavior). + /// + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. + /// An that optional equality comparer to suppress updates when the incoming child value equals the current value. + /// An that optional fallback comparer for destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, IEqualityComparer? equalityComparer = null, IComparer? childComparer = null) where TObject : notnull where TKey : notnull @@ -3063,20 +3620,20 @@ public static IObservable> MergeManyCh } /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. + /// Source-priority variant of MergeManyChangeSets. Uses to resolve + /// destination key conflicts. Source priorities are always re-evaluated on Refresh (default behavior). /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional instance to determine if two elements are the same. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. + /// An that optional equality comparer to suppress updates when the incoming child value equals the current value. + /// An that optional fallback comparer for destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, IEqualityComparer? equalityComparer = null, IComparer? childComparer = null) where TObject : notnull where TKey : notnull @@ -3084,21 +3641,21 @@ public static IObservable> MergeManyCh where TDestinationKey : notnull => source.MergeManyChangeSets(observableSelector, sourceComparer, DefaultResortOnSourceRefresh, equalityComparer, childComparer); /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. - /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional boolean to indicate whether or not a refresh event in the parent stream should re-evaluate item priorities. - /// Optional instance to determine if two elements are the same. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// Source-priority variant of MergeManyChangeSets with full control over all conflict resolution parameters. + /// The selector receives only the item, not its key. + /// + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. + /// If , a Refresh in the source stream re-evaluates source priorities. If , Refresh events are ignored for priority recalculation. + /// An that optional equality comparer to suppress updates when the incoming child value equals the current value. + /// An that optional fallback comparer for destination key conflicts when source items compare equal. + /// A merged changeset stream with conflicts resolved by source priority. + /// or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, bool resortOnSourceRefresh, IEqualityComparer? equalityComparer = null, IComparer? childComparer = null) where TObject : notnull where TKey : notnull @@ -3112,21 +3669,33 @@ public static IObservable> MergeManyCh } /// - /// Overload of that - /// will handle key collisions by using an instance that operates on the sources, so that the values from the preferred source take precedent over other values with the same. + /// For each item in the source cache, subscribes to a child cache changeset stream and merges all child + /// changes into a single flattened output. When multiple source items produce children with the same destination key, + /// determines which source has priority (the source ordering lower wins). + /// If sources compare equal, (if provided) breaks the tie. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which source elements child to use when two sources provide a child element with the same key. - /// Optional boolean to indicate whether or not a refresh event in the parent stream should re-evaluate item priorities. - /// Optional instance to determine if two elements are the same. - /// Optional fallback instance to determine which child element to emit if the sources compare to be the same. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child changeset streams. + /// The type of the key identifying child items. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child cache changeset stream. + /// An that comparer to prioritize between source items when their children produce the same destination key. Lower-ordered source wins. + /// If (default), a Refresh in the source stream re-evaluates source priorities. If , Refresh events are ignored for priority recalculation. + /// An that optional equality comparer to suppress updates when the incoming child value equals the current value for a destination key. + /// An that optional fallback comparer to resolve destination key conflicts when source items compare equal. + /// A merged changeset stream containing items from all active child streams, with conflicts resolved by source priority. + /// + /// + /// The provides a layer of conflict resolution above the child values themselves. + /// This is useful when source items represent priority tiers (e.g., user settings overriding defaults). + /// + /// + /// Errors from child streams propagate to the output. An error from the source or any child terminates the merged output. + /// The output completes when the source completes and all active child streams have also completed. + /// + /// + /// , , or is null. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer sourceComparer, bool resortOnSourceRefresh, IEqualityComparer? equalityComparer = null, IComparer? childComparer = null) where TObject : notnull where TKey : notnull @@ -3141,15 +3710,17 @@ public static IObservable> MergeManyCh } /// - /// Merges the List ChangeSets derived from items in a Cache ChangeSet into a single observable list changeset. + /// For each item in the source cache, subscribes to a child list changeset stream produced by + /// and merges all child changes into a single flattened list changeset output. + /// Child subscriptions follow the source item lifecycle: created on Add, replaced on Update, disposed on Remove. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// The result from merging the child changesets together. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child list changeset streams. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and its key, and returns a child list changeset stream. + /// An that optional equality comparer to detect duplicate items in the merged list output. + /// A merged list changeset stream containing items from all active child streams. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -3162,15 +3733,16 @@ public static IObservable> MergeManyChangeSets - /// Merges the List ChangeSets derived from items in a Cache ChangeSet into a single observable list changeset. + /// For each item in the source cache, subscribes to a child list changeset stream and merges all child changes + /// into a single flattened list changeset output. The selector receives only the item, not its key. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// The result from merging the child changesets together. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of items in the child list changeset streams. + /// The source whose items each produce a child changeset stream. + /// A factory function that receives a source item and returns a child list changeset stream. + /// An that optional equality comparer to detect duplicate items in the merged list output. + /// A merged list changeset stream containing items from all active child streams. public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -3181,18 +3753,17 @@ public static IObservable> MergeManyChangeSets - /// Dynamically merges the observable which is selected from each item in the stream, and un-merges the item - /// when it is no longer part of the stream. + /// Like , + /// but wraps each emitted value as an , pairing the source item + /// with the value it produced. This lets you identify which source item is responsible for each emission. /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The source. - /// The observable selector. - /// An observable which emits the item with the value. - /// source - /// or - /// observableSelector. + /// The type of items in the source cache. + /// The type of the key identifying source cache items. + /// The type of values emitted by child observables. + /// The source whose items each produce an observable. + /// A factory function that produces a child observable for each source item. + /// An observable of pairing each emission with its source item. + /// or is null. public static IObservable> MergeManyItems(this IObservable> source, Func> observableSelector) where TObject : notnull where TKey : notnull @@ -3203,19 +3774,9 @@ public static IObservable> MergeManyItems(source, observableSelector).Run(); } - /// - /// Dynamically merges the observable which is selected from each item in the stream, and un-merges the item - /// when it is no longer part of the stream. - /// - /// The type of the object. - /// The type of the key. - /// The type of the destination. - /// The source. - /// The observable selector. - /// An observable which emits the item with the value. - /// source - /// or - /// observableSelector. + /// + /// The source whose items each produce an observable. + /// A factory function that receives both the item and its key, and returns a child observable. public static IObservable> MergeManyItems(this IObservable> source, Func> observableSelector) where TObject : notnull where TKey : notnull @@ -3227,22 +3788,26 @@ public static IObservable> MergeManyItems - /// Monitors the status of a stream. + /// Monitors the source observable and emits values: Pending initially, + /// Loaded when the first value arrives, Errored on error, and Completed on completion. + /// This is not a changeset operator. /// /// The type of the source observable. - /// The source. - /// An observable which monitors the status of the observable. - /// source. + /// The source to monitor for connection status. + /// An observable that emits values reflecting the source's lifecycle. + /// is . + /// public static IObservable MonitorStatus(this IObservable source) => new StatusMonitor(source).Run(); /// - /// Suppresses updates which are empty. + /// Filters out empty changesets from the stream. A thin wrapper around Where(changes => changes.Count != 0). /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change set values when not empty. - /// source. + /// The source to suppress empty changesets. + /// An observable that emits only non-empty changesets. + /// is . + /// public static IObservable> NotEmpty(this IObservable> source) where TObject : notnull where TKey : notnull @@ -3253,16 +3818,27 @@ public static IObservable> NotEmpty(thi } /// - /// Filters an observable changeset so that it only includes items that are of type . + /// Filters and casts items in the changeset to . Items that are not of type + /// are excluded. Combines filter and transform in one step without an intermediate cache. /// /// The type of the objects in the source changeset. /// The type of the key. - /// The type of the objects that are allowed to pass the filter. - /// The source observable changeset of instances. - /// Indicates whether or not to suppress changesets that end up being empty after the conversion. - /// An observable changeset of where each item was either converted from or filtered out. - /// source. - /// Combines a filter and a transform into a single step that does not use an intermediate cache. + /// The destination type to filter and cast to. + /// The source to filter by type. + /// If , changesets that become empty after filtering are suppressed. + /// An observable changeset of items. + /// + /// + /// EventBehavior + /// AddIf the item is , cast and emit as Add. Otherwise dropped. + /// UpdateRe-evaluated. If the new item is , emit accordingly. If the old item was downstream but the new one is not, emit Remove. + /// RemoveIf the item was downstream, emit Remove. + /// RefreshIf the item is downstream, forwarded as Refresh. + /// OnErrorForwarded to subscribers. + /// OnCompletedForwarded to subscribers. + /// + /// + /// is . public static IObservable> OfType(this IObservable> source, bool suppressEmptyChangeSets = true) where TObject : notnull where TKey : notnull @@ -3278,9 +3854,29 @@ public static IObservable> OfType /// The type of the object. /// The type of the key. - /// The source. - /// The add action that takes the new value and the associated key. - /// An observable which emits a change set with items being added. + /// The source to observe item additions in. + /// The callback invoked for each added item. Receives the new item and its key. + /// A stream that forwards all changesets from unchanged. + /// + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddInvokes with the item and key. + /// UpdateIgnored. + /// RemoveIgnored. + /// RefreshIgnored. + /// + /// + /// + /// Exceptions thrown in propagate as OnError. No try-catch is applied. + /// + /// + /// or is . + /// + /// + /// + /// public static IObservable> OnItemAdded(this IObservable> source, Action addAction) where TObject : notnull where TKey : notnull @@ -3291,15 +3887,10 @@ public static IObservable> OnItemAdded( return source.OnChangeAction(ChangeReason.Add, addAction); } - /// - /// Callback for each item as and when it is being added to the stream. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The add action that takes the new value. - /// An observable which emits a change set with items being added. - /// Overload for with a callback that doesn't use a key. + /// + /// The source to observe item additions in. + /// The callback invoked for each added item. Receives only the item (no key). + /// Overload that omits the key from the callback. Delegates to . public static IObservable> OnItemAdded(this IObservable> source, Action addAction) where TObject : notnull where TKey : notnull @@ -3310,9 +3901,27 @@ public static IObservable> OnItemAdded( /// /// The type of the object. /// The type of the key. - /// The source. - /// The refresh action that takes the refreshed value and the key. - /// An observable which emits a change set with items being added. + /// The source to observe item refresh events in. + /// The callback invoked for each refreshed item. Receives the item and its key. + /// A stream that forwards all changesets from unchanged. + /// + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddIgnored. + /// UpdateIgnored. + /// RemoveIgnored. + /// RefreshInvokes with the item and key. + /// + /// + /// + /// Exceptions thrown in propagate as OnError. No try-catch is applied. + /// + /// + /// or is . + /// + /// public static IObservable> OnItemRefreshed(this IObservable> source, Action refreshAction) where TObject : notnull where TKey : notnull @@ -3323,34 +3932,55 @@ public static IObservable> OnItemRefreshed - /// Callback for each item as and when it is being refreshed in the stream. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The refresh action that takes the refreshed value. - /// An observable which emits a change set with items being added. - /// Overload for with a callback that doesn't use a key. + /// + /// The source to observe item refresh events in. + /// The callback invoked for each refreshed item. Receives only the item (no key). + /// Overload that omits the key from the callback. Delegates to . public static IObservable> OnItemRefreshed(this IObservable> source, Action refreshAction) where TObject : notnull where TKey : notnull => source.OnItemRefreshed((obj, _) => refreshAction(obj)); /// - /// Callback for each item/key as and when it is being removed from the stream. + /// Invokes for each item with in the changeset stream. + /// The changeset is forwarded downstream unchanged. /// /// The type of the object. /// The type of the key. - /// The source. - /// The remove action that takes the removed value and the key. - /// Should the remove action be invoked when the subscription is disposed. - /// An observable which emits a change set with items being removed. - /// - /// source - /// or - /// removeAction. - /// + /// The source to observe item removals in. + /// The callback invoked for each removed item. Receives the removed item and its key. + /// + /// When (the default), the callback is also invoked for every item still in the cache + /// when the subscription is disposed. When , only inline Remove changes trigger the callback. + /// + /// A stream that forwards all changesets from unchanged. + /// + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddIgnored (but tracked internally when is ). + /// UpdateIgnored (cache updated internally when is ). + /// RemoveInvokes with the item and key. + /// RefreshIgnored. + /// + /// + /// + /// Unsubscribe behavior: when is , the operator + /// maintains an internal cache mirroring the stream. On disposal, it iterates all remaining items and + /// invokes for each. This is useful for cleanup logic (e.g. event unsubscription) + /// that must run for items that were never explicitly removed. + /// + /// + /// Exceptions thrown in propagate as OnError during inline removes. + /// During unsubscribe disposal, exceptions are not caught. + /// + /// Worth noting: The action also fires for ALL remaining items when the subscription is disposed (unless invokeOnUnsubscribe is ). The action runs under a lock; avoid calling into other caches from within it. + /// + /// or is . + /// + /// + /// public static IObservable> OnItemRemoved(this IObservable> source, Action removeAction, bool invokeOnUnsubscribe = true) where TObject : notnull where TKey : notnull @@ -3366,34 +3996,43 @@ public static IObservable> OnItemRemoved - /// Callback for each item as and when it is being removed from the stream. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The remove action that takes the removed value. - /// Should the remove action be invoked when the subscription is disposed. - /// An observable which emits a change set with items being removed. - /// - /// source - /// or - /// removeAction. - /// - /// Overload for with a callback that doesn't use the key. + /// + /// The source to observe item removals in. + /// The callback invoked for each removed item. Receives only the item (no key). + /// When (the default), also invoked for all remaining items on disposal. + /// Overload that omits the key from the callback. Delegates to . public static IObservable> OnItemRemoved(this IObservable> source, Action removeAction, bool invokeOnUnsubscribe = true) where TObject : notnull where TKey : notnull => source.OnItemRemoved((obj, _) => removeAction(obj), invokeOnUnsubscribe); /// - /// Callback when an item has been updated eg. (current, previous)=>{}. + /// Invokes for each item with in the changeset stream. + /// The changeset is forwarded downstream unchanged. /// /// The type of the object. /// The type of the key. - /// The source. - /// The update action that takes current value, previous value, and the key. - /// An observable which emits a change set with items being updated. + /// The source to observe item updates in. + /// The callback invoked for each updated item. Receives the current value, previous value, and key. + /// A stream that forwards all changesets from unchanged. + /// + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddIgnored. + /// UpdateInvokes with (current, previous, key). The previous value is always available for Update changes. + /// RemoveIgnored. + /// RefreshIgnored. + /// + /// + /// + /// Exceptions thrown in propagate as OnError. No try-catch is applied. + /// + /// + /// or is . + /// + /// public static IObservable> OnItemUpdated(this IObservable> source, Action updateAction) where TObject : notnull where TKey : notnull @@ -3404,33 +4043,44 @@ public static IObservable> OnItemUpdated change.Reason == ChangeReason.Update, change => updateAction(change.Current, change.Previous.Value, change.Key)); } - /// - /// Callback when an item has been updated eg. (current, previous)=>{}. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The update action that takes the current value and previous value. - /// An observable which emits a change set with items being updated. - /// Overload for with a callback that doesn't use the key. + /// + /// The source to observe item updates in. + /// The callback invoked for each updated item. Receives only the current and previous values (no key). + /// Overload that omits the key from the callback. Delegates to . public static IObservable> OnItemUpdated(this IObservable> source, Action updateAction) where TObject : notnull where TKey : notnull => source.OnItemUpdated((cur, prev, _) => updateAction(cur, prev)); /// - /// Apply a logical Or operator between the collections i.e items which are in any of the sources are included. + /// Combines multiple changeset streams using logical OR (union). An item appears downstream if it exists in any source. /// /// The type of the object. /// The type of the key. - /// The source. - /// The others. - /// An observable which emits change sets. - /// - /// source - /// or - /// others. - /// + /// The source to combine. + /// The additional streams to combine with. + /// A changeset stream containing items present in any of the sources. + /// + /// + /// Items are tracked via reference counting across all sources. An item appears downstream as long as + /// at least one source contains it. When the last source holding a key removes it, the item is removed downstream. + /// + /// + /// EventBehavior + /// AddIf this is the first source to provide the key, an Add is emitted. If other sources already have the key, the reference count is incremented but no emission occurs. + /// UpdateIf the item is currently downstream, an Update is emitted. + /// RemoveReference count decremented. If the count reaches zero (no source holds the key), a Remove is emitted. Otherwise no emission. + /// RefreshIf the item is downstream, a Refresh is forwarded. + /// OnErrorAn error from any source terminates the combined output. + /// OnCompletedThe output completes when all sources have completed. + /// + /// + /// or is . + /// + /// + /// + /// + /// public static IObservable> Or(this IObservable> source, params IObservable>[] others) where TObject : notnull where TKey : notnull @@ -3445,18 +4095,9 @@ public static IObservable> Or(this IObs return source.Combine(CombineOperator.Or, others); } - /// - /// Apply a logical Or operator between the collections i.e items which are in any of the sources are included. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// An observable which emits change sets. - /// - /// source - /// or - /// others. - /// + /// + /// The of streams to combine. + /// This overload accepts a pre-built collection of sources instead of a params array. public static IObservable> Or(this ICollection>> sources) where TObject : notnull where TKey : notnull @@ -3472,7 +4113,7 @@ public static IObservable> Or(this ICol /// /// The type of the object. /// The type of the key. - /// The source. + /// The of streams to combine. /// An observable which emits change sets. public static IObservable> Or(this IObservableList>> sources) where TObject : notnull @@ -3489,7 +4130,7 @@ public static IObservable> Or(this IObs /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> Or(this IObservableList> sources) where TObject : notnull @@ -3506,7 +4147,7 @@ public static IObservable> Or(this IObs /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits change sets. public static IObservable> Or(this IObservableList> sources) where TObject : notnull @@ -3518,18 +4159,19 @@ public static IObservable> Or(this IObs } /// - /// Populate a cache from an observable stream. + /// Subscribes to the observable and calls AddOrUpdate on the source cache for each emitted batch of items. /// /// The type of the object. /// The type of the key. - /// The source. - /// The observable. - /// A disposable which will unsubscribe from the source. - /// - /// source - /// or - /// keySelector. - /// + /// The to operate on. + /// The that emits batches of items. + /// An that, when disposed, unsubscribes from . + /// + /// Each emission from is passed to , producing one changeset per emission containing Add or Update events for each item. Errors from propagate and terminate the subscription. Completion ends the subscription; the cache retains all items. + /// + /// or is . + /// + /// public static IDisposable PopulateFrom(this ISourceCache source, IObservable> observable) where TObject : notnull where TKey : notnull @@ -3540,18 +4182,14 @@ public static IDisposable PopulateFrom(this ISourceCache - /// Populate a cache from an observable stream. + /// Subscribes to the observable and calls AddOrUpdate on the source cache for each emitted item. /// /// The type of the object. /// The type of the key. - /// The source. - /// The observable. - /// A disposable which will unsubscribe from the source. - /// - /// source - /// or - /// keySelector. - /// + /// The to operate on. + /// The that emits individual items. + /// An that, when disposed, unsubscribes from . + /// or is . public static IDisposable PopulateFrom(this ISourceCache source, IObservable observable) where TObject : notnull where TKey : notnull @@ -3562,18 +4200,30 @@ public static IDisposable PopulateFrom(this ISourceCache - /// Populates a source into the specified cache. + /// Subscribes to the changeset stream and clones each changeset into the destination cache. /// /// The type of the object. /// The type of the key. - /// The source. - /// The destination. - /// A disposable which will unsubscribe from the source. - /// - /// source - /// or - /// destination. - /// + /// The source to pipe into a target cache. + /// The that will receive the changes. + /// An that, when disposed, unsubscribes from the source. + /// + /// + /// Each changeset from the source is applied to the destination cache inside an Edit call. + /// + /// + /// EventBehavior + /// AddThe item is added to the destination cache via AddOrUpdate. + /// UpdateThe item is updated in the destination cache via AddOrUpdate. + /// RemoveThe item is removed from the destination cache. + /// RefreshA Refresh is issued on the destination cache for the item. + /// OnErrorThe subscription is terminated. The destination cache is not rolled back. + /// OnCompletedThe subscription ends. The destination cache retains all items. + /// + /// + /// or is . + /// + /// public static IDisposable PopulateInto(this IObservable> source, ISourceCache destination) where TObject : notnull where TKey : notnull @@ -3584,17 +4234,10 @@ public static IDisposable PopulateInto(this IObservable destination.Edit(updater => updater.Clone(changes))); } - /// - /// Populates a source into the specified cache. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The destination. - /// A disposable which will unsubscribe from the source. - /// source - /// or - /// destination. + /// + /// The source to pipe into a target cache. + /// The that will receive the changes. + /// Overload that targets an . public static IDisposable PopulateInto(this IObservable> source, IIntermediateCache destination) where TObject : notnull where TKey : notnull @@ -3605,14 +4248,10 @@ public static IDisposable PopulateInto(this IObservable destination.Edit(updater => updater.Clone(changes))); } - /// - /// Populates a source into the specified cache. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The destination. - /// A disposable which will unsubscribe from the source. + /// + /// The source to pipe into a target cache. + /// The that will receive the changes. + /// Overload that targets a . public static IDisposable PopulateInto(this IObservable> source, LockFreeObservableCache destination) where TObject : notnull where TKey : notnull @@ -3624,19 +4263,31 @@ public static IDisposable PopulateInto(this IObservable - /// The latest copy of the cache is exposed for querying after each modification to the underlying data. + /// Projects the current cache state through after each modification. + /// Emits a new value of on every changeset. /// /// The type of the object. /// The type of the key. /// The type of the destination. - /// The source. - /// The result selector. - /// An observable which emits the destination values. - /// - /// source - /// or - /// resultSelector. - /// + /// The source to project on each change. + /// A function that projects the current snapshot to a result value. + /// An observable that emits a projected value after each changeset. + /// + /// + /// EventBehavior + /// AddCache updated, then invoked and result emitted. + /// UpdateCache updated, then invoked and result emitted. + /// RemoveCache updated, then invoked and result emitted. + /// RefreshCache updated, then invoked and result emitted. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: The selector is called on every changeset, which can be chatty. The exposes the full cache state for LINQ-style queries. + /// + /// or is . + /// + /// + /// public static IObservable QueryWhenChanged(this IObservable> source, Func, TDestination> resultSelector) where TObject : notnull where TKey : notnull @@ -3652,7 +4303,7 @@ public static IObservable QueryWhenChanged /// The type of the object. /// The type of the key. - /// The source. + /// The source to project on each change. /// An observable which emits the query. /// source. public static IObservable> QueryWhenChanged(this IObservable> source) @@ -3670,8 +4321,8 @@ public static IObservable> QueryWhenChanged /// The type of the object. /// The type of the key. /// The type of the value. - /// The source. - /// Should the query be triggered for observables on individual items. + /// The source to project on each change. + /// A that should the query be triggered for observables on individual items. /// An observable that emits the query. /// source. public static IObservable> QueryWhenChanged(this IObservable> source, Func> itemChangedTrigger) @@ -3685,12 +4336,14 @@ public static IObservable> QueryWhenChanged - /// Cache equivalent to Publish().RefCount(). The source is cached so long as there is at least 1 subscriber. + /// Cache-aware equivalent of Publish().RefCount(). An internal cache is created on the first subscriber + /// and disposed when the last subscriber unsubscribes. All subscribers share the same upstream subscription. /// /// The type of the object. - /// The type of the destination key. - /// The source. - /// An observable which emits change sets that are ref counted. + /// The type of the key. + /// The source to share via reference counting. + /// A ref-counted observable changeset stream. + /// public static IObservable> RefCount(this IObservable> source) where TObject : notnull where TKey : notnull @@ -3701,13 +4354,23 @@ public static IObservable> RefCount(thi } /// - /// Signal observers to re-evaluate the specified item. + /// Signals downstream operators to re-evaluate the specified item. Produces a changeset with a single Refresh change. /// /// The type of the object. /// The type of the key. - /// The source. - /// The item. - /// source. + /// The to signal re-evaluation on. + /// The item to refresh. + /// + /// Convenience method that wraps a Refresh inside . A Refresh does not change data in the cache; it signals downstream operators (such as or ) to re-evaluate the item. + /// + /// EventBehavior + /// RefreshProduced for the specified item. Downstream operators re-evaluate this item against their current logic (filter predicate, sort comparer, group key selector, etc.). + /// OtherNo Add, Update, or Remove events are produced by this method. + /// + /// + /// is . + /// + /// public static void Refresh(this ISourceCache source, TObject item) where TObject : notnull where TKey : notnull @@ -3718,13 +4381,13 @@ public static void Refresh(this ISourceCache sourc } /// - /// Signal observers to re-evaluate the specified items. + /// Signals downstream operators to re-evaluate the specified items. Produces one changeset with a Refresh for each item. /// /// The type of the object. /// The type of the key. - /// The source. - /// The items. - /// source. + /// The to signal re-evaluation on. + /// The of items to refresh. + /// is . public static void Refresh(this ISourceCache source, IEnumerable items) where TObject : notnull where TKey : notnull @@ -3735,12 +4398,12 @@ public static void Refresh(this ISourceCache sourc } /// - /// Signal observers to re-evaluate the all items. + /// Signals downstream operators to re-evaluate all items in the cache. Produces one changeset with a Refresh for every item. /// /// The type of the object. /// The type of the key. - /// The source. - /// source. + /// The to signal re-evaluation on. + /// is . public static void Refresh(this ISourceCache source) where TObject : notnull where TKey : notnull @@ -3751,14 +4414,24 @@ public static void Refresh(this ISourceCache sourc } /// - /// Removes the specified item from the cache. - /// If the item is not contained in the cache then the operation does nothing. + /// Removes the specified item from the cache. Produces a Remove changeset if the item exists, nothing otherwise. /// /// The type of the object. /// The type of the key. - /// The source. - /// The item. - /// source. + /// The from which to remove items. + /// The item to remove. + /// + /// Convenience method that wraps a single-item removal inside . The key is extracted from the item using the cache's key selector. + /// + /// EventBehavior + /// RemoveProduced if the key exists in the cache. The removed value is included in the changeset. + /// OtherNo Add, Update, or Refresh events are produced by this method. + /// + /// + /// is . + /// + /// + /// public static void Remove(this ISourceCache source, TObject item) where TObject : notnull where TKey : notnull @@ -3769,14 +4442,13 @@ public static void Remove(this ISourceCache source } /// - /// Removes the specified key from the cache. - /// If the item is not contained in the cache then the operation does nothing. + /// Removes the item with the specified key from the cache. Produces a Remove changeset if the key exists, nothing otherwise. /// /// The type of the object. /// The type of the key. - /// The source. - /// The key. - /// source. + /// The from which to remove items. + /// The key of the item to remove. + /// is . public static void Remove(this ISourceCache source, TKey key) where TObject : notnull where TKey : notnull @@ -3787,14 +4459,14 @@ public static void Remove(this ISourceCache source } /// - /// Removes the specified items from the cache. - /// Any items not contained in the cache are ignored. + /// Removes the specified items from the cache. Any items not present in the cache are ignored. + /// Produces a Remove changeset for each item that existed. /// /// The type of the object. /// The type of the key. - /// The source. - /// The items. - /// source. + /// The from which to remove items. + /// The of items to remove. + /// is . public static void Remove(this ISourceCache source, IEnumerable items) where TObject : notnull where TKey : notnull @@ -3805,14 +4477,14 @@ public static void Remove(this ISourceCache source } /// - /// Removes the specified keys from the cache. - /// Any keys not contained in the cache are ignored. + /// Removes the items with the specified keys from the cache. Any keys not present are ignored. + /// Produces a Remove changeset for each key that existed. /// /// The type of the object. /// The type of the key. - /// The source. - /// The keys. - /// source. + /// The from which to remove items. + /// The keys to remove. + /// is . public static void Remove(this ISourceCache source, IEnumerable keys) where TObject : notnull where TKey : notnull @@ -3822,15 +4494,10 @@ public static void Remove(this ISourceCache source source.Edit(updater => updater.Remove(keys)); } - /// - /// Removes the specified key from the cache. - /// If the item is not contained in the cache then the operation does nothing. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The key. - /// source. + /// + /// The from which to remove items. + /// The key of the item to remove. + /// Overload that targets an . public static void Remove(this IIntermediateCache source, TKey key) where TObject : notnull where TKey : notnull @@ -3840,15 +4507,10 @@ public static void Remove(this IIntermediateCache source.Edit(updater => updater.Remove(key)); } - /// - /// Removes the specified keys from the cache. - /// Any keys not contained in the cache are ignored. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The keys. - /// source. + /// + /// The from which to remove items. + /// The keys to remove. + /// Overload that targets an . public static void Remove(this IIntermediateCache source, IEnumerable keys) where TObject : notnull where TKey : notnull @@ -3859,15 +4521,15 @@ public static void Remove(this IIntermediateCache } /// - /// Removes the key which enables all observable list features of dynamic data. + /// Strips the key from a cache changeset, converting to + /// (list changeset). All indexed changes are dropped (sorting is not supported). /// - /// - /// All indexed changes are dropped i.e. sorting is not supported by this function. - /// - /// The type of object. - /// The type of key. - /// The source. - /// An observable which emits change sets. + /// The type of the object. + /// The type of the key. + /// The source to strip keys from, producing an unkeyed list changeset. + /// A list changeset stream without key information. + /// + /// public static IObservable> RemoveKey(this IObservable> source) where TObject : notnull where TKey : notnull @@ -3883,14 +4545,13 @@ public static IObservable> RemoveKey(this IOb } /// - /// Removes the specified key from the cache. - /// If the item is not contained in the cache then the operation does nothing. + /// Removes a specific key from the cache. Equivalent to source.Edit(u => u.RemoveKey(key)). /// /// The type of the object. /// The type of the key. - /// The source. - /// The key. - /// source. + /// The from which to remove a key. + /// The key to remove. + /// is . public static void RemoveKey(this ISourceCache source, TKey key) where TObject : notnull where TKey : notnull @@ -3901,14 +4562,13 @@ public static void RemoveKey(this ISourceCache sou } /// - /// Removes the specified keys from the cache. - /// Any keys not contained in the cache are ignored. + /// Removes multiple keys from the cache in a single Edit call. Keys not present in the cache are ignored. /// /// The type of the object. /// The type of the key. - /// The source. - /// The keys. - /// source. + /// The from which to remove keys. + /// The keys to remove. + /// is . public static void RemoveKeys(this ISourceCache source, IEnumerable keys) where TObject : notnull where TKey : notnull @@ -3918,19 +4578,12 @@ public static void RemoveKeys(this ISourceCache so source.Edit(updater => updater.RemoveKeys(keys)); } - /// - /// Joins the left and right observable data sources, taking all right values and combining any matching left values. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the optional left and right values into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> RightJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TRight, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -3947,18 +4600,48 @@ public static IObservable> RightJoin - /// Joins the left and right observable data sources, taking all right values and combining any matching left values. + /// Joins two changeset streams, producing a result for every right-side key. The left side is + /// because a matching left item may or may not exist. All right items + /// appear in the output regardless. Equivalent to SQL RIGHT OUTER JOIN. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the right key, optional left, and right value into a destination object. Example: (rightKey, left, right) => new Result(rightKey, left, right). + /// An observable changeset keyed by . + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddAlways emits. Invokes with the matching left (or ) and the right value. + /// UpdateRe-invokes the selector with current left (if any) and the new right value. + /// RemoveRemoves the joined result. + /// RefreshForwarded as Refresh on the joined result. + /// + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddIf matching right items exist, re-invokes the selector (left transitions from None to Some) and emits Updates. + /// UpdateIf matching right items exist, re-invokes the selector with the new left value. + /// RemoveIf matching right items exist, re-invokes the selector (left transitions from Some to None) and emits Updates. + /// RefreshIf joined results exist, forwarded as Refresh. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> RightJoin(this IObservable> left, IObservable> right, Func rightKeySelector, Func, TRight, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -3974,20 +4657,12 @@ public static IObservable> RightJoin(left, right, rightKeySelector, resultSelector).Run(); } - /// - /// Groups the right data source and joins the two sources matching them using the specified key selector, , taking all right values and combining any matching left values. - /// This is the equivalent of SQL left join. - /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the optional left value and the right group into a destination object. The key is not provided in this overload. + /// Overload that omits the key from the result selector. Delegates to . public static IObservable> RightJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, IGrouping, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -4004,19 +4679,49 @@ public static IObservable> RightJoinMany - /// Groups the right data source and joins the two sources matching them using the specified key selector,, taking all right values and combining any matching left values. - /// This is the equivalent of SQL left join. + /// Groups right-side items by their mapped key, then right-joins each group to the left source. + /// A result is produced for every key that has at least one right item. The left value is + /// because a matching left item may or may not exist. + /// Equivalent to SQL RIGHT OUTER JOIN with the right side grouped. /// - /// The object type of the left data source. - /// The key type of the left data source. - /// The object type of the right data source. - /// The key type of the right data source. - /// The resulting object which. - /// The left data source. - /// The right data source. - /// Specify the foreign key on the right data source. - /// The result selector.used to transform the combined data into. Example (key, left, right) => new CustomObject(key, left, right). - /// An observable which will emit change sets. + /// The item type of the left source. + /// The key type of the left source. + /// The item type of the right source. + /// The key type of the right source. + /// The type produced by . + /// The left to join. + /// The right to join. + /// A that maps each right item to the left key it should join on. + /// A that combines the key, optional left value, and right group into a destination object. Example: (key, left, group) => new Result(key, left, group). + /// An observable changeset keyed by . + /// + /// + /// Right-side change handling: + /// + /// EventBehavior + /// AddUpdates the right group. If the group was previously empty, emits an Add with the current left (if any). Otherwise emits an Update. + /// UpdateUpdates the right group and re-invokes . + /// RemoveUpdates the right group. If the group becomes empty, removes the joined result. + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// + /// Left-side change handling: + /// + /// EventBehavior + /// AddIf a non-empty right group exists, re-invokes the selector (left transitions from None to Some) and emits an Update. + /// UpdateIf a non-empty right group exists, re-invokes the selector with the new left value. + /// RemoveIf a non-empty right group exists, re-invokes the selector (left transitions from Some to None) and emits an Update. + /// RefreshIf a joined result exists, forwarded as Refresh. + /// + /// + /// Both sources are serialized through a shared lock held during downstream delivery. Avoid blocking operations in subscribers. + /// + /// Any argument is . + /// + /// + /// + /// public static IObservable> RightJoinMany(this IObservable> left, IObservable> right, Func rightKeySelector, Func, IGrouping, TDestination> resultSelector) where TLeft : notnull where TLeftKey : notnull @@ -4033,13 +4738,16 @@ public static IObservable> RightJoinMany - /// Defer the subscription until loaded and skip initial change set. + /// Skips the initial snapshot changeset that Connect() typically emits, then forwards all subsequent changesets. + /// Internally uses DeferUntilLoaded().Skip(1). /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits change sets. - /// source. + /// The source to skip the initial changeset. + /// An observable that skips the first changeset and forwards all others. + /// is . + /// + /// public static IObservable> SkipInitial(this IObservable> source) where TObject : notnull where TKey : notnull @@ -4050,15 +4758,13 @@ public static IObservable> SkipInitial( } /// - /// Sorts using the specified comparer. - /// Returns the underlying ChangeSet as per the system conventions. - /// The resulting change set also exposes a sorted key value collection of the underlying cached data. + /// Obsolete: use SortAndBind instead. Sorts using the specified comparer. /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer. - /// Sort optimisation flags. Specify one or more sort optimisations. + /// The source to sort. + /// The used to determine sort order. + /// A that sort optimisation flags. Specify one or more sort optimisations. /// The number of updates before the entire list is resorted (rather than inline sort). /// An observable which emits change sets. /// @@ -4066,6 +4772,7 @@ public static IObservable> SkipInitial( /// or /// comparer. /// + /// [Obsolete(Constants.SortIsObsolete)] public static IObservable> Sort(this IObservable> source, IComparer comparer, SortOptimisations sortOptimisations = SortOptimisations.None, int resetThreshold = DefaultSortResetThreshold) where TObject : notnull @@ -4078,13 +4785,13 @@ public static IObservable> Sort(t } /// - /// Sorts a sequence as, using the comparer observable to determine order. + /// Obsolete: use SortAndBind instead. Sorts using a dynamic comparer observable. /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer observable. - /// The sort optimisations. + /// The source to sort. + /// The comparer observable. + /// The sort optimisations. /// The reset threshold. /// An observable which emits change sets. [Obsolete(Constants.SortIsObsolete)] @@ -4099,14 +4806,14 @@ public static IObservable> Sort(t } /// - /// Sorts a sequence as, using the comparer observable to determine order. + /// Obsolete: use SortAndBind instead. Sorts using a dynamic comparer observable with a manual re-sort signal. /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer observable. - /// Signal to instruct the algorithm to re-sort the entire data set. - /// The sort optimisations. + /// The source to sort. + /// The comparer observable. + /// An that signals the algorithm to re-sort the entire data set. + /// The sort optimisations. /// The reset threshold. /// An observable which emits change sets. [Obsolete(Constants.SortIsObsolete)] @@ -4121,14 +4828,14 @@ public static IObservable> Sort(t } /// - /// Sorts a sequence as, using the comparer observable to determine order. + /// Obsolete: use SortAndBind instead. Sorts using a static comparer with a manual re-sort signal. /// /// The type of the object. /// The type of the key. - /// The source. - /// The comparer to sort on. - /// Signal to instruct the algorithm to re-sort the entire data set. - /// The sort optimisations. + /// The source to sort. + /// The used to determine sort order. + /// An that signals the algorithm to re-sort the entire data set. + /// The sort optimisations. /// The reset threshold. /// An observable which emits change sets. [Obsolete(Constants.SortIsObsolete)] @@ -4143,16 +4850,18 @@ public static IObservable> Sort(t } /// - /// Sorts a sequence by selected property. + /// Sorts the changeset stream by the value returned from . Creates a comparer internally + /// and delegates to . + /// Since Sort is obsolete, prefer SortAndBind for new code. /// /// The type of the object. /// The type of the key. - /// The source. - /// The expression. - /// The sort order. Defaults to ascending. - /// The sort optimisations. - /// The reset threshold. - /// An observable which emits change sets. + /// The source to sort. + /// A that expression that selects a comparable value from each item. + /// The sort direction. Defaults to ascending. + /// A that sort optimization flags. + /// The number of updates before the entire list is re-sorted (rather than inline sort). + /// An observable that emits sorted changesets. public static IObservable> SortBy( this IObservable> source, Func expression, @@ -4176,91 +4885,76 @@ public static IObservable> SortBy } /// - /// Prepends an empty change set to the source. + /// Prepends an empty changeset to the source stream, ensuring subscribers always receive an immediate + /// (empty) notification on subscription. Uses Rx's StartWith. /// - /// The object of the change set. - /// The key of the change set. - /// The source observable change set. - /// An observable which emits change sets. + /// The type of the object. + /// The type of the key. + /// The source to prepend an empty changeset to. + /// An observable that emits an empty changeset first, then all source changesets. public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull => source.StartWith(ChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// - /// The object of the change set. - /// The key of the change set. - /// The source observable change set. - /// An observable which emits sorted change sets. + /// + /// The source to prepend an empty changeset to. + /// An observable that emits an empty sorted changeset first, then all source changesets. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull => source.StartWith(SortedChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// - /// The object of the change set. - /// The key of the change set. - /// The source observable change set. - /// An observable which emits virtual change sets. + /// + /// The source to prepend an empty changeset to. + /// An observable that emits an empty virtual changeset first, then all source changesets. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull => source.StartWith(VirtualChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// - /// The object of the change set. - /// The key of the change set. - /// The source observable change set. - /// An observable which emits paged change sets. + /// + /// The source to prepend an empty changeset to. + /// An observable that emits an empty paged changeset first, then all source changesets. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull => source.StartWith(PagedChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// - /// The object of the change set. - /// The key of the change set. - /// The grouping key type. - /// The source observable change set. - /// An observable which emits group change sets. + /// + /// The type of the object. + /// The type of the key. + /// The grouping key type. + /// The source to prepend an empty changeset to. + /// An observable that emits an empty group changeset first, then all source changesets. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull where TGroupKey : notnull => source.StartWith(GroupChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// - /// The object of the change set. - /// The key of the change set. + /// + /// The type of the object. + /// The type of the key. /// The grouping key type. - /// The source observable change set. - /// An observable which emits immutable group change sets. + /// The source to prepend an empty changeset to. + /// An observable that emits an empty immutable group changeset first, then all source changesets. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull where TGroupKey : notnull => source.StartWith(ImmutableGroupChangeSet.Empty); - /// - /// Prepends an empty change set to the source. - /// + /// /// The type of the item. - /// The source read only collection. - /// A read only collection. + /// The source of to prepend an empty changeset to. + /// An observable that emits an empty collection first, then all source collections. + /// Overload for . public static IObservable> StartWithEmpty(this IObservable> source) => source.StartWith(ReadOnlyCollectionLight.Empty); - /// - /// The equivalent of rx StartsWith operator, but wraps the item in a change where reason is ChangeReason.Add. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The item. - /// An observable which emits change sets. + /// + /// The source to prepend an initial item to. + /// The item to prepend. The key is extracted from . + /// Overload for items that implement . Delegates to the explicit key overload. public static IObservable> StartWithItem(this IObservable> source, TObject item) where TObject : IKey where TKey : notnull @@ -4271,14 +4965,15 @@ public static IObservable> StartWithItem - /// The equivalent of rx StartWith operator, but wraps the item in a change where reason is ChangeReason.Add. + /// Prepends a changeset containing a single Add for the given item and key to the source stream. + /// The Rx equivalent of StartWith, but wrapped as a DynamicData changeset. /// /// The type of the object. /// The type of the key. - /// The source. - /// The item. - /// The key. - /// An observable which emits change sets. + /// The source to prepend an initial item to. + /// The item to prepend. + /// The key for the item. + /// An observable that emits a single-item Add changeset first, then all source changesets. public static IObservable> StartWithItem(this IObservable> source, TObject item, TKey key) where TObject : notnull where TKey : notnull @@ -4290,19 +4985,39 @@ public static IObservable> StartWithItem - /// Subscribes to each item when it is added to the stream and un-subscribes when it is removed. All items will be unsubscribed when the stream is disposed. + /// Creates an subscription per item via . + /// Subscriptions are created on Add/Update and disposed on Update/Remove. All active subscriptions + /// are disposed when the stream completes, errors, or the subscription is disposed. /// /// The type of the object. /// The type of the key. - /// The source. - /// The subscription function. - /// An observable which emits a change set. - /// source - /// or - /// subscriptionFactory. + /// The source to create a subscription for each item in. + /// A factory that creates an for each item. Called on Add and Update (for the new value). + /// A stream that forwards all changesets from unchanged. /// - /// Subscribes to each item when it is added or updates and un-subscribes when it is removed. + /// + /// Change reason handling: + /// + /// EventBehavior + /// AddCalls , stores the returned . + /// UpdateDisposes the previous subscription, then calls for the new value. + /// RemoveDisposes the subscription for the removed item. + /// RefreshPassed through. No subscription change. + /// + /// + /// + /// Internally implemented using + /// and , so disposal semantics match . + /// + /// + /// Use this to tie per-item side effects (event subscriptions, polling timers, child observable subscriptions) + /// to the lifecycle of items in the cache. + /// /// + /// or is . + /// + /// + /// public static IObservable> SubscribeMany(this IObservable> source, Func subscriptionFactory) where TObject : notnull where TKey : notnull @@ -4313,20 +5028,10 @@ public static IObservable> SubscribeMany(source, subscriptionFactory).Run(); } - /// - /// Subscribes to each item when it is added to the stream and unsubscribes when it is removed. All items will be unsubscribed when the stream is disposed. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The subscription function. - /// An observable which emits a change set. - /// source - /// or - /// subscriptionFactory. - /// - /// Subscribes to each item when it is added or updates and unsubscribes when it is removed. - /// + /// + /// The source to create a subscription for each item in. + /// A factory that creates an for each item. Receives the item and its key. + /// Overload whose factory receives both the item and the key. See for full details. public static IObservable> SubscribeMany(this IObservable> source, Func subscriptionFactory) where TObject : notnull where TKey : notnull @@ -4342,24 +5047,15 @@ public static IObservable> SubscribeMany /// The object of the change set. /// The key of the change set. - /// The source observable change set. + /// The source to strip refresh events. /// An observable which emits change sets. public static IObservable> SuppressRefresh(this IObservable> source) where TObject : notnull where TKey : notnull => source.WhereReasonsAreNot(ChangeReason.Refresh); - /// - /// Transforms an observable sequence of observable caches into a single sequence - /// producing values only from the most recent observable sequence. - /// Each time a new inner observable sequence is received, unsubscribe from the - /// previous inner observable sequence and clear the existing result set. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// - /// The observable sequence that at any point in time produces the elements of the most recent inner observable sequence that has been received. - /// + /// + /// An observable that emits instances. + /// Overload that accepts observable caches. Internally calls Connect() on each cache and delegates to the changeset overload. public static IObservable> Switch(this IObservable> sources) where TObject : notnull where TKey : notnull @@ -4370,17 +5066,26 @@ public static IObservable> Switch(this } /// - /// Transforms an observable sequence of observable changes sets into an observable sequence - /// producing values only from the most recent observable sequence. - /// Each time a new inner observable sequence is received, unsubscribe from the - /// previous inner observable sequence and clear the existing result set. + /// Subscribes to the latest inner changeset stream, unsubscribing from the previous one on each switch. + /// When switching, the old source's items are removed and the new source's items are added. /// /// The type of the object. /// The type of the key. - /// The source. - /// - /// The observable sequence that at any point in time produces the elements of the most recent inner observable sequence that has been received. - /// + /// An of changeset streams. The operator subscribes to the latest inner stream. + /// A changeset stream reflecting the items from the most recently emitted inner source. + /// + /// + /// EventBehavior + /// AddForwarded from the active inner source. + /// UpdateForwarded from the active inner source. + /// RemoveForwarded from the active inner source. + /// RefreshForwarded from the active inner source. + /// OnErrorAn error from any inner source or the outer source terminates the stream. + /// OnCompletedCompletes when the outer source and the current inner source have both completed. + /// + /// On switch: Remove is emitted for all items from the previous source, then Add for all items from the new source. + /// Worth noting: Each switch clears the entire downstream cache before populating from the new source. Subscribers see a full remove-then-add reset on every switch. + /// public static IObservable> Switch(this IObservable>> sources) where TObject : notnull where TKey : notnull @@ -4395,27 +5100,26 @@ public static IObservable> Switch(this /// /// The type of the object. /// The type of the key. - /// The source. + /// The source to materialize into a collection on each change. /// An observable which emits the read only collection. public static IObservable> ToCollection(this IObservable> source) where TObject : notnull where TKey : notnull => source.QueryWhenChanged(query => new ReadOnlyCollectionLight(query.Items)); /// - /// Converts the observable to an observable change set. - /// Change set observes observable change events. + /// Bridges a standard Rx observable of individual items into a DynamicData changeset stream. + /// Each emission becomes an Add (or Update if the key already exists). + /// Supports optional per-item expiration and size limiting. /// /// The type of the object. /// The type of the key. - /// The source. - /// The key selector. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// Remove the oldest items when the size has reached this limit. - /// The scheduler (only used for time expiry). - /// An observable which will emit changes. - /// source - /// or - /// keySelector. + /// The source to convert into a keyed changeset stream. + /// A that selects the unique key for each item. + /// An optional that specifies per-item expiration time. Return for no expiration. + /// The maximum cache size. Oldest items are removed when exceeded. Use -1 for no limit. + /// An optional for expiration timing. + /// An observable changeset stream. + /// or is . public static IObservable> ToObservableChangeSet( this IObservable source, Func keySelector, @@ -4437,20 +5141,19 @@ public static IObservable> ToObservableChangeSet - /// Converts the observable to an observable change set. - /// Change set observes observable change events. + /// Bridges a standard Rx observable of item batches into a DynamicData changeset stream. + /// Each batch is processed with AddOrUpdate, producing Add or Update changes per item. + /// Supports optional per-item expiration and size limiting. /// /// The type of the object. /// The type of the key. - /// The source. - /// The key selector. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// Remove the oldest items when the size has reached this limit. - /// The scheduler (only used for time expiry). - /// An observable change set. - /// source - /// or - /// keySelector. + /// The source to convert into a keyed changeset stream. + /// A that selects the unique key for each item. + /// An optional that specifies per-item expiration time. Return for no expiration. + /// The maximum cache size. Oldest items are removed when exceeded. Use -1 for no limit. + /// An optional for expiration timing. + /// An observable changeset stream. + /// or is . public static IObservable> ToObservableChangeSet( this IObservable> source, Func keySelector, @@ -4472,15 +5175,34 @@ public static IObservable> ToObservableChangeSet - /// Converts an observable change set into an observable optional that emits the value for the given key. + /// Watches a single key in the source changeset stream, emitting Optional.Some(value) when the key + /// is present and when it is removed. Duplicate values are suppressed via . /// /// The type of the object. /// The type of the key. - /// The source. - /// The key value. - /// Optional instance used to determine if an object value has changed. - /// An observable optional. - /// source is null. + /// The source to watch a single key in. + /// The key to watch. + /// An that optional comparer to suppress duplicate emissions. Uses default equality if . + /// An observable of that reflects the presence or absence of the specified key. + /// + /// + /// Unlike , this emits None on removal + /// (rather than the removed value), making it possible to distinguish "key is absent" from "key has a value". + /// + /// + /// EventBehavior + /// AddEmits Optional.Some(value) if the key was not previously tracked. + /// UpdateEmits Optional.Some(newValue) if the new value differs from the previous per . Otherwise suppressed. + /// RemoveEmits . + /// RefreshEmits Optional.Some(value) if the value differs from the last emission per . Otherwise suppressed. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No emission occurs if the key is not present at subscription time. To get an initial None when the key is absent, use the overload with initialOptionalWhenMissing: true. + /// + /// is . + /// + /// public static IObservable> ToObservableOptional(this IObservable> source, TKey key, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -4495,12 +5217,15 @@ public static IObservable> ToObservableOptional /// /// The type of the object. /// The type of the key. - /// The source. - /// The key value. - /// Indicates if an initial Optional None should be emitted if the value doesn't exist. - /// Optional instance used to determine if an object value has changed. + /// The source to watch a single key in. + /// The key value. + /// When , emits an initial with no value if the key is not present in the cache. + /// An optional instance used to determine if an object value has changed. /// An observable optional. /// source is null. + /// + /// Worth noting: Uses lock-based coordination. If the key exists synchronously on Connect(), the initial None may or may not be emitted depending on timing. + /// public static IObservable> ToObservableOptional(this IObservable> source, TKey key, bool initialOptionalWhenMissing, IEqualityComparer? equalityComparer = null) where TObject : notnull where TKey : notnull @@ -4525,9 +5250,9 @@ public static IObservable> ToObservableOptional /// The type of the object. /// The type of the key. /// The sort key. - /// The source. - /// The sort function. - /// The sort order. Defaults to ascending. + /// The source to materialize into a sorted collection on each change. + /// The sort function. + /// The sort order. Defaults to ascending. /// An observable which emits the read only collection. public static IObservable> ToSortedCollection(this IObservable> source, Func sort, SortDirection sortOrder = SortDirection.Ascending) where TObject : notnull @@ -4539,8 +5264,8 @@ public static IObservable> ToSortedCollection /// The type of the object. /// The type of the key. - /// The source. - /// The sort comparer. + /// The source to materialize into a sorted collection on each change. + /// The sort comparer. /// An observable which emits the read only collection. public static IObservable> ToSortedCollection(this IObservable> source, IComparer comparer) where TObject : notnull @@ -4552,21 +5277,9 @@ public static IObservable> ToSortedCollection(items); }); - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts a bool transformOnRefresh flag. When , Refresh changes cause re-transformation (emitted as Update). The factory receives only the current item. + /// public static IObservable> Transform(this IObservable> source, Func transformFactory, bool transformOnRefresh) where TDestination : notnull where TSource : notnull @@ -4578,21 +5291,8 @@ public static IObservable> Transform transformFactory(current), transformOnRefresh); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts a bool transformOnRefresh flag. When , Refresh changes cause re-transformation (emitted as Update). The factory receives the current item and key. public static IObservable> Transform(this IObservable> source, Func transformFactory, bool transformOnRefresh) where TDestination : notnull where TSource : notnull @@ -4604,21 +5304,8 @@ public static IObservable> Transform transformFactory(current, key), transformOnRefresh); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts a bool transformOnRefresh flag. When , Refresh changes cause re-transformation (emitted as Update). public static IObservable> Transform(this IObservable> source, Func, TKey, TDestination> transformFactory, bool transformOnRefresh) where TDestination : notnull where TSource : notnull @@ -4630,21 +5317,8 @@ public static IObservable> Transform(source, transformFactory, transformOnRefresh: transformOnRefresh).Run(); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts an optional forceTransform predicate filtering by source item only (without the key). The factory receives only the current item. public static IObservable> Transform(this IObservable> source, Func transformFactory, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -4656,21 +5330,8 @@ public static IObservable> Transform transformFactory(current), forceTransform?.ForForced()); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts an optional forceTransform predicate filtering by source item and key. The factory receives the current item and key. public static IObservable> Transform(this IObservable> source, Func transformFactory, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -4683,20 +5344,43 @@ public static IObservable> Transform - /// Projects each update item to a new form using the specified transform function. + /// Projects each item in the changeset to a new form using a synchronous transform factory. /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. + /// The type of the source items. + /// The type of the key. + /// The source to transform. + /// The that produces a from the current source item, the previous source item (if any), and the key. + /// An observable that, when it emits a predicate, re-transforms all items for which the predicate returns . Re-transformed items are emitted as changes. If , no forced re-transforms occur. + /// An observable changeset of transformed items. + /// + /// + /// Transform maintains a 1:1 mapping between source and destination items, keyed identically. The factory + /// is called once per Add and once per Update. Removes are forwarded without calling the factory. + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddCalls factory, emits Add. + /// UpdateCalls factory (receives current item, previous item, key), emits Update with Previous preserved. + /// RemoveEmits Remove. Factory is NOT called. + /// RefreshForwarded as Refresh without re-transforming. To re-transform on Refresh, use the parameter or the transformOnRefresh overloads. + /// + /// Worth noting: By default, Refresh does NOT re-invoke the transform factory (it is just forwarded). Set transformOnRefresh: true to re-transform on Refresh. + /// + /// When emits a predicate, every cached item is tested against it. + /// Matching items are re-transformed and emitted as Updates. + /// + /// + /// Factory exceptions propagate as , terminating the stream. + /// Use + /// to catch factory errors without killing the stream. + /// + /// + /// + /// + /// + /// or is . public static IObservable> Transform(this IObservable> source, Func, TKey, TDestination> transformFactory, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -4712,41 +5396,15 @@ public static IObservable> Transform(source, transformFactory).Run(); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for all items. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items when the observable emits. The factory receives only the current item. public static IObservable> Transform(this IObservable> source, Func transformFactory, IObservable forceTransform) where TDestination : notnull where TSource : notnull where TKey : notnull => source.Transform((cur, _, _) => transformFactory(cur), forceTransform.ForForced()); - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for all items.# - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items when the observable emits. The factory receives the current item and key. public static IObservable> Transform(this IObservable> source, Func transformFactory, IObservable forceTransform) where TDestination : notnull where TSource : notnull @@ -4759,21 +5417,8 @@ public static IObservable> Transform transformFactory(cur, key), forceTransform.ForForced()); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for all items.# - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items when the observable emits. public static IObservable> Transform(this IObservable> source, Func, TKey, TDestination> transformFactory, IObservable forceTransform) where TDestination : notnull where TSource : notnull @@ -4786,21 +5431,9 @@ public static IObservable> Transform()); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload takes a simpler factory that receives only the current item. + /// [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func> transformFactory, IObservable>? forceTransform = null) where TDestination : notnull @@ -4813,21 +5446,8 @@ public static IObservable> TransformAsync transformFactory(current), forceTransform); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload takes a factory that receives the current item and key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func> transformFactory, IObservable>? forceTransform = null) where TDestination : notnull @@ -4841,20 +5461,38 @@ public static IObservable> TransformAsync - /// Projects each update item to a new form using the specified transform function. + /// Async version of . + /// Projects each item using an async factory that returns . /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. + /// The type of the source items. + /// The type of the key. + /// The source to transform asynchronously. + /// The async function that produces a from the current source item, the previous source item (if any), and the key. + /// An observable that, when it emits a predicate, re-transforms all items for which the predicate returns . Re-transformed items are emitted as changes. If , no forced re-transforms occur. + /// An observable changeset of transformed items. + /// + /// + /// Transforms within a single changeset batch execute concurrently. The entire batch must complete + /// before the resulting changeset is emitted. Use the overloads + /// to control maximum concurrency and Refresh handling. + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddAwaits factory, emits Add. + /// UpdateAwaits factory (receives current, previous, key), emits Update. + /// RemoveEmits Remove. Factory is NOT called. + /// RefreshForwarded as Refresh by default. Use to re-transform. + /// + /// Worth noting: Transforms are batched per changeset (all tasks must complete before the next changeset is processed). Completion waits for in-flight transforms. Remove does NOT cancel in-flight transforms for the removed key. + /// + /// Factory exceptions propagate as . Use + /// + /// to catch factory errors without terminating the stream. + /// + /// + /// or is . [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func, TKey, Task> transformFactory, IObservable>? forceTransform = null) where TDestination : notnull @@ -4867,21 +5505,8 @@ public static IObservable> TransformAsync(source, transformFactory, null, forceTransform).Run(); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. The factory receives only the current item. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func> transformFactory, TransformAsyncOptions options) where TDestination : notnull @@ -4894,21 +5519,8 @@ public static IObservable> TransformAsync transformFactory(current), options); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. The factory receives the current item and key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func> transformFactory, TransformAsyncOptions options) where TDestination : notnull @@ -4921,21 +5533,8 @@ public static IObservable> TransformAsync transformFactory(current, key), options); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync(this IObservable> source, Func, TKey, Task> transformFactory, TransformAsyncOptions options) where TDestination : notnull @@ -4949,26 +5548,31 @@ public static IObservable> TransformAsync - /// Projects each update item to a new form using the specified transform function, with optimizations for stateless/deterministic transformation of immutable items. + /// Optimized transform for immutable items with deterministic (pure) transform functions. + /// Refresh changes are dropped entirely since immutable items cannot change in place. /// - /// The type of collection items produced by the transformation. - /// The type of collection items to be transformed. - /// The type of the key values of each collection item. - /// The source stream of collection items to be transformed. - /// The transformation to be applied to each item. - /// A stream of collection changesets where upstream collection items are transformed by the given factory function. + /// The type of the transformed items. + /// The type of the source items. + /// The type of the key. + /// The source to transform (items assumed immutable). + /// The pure function that maps a source item to a destination item. Must be deterministic: same input always produces equivalent output. + /// An observable changeset of transformed items. /// - /// The goal of this operator is to optimize a common use-case of reactive programming, where data values flowing through a stream are immutable, and state changes are distributed by publishing new immutable items as replacements, instead of mutating the items directly. - /// In addition to assuming that all collection items are immutable, this operator also assumes that the given transformation function is deterministic, such that the result it returns will always be equivalent each time a specific input is passed to it. In other words, the transformation itself also contains no mutable state. - /// Under these assumptions, this operator can bypass the need to keep track of every collection item that passes through it, which the normal operator must do, in order to re-evaluate transformations during a refresh operation. - /// Consider using this operator when the following are true: - /// - /// Your collection items are immutable, and changes are published by replacing entire items - /// Your transformation logic does not change over the lifetime of the stream, only the items do - /// Your transformation function runs quickly, and does not heavily allocate memory + /// + /// Because the transform is assumed to be stateless and deterministic, this operator does not track + /// previously transformed items. This reduces memory overhead compared to . + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddCalls factory, emits Add. + /// UpdateCalls factory, emits Update. + /// RemoveEmits Remove. Factory is NOT called. + /// RefreshDROPPED. Immutable items do not change, so Refresh is meaningless. /// - /// Note that, because transformation is purely deterministic, Refresh operations are transparently ignored by this operator. + /// Use this when items are immutable, the factory is pure, and the factory is cheap. If any of these conditions are false, use instead. /// + /// or is . public static IObservable> TransformImmutable( this IObservable> source, Func transformFactory) @@ -4986,67 +5590,56 @@ public static IObservable> TransformImmutable - /// Equivalent to a select many transform. To work, the key must individually identify each child. + /// Flattens each source item into zero or more destination items (1:N), producing a single flat changeset. + /// Each child item must have a globally unique key across all parents. /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Will select a enumerable of values. - /// The key selector which must be unique across all. + /// The type of the child items. + /// The type of the child item keys. + /// The type of the source (parent) items. + /// The type of the source (parent) keys. + /// The source to expand each item into multiple children. + /// A function that expands a parent item into its children. For or overloads, subsequent changes to the child collection are automatically tracked. + /// A that extracts a unique key from each child item. Keys must be unique across ALL parents, not just within one parent. + /// An observable changeset of flattened child items. + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddCalls , emits Add for each child. + /// UpdateDiffs old children vs new children: emits Remove for removed children, Add for new children, Update for children with matching keys. + /// RemoveEmits Remove for all children of the removed parent. + /// RefreshPropagated as Refresh to all children (no re-expansion). + /// + /// Worth noting: If two source items produce children with the same key, last-in-wins. Refresh does NOT re-expand children (only Update does). + /// If two parents produce children with the same key, last-in-wins. Use the async variant with a to control conflict resolution. + /// + /// , , or is . + /// + /// public static IObservable> TransformMany(this IObservable> source, Func> manySelector, Func keySelector) where TDestination : notnull where TDestinationKey : notnull where TSource : notnull where TSourceKey : notnull => new TransformMany(source, manySelector, keySelector).Run(); - /// - /// Flatten the nested observable collection, and subsequently observe observable collection changes. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Will select a enumerable of values. - /// The key selector which must be unique across all. + /// + /// This overload accepts an selector. Changes to the child collection (adds, removes, replacements) are automatically observed and reflected downstream. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, Func keySelector) where TDestination : notnull where TDestinationKey : notnull where TSource : notnull where TSourceKey : notnull => new TransformMany(source, manySelector, keySelector).Run(); - /// - /// Flatten the nested observable collection, and subsequently observe observable collection changes. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Will select a enumerable of values. - /// The key selector which must be unique across all. + /// + /// This overload accepts a selector. Changes to the child collection are automatically observed and reflected downstream. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, Func keySelector) where TDestination : notnull where TDestinationKey : notnull where TSource : notnull where TSourceKey : notnull => new TransformMany(source, manySelector, keySelector).Run(); - /// - /// Flatten the nested observable cache, and subsequently observe observable cache changes. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Will select an observable cache of values. - /// The key selector which must be unique across all. + /// + /// This overload accepts an selector. The child cache is live: subsequent changes to it are automatically propagated downstream. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, Func keySelector) where TDestination : notnull where TDestinationKey : notnull @@ -5054,19 +5647,31 @@ public static IObservable> TransformMa where TSourceKey : notnull => new TransformMany(source, manySelector, keySelector).Run(); /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. + /// Async version of . + /// Flattens each source item into zero or more destination items using an async factory. /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable changeset with the transformed values. - /// The source. - /// Async function to transform a and into an of . - /// The key selector which must be unique across all. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// The type of the child items. + /// The type of the child item keys. + /// The type of the source (parent) items. + /// The type of the source (parent) keys. + /// The source to expand each item into multiple children asynchronously. + /// An async function that expands a parent item (and its key) into an of children. + /// A that extracts a unique key from each child item. + /// An that optional comparer to determine if two child items with the same key are equal. Used to suppress no-op updates. + /// An that optional comparer to resolve key collisions when the same destination key is produced by multiple parents. The winning item is determined by this comparer. + /// An observable changeset of flattened child items. + /// + /// + /// Because each parent's expansion is async, child collections may arrive via separate changesets + /// (unlike the synchronous TransformMany which batches all children into one changeset). + /// + /// + /// Factory exceptions propagate as . Use + /// + /// to catch errors without killing the stream. + /// + /// + /// or is . [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func>> manySelector, Func keySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5080,20 +5685,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector, keySelector), equalityComparer, comparer).Run(); } - /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable changeset with the transformed values. - /// The source. - /// Async function to transform a into an of . - /// The key selector which must be unique across all. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload takes a factory that receives only the source item (without the key). [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func>> manySelector, Func keySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5102,21 +5695,8 @@ public static IObservable> TransformMa where TSource : notnull where TSourceKey : notnull => source.TransformManyAsync((val, _) => manySelector(val), keySelector, equalityComparer, comparer); - /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// The type of an observable collection of . - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a and into an of . - /// The key selector which must be unique across all. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an observable collection (of type implementing both and ) whose changes are tracked live. The factory receives the source item and its key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func> manySelector, Func keySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5131,21 +5711,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector, keySelector), equalityComparer, comparer).Run(); } - /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// The type of an observable collection of . - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a into an of . - /// The key selector which must be unique across all. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an observable collection (of type implementing both and ) whose changes are tracked live. The factory receives only the source item. [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func> manySelector, Func keySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5155,19 +5722,8 @@ public static IObservable> TransformMa where TSourceKey : notnull where TCollection : INotifyCollectionChanged, IEnumerable => source.TransformManyAsync((val, _) => manySelector(val), keySelector, equalityComparer, comparer); - /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a and into an of . - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an per parent. The child cache is live: its changes propagate downstream. No keySelector is needed since the cache already has keys. The factory receives the source item and its key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func>> manySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5181,19 +5737,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector), equalityComparer, comparer).Run(); } - /// - /// Extension method similar to except that it allows the tranformation function to be an async method. Also supports comparison and sorting to prioritize values the same destination key returned from multiple sources. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a and into an of . - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an per parent. The child cache is live. The factory receives only the source item. [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManyAsync(this IObservable> source, Func>> manySelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5203,20 +5748,23 @@ public static IObservable> TransformMa where TSourceKey : notnull => source.TransformManyAsync((val, _) => manySelector(val), equalityComparer, comparer); /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable changeset with the transformed values. - /// The source. - /// Async function to transform a and into an of . - /// The key selector which must be unique across all. - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// Async version of + /// with error handling. Factory exceptions are caught and routed to instead of + /// terminating the stream. + /// + /// The type of the child items. + /// The type of the child item keys. + /// The type of the source (parent) items. + /// The type of the source (parent) keys. + /// The source to expand each item into multiple children asynchronously with error handling. + /// An async function that expands a parent item (and its key) into an of children. + /// A that extracts a unique key from each child item. + /// A that called when throws. The faulting item is skipped and the stream continues. + /// An that optional comparer to determine if two child items with the same key are equal. + /// An that optional comparer to resolve key collisions when the same destination key is produced by multiple parents. + /// An observable changeset of flattened child items. + /// Because the transformations are asynchronous, each sub-collection may be emitted via a separate changeset. + /// , , or is . [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func>> manySelector, Func keySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5231,21 +5779,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector, keySelector), equalityComparer, comparer, errorHandler).Run(); } - /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable changeset with the transformed values. - /// The source. - /// Async function to transform a into an of . - /// The key selector which must be unique across all. - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload takes a factory that receives only the source item (without the key). [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func>> manySelector, Func keySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5254,22 +5789,8 @@ public static IObservable> TransformMa where TSource : notnull where TSourceKey : notnull => source.TransformManySafeAsync((val, _) => manySelector(val), keySelector, errorHandler, equalityComparer, comparer); - /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// The type of an observable collection of . - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a and into an of . - /// The key selector which must be unique across all. - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an observable collection (of type implementing both and ) whose changes are tracked live. The factory receives the source item and its key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func> manySelector, Func keySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5285,22 +5806,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector, keySelector), equalityComparer, comparer, errorHandler).Run(); } - /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// The type of an observable collection of . - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a into an of . - /// The key selector which must be unique across all. - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an observable collection (of type implementing both and ) whose changes are tracked live. The factory receives only the source item. [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func> manySelector, Func keySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5310,20 +5817,8 @@ public static IObservable> TransformMa where TSourceKey : notnull where TCollection : INotifyCollectionChanged, IEnumerable => source.TransformManySafeAsync((val, _) => manySelector(val), keySelector, errorHandler, equalityComparer, comparer); - /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a and into an of . - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an per parent. The child cache is live. The factory receives the source item and its key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func>> manySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TDestination : notnull @@ -5338,20 +5833,8 @@ public static IObservable> TransformMa return new TransformManyAsync(source, CreateChangeSetTransformer(manySelector), equalityComparer, comparer, errorHandler).Run(); } - /// - /// Extension method similar to except it accepts an error handler so that failed transformations are not fatal errors. - /// - /// The type of the destination. - /// The type of the destination key. - /// The type of the source. - /// The type of the source key. - /// An observable with the transformed change set. - /// The source. - /// Async function to transform a into an of . - /// Callback function for handling an errors. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// Because the transformations are asynchronous, unlike TransformMany, each sub-collection could be emitted via a separate changeset. + /// + /// This overload returns an per parent. The child cache is live. The factory receives only the source item. [MethodImpl(MethodImplOptions.AggressiveInlining)] [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformManySafeAsync(this IObservable> source, Func>> manySelector, Action> errorHandler, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) @@ -5361,19 +5844,48 @@ public static IObservable> TransformMa where TSourceKey : notnull => source.TransformManySafeAsync((val, _) => manySelector(val), errorHandler, equalityComparer, comparer); /// - /// Transforms each item in the ChangeSet into an Observable that provides the value for the Resulting ChangeSet. + /// Projects each item into a per-item observable. The latest value emitted by each item's observable + /// becomes the transformed value in the output changeset. /// - /// The type of the source changeset. + /// The type of the source items. /// The type of the key. - /// The type of the destination changeset. - /// The source changeset observable. - /// Factory function to create the Observable that will provide the values in the result changeset from the given object in the source changeset. - /// - /// A changeset whose value for a given key is the latest value emitted from the transformed Observable and will update to future values from that observable. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. + /// The source to transform using per-item observables. + /// A function that, given a source item and its key, returns an whose emissions become the transformed values. + /// An observable changeset where each key's value is the latest emission from its per-item observable. + /// + /// + /// Source changeset handling (parent events): + /// + /// + /// EventBehavior + /// AddCalls and subscribes to the returned observable. The item is not visible downstream until the observable emits its first value. + /// UpdateDisposes the old item's observable subscription and subscribes to the new item's observable. The item disappears from downstream until the new observable emits. + /// RemoveDisposes the item's observable subscription. If the item was visible downstream, a Remove is emitted. + /// RefreshForwarded as Refresh if the item is currently visible downstream. Otherwise dropped. + /// + /// + /// Per-item observable handling (transform observable events): + /// + /// + /// EmissionBehavior + /// First valueThe transformed item appears downstream as an Add. + /// Subsequent valuesEach new value replaces the previous one: an Update is emitted downstream. + /// ErrorTerminates the entire output stream. + /// CompletedThe item remains at its last emitted value. No further updates are possible for this item. + /// + /// + /// Worth noting: Items are invisible downstream until their per-item observable emits at least one value. + /// If an item's observable never emits, that item never appears in the output. The transform factory's selector + /// runs under an internal lock, so it must not synchronously access other DynamicData caches (deadlock risk in + /// cross-cache pipelines). The output completes when the source completes and all per-item observables have + /// also completed. + /// + /// + /// or is . + /// + /// + /// public static IObservable> TransformOnObservable(this IObservable> source, Func> transformFactory) where TSource : notnull where TKey : notnull @@ -5385,18 +5897,8 @@ public static IObservable> TransformOnObservable< return new TransformOnObservable(source, transformFactory).Run(); } - /// - /// Transforms each item in the ChangeSet into an Observable that provides the value for the Resulting ChangeSet. - /// - /// The type of the source changeset. - /// The type of the key. - /// The type of the destination changeset. - /// The source changeset observable. - /// Factory function to create the Observable that will provide the values in the result changeset from the given object in the source changeset. - /// - /// A changeset whose value for a given key is the latest value emitted from the transformed Observable and will update to future values from that observable. - /// - /// source or transformFactory. + /// + /// This overload takes a factory that receives only the source item (without the key). public static IObservable> TransformOnObservable(this IObservable> source, Func> transformFactory) where TSource : notnull where TKey : notnull @@ -5407,23 +5909,8 @@ public static IObservable> TransformOnObservable< return source.TransformOnObservable((obj, _) => transformFactory(obj)); } - /// - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts a simpler factory that receives only the current item, and a forceTransform predicate filtering by source item only. public static IObservable> TransformSafe(this IObservable> source, Func transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -5436,23 +5923,8 @@ public static IObservable> TransformSafe transformFactory(current), errorHandler, forceTransform.ForForced()); } - /// - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts a factory that receives the current item and key. public static IObservable> TransformSafe(this IObservable> source, Func transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -5466,22 +5938,26 @@ public static IObservable> TransformSafe - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. + /// Projects each item using a synchronous factory, catching factory exceptions via a mandatory error handler + /// instead of terminating the stream. /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. + /// The type of the source items. + /// The type of the key. + /// The source to transform with error handling. + /// The that produces a from the current source item, the previous source item (if any), and the key. + /// A callback invoked when throws. Receives an containing the exception and the faulting item. The item is skipped and the stream continues. + /// An optional that, when it emits a predicate, re-transforms all items for which the predicate returns . If , no forced re-transforms occur. + /// An observable changeset of transformed items. + /// + /// + /// Behaves identically to + /// except that factory exceptions are routed to instead of propagating as . + /// Source-level errors (i.e. the source observable itself erroring) still propagate normally. + /// + /// Worth noting: Factory exceptions are caught per-item; the faulting item is skipped and reported to the error handler while the stream continues. Source-level errors still terminate the stream. + /// + /// , , or is . public static IObservable> TransformSafe(this IObservable> source, Func, TKey, TDestination> transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull where TSource : notnull @@ -5498,45 +5974,15 @@ public static IObservable> TransformSafe(source, transformFactory, errorHandler).Run(); } - /// - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for all items. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items. The factory receives only the current item. public static IObservable> TransformSafe(this IObservable> source, Func transformFactory, Action> errorHandler, IObservable forceTransform) where TDestination : notnull where TSource : notnull where TKey : notnull => source.TransformSafe((cur, _, _) => transformFactory(cur), errorHandler, forceTransform.ForForced()); - /// - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for all items.# - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items. The factory receives the current item and key. public static IObservable> TransformSafe(this IObservable> source, Func transformFactory, Action> errorHandler, IObservable forceTransform) where TDestination : notnull where TSource : notnull @@ -5549,23 +5995,8 @@ public static IObservable> TransformSafe transformFactory(cur, key), errorHandler, forceTransform.ForForced()); } - /// - /// Projects each update item to a new form using the specified transform function, - /// providing an error handling action to safely handle transform errors without killing the stream. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Provides the option to safely handle errors without killing the stream. - /// Invoke to force a new transform for all items.# - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts of to force re-transformation of ALL items. public static IObservable> TransformSafe(this IObservable> source, Func, TKey, TDestination> transformFactory, Action> errorHandler, IObservable forceTransform) where TDestination : notnull where TSource : notnull @@ -5578,22 +6009,8 @@ public static IObservable> TransformSafe()); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload takes a factory that receives only the current item. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func> transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull @@ -5607,22 +6024,8 @@ public static IObservable> TransformSafeAsync transformFactory(current), errorHandler, forceTransform); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload takes a factory that receives the current item and key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func> transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull @@ -5637,21 +6040,19 @@ public static IObservable> TransformSafeAsync - /// Projects each update item to a new form using the specified transform function. + /// Async version of . + /// Projects each item using an async factory, catching factory exceptions via a mandatory error handler. /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Invoke to force a new transform for items matching the selected objects. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. + /// The type of the source items. + /// The type of the key. + /// The source to transform asynchronously with error handling. + /// The async function that produces a . + /// A that called when throws or faults. The item is skipped and the stream continues. + /// An optional that forces re-transformation of matching items. + /// An observable changeset of transformed items. + /// Combines the async execution model of with the error-safe behavior of . + /// , , or is . [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func, TKey, Task> transformFactory, Action> errorHandler, IObservable>? forceTransform = null) where TDestination : notnull @@ -5665,22 +6066,8 @@ public static IObservable> TransformSafeAsync(source, transformFactory, errorHandler, forceTransform).Run(); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Additional transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. The factory receives only the current item. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func> transformFactory, Action> errorHandler, TransformAsyncOptions options) where TDestination : notnull @@ -5694,22 +6081,8 @@ public static IObservable> TransformSafeAsync transformFactory(current), errorHandler, options); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Additional transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. The factory receives the current item and key. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func> transformFactory, Action> errorHandler, TransformAsyncOptions options) where TDestination : notnull @@ -5723,22 +6096,8 @@ public static IObservable> TransformSafeAsync transformFactory(current, key), errorHandler, options); } - /// - /// Projects each update item to a new form using the specified transform function. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// The error handler. - /// Additional transform options. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload accepts to control concurrency and Refresh handling. [SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformSafeAsync(this IObservable> source, Func, TKey, Task> transformFactory, Action> errorHandler, TransformAsyncOptions options) where TDestination : notnull @@ -5753,14 +6112,27 @@ public static IObservable> TransformSafeAsync - /// Transforms the object to a fully recursive tree, create a hierarchy based on the pivot function. + /// Builds a hierarchical tree from a flat changeset using a parent key selector. + /// Each item becomes a with Parent, Children, Depth, and IsRoot properties. /// - /// The type of the object. + /// The type of the source items. Must be a reference type. /// The type of the key. - /// The source. - /// The pivot on. - /// Observable to change the underlying predicate. - /// An observable which will emit change sets. + /// The source to transform into a hierarchical tree. + /// The that returns the key of an item's parent. Return the item's own key (or a non-existent key) for root items. + /// An optional that emits a filter predicate for nodes. When the predicate changes, nodes are re-evaluated and filtered. + /// An observable changeset of items representing the tree. + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddCreates node, attaches to parent (or root if parent not found), emits Add. + /// UpdateUpdates node. If returns a different parent key, the node is re-parented. + /// RemoveRemoves node. Orphaned children become root nodes. + /// RefreshRe-evaluates parent key. May re-parent the node if the parent changed. + /// + /// Circular references are NOT detected. If item A is the parent of B and B is the parent of A, behavior is undefined. + /// + /// or is . public static IObservable, TKey>> TransformToTree(this IObservable> source, Func pivotOn, IObservable, bool>>? predicateChanged = null) where TObject : class where TKey : notnull @@ -5771,21 +6143,8 @@ public static IObservable, TKey>> TransformToTree return new TreeBuilder(source, pivotOn, predicateChanged).Run(); } - /// - /// Projects each update item to a new form using the specified transform function and when an update is received, allows the preservation of the previous instance. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Apply changes to the original. Example (previousTransformedItem, newOriginalItem) => previousTransformedItem.Value = newOriginalItem. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload defaults to transformOnRefresh: false and does not provide an error handler (factory exceptions propagate as OnError). public static IObservable> TransformWithInlineUpdate(this IObservable> source, Func transformFactory, Action updateAction) where TDestination : class where TSource : notnull @@ -5798,22 +6157,8 @@ public static IObservable> TransformWithInlineUpd return source.TransformWithInlineUpdate(transformFactory, updateAction, false); } - /// - /// Projects each update item to a new form using the specified transform function and when an update is received, allows the preservation of the previous instance. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Apply changes to the original. Example (previousTransformedItem, newOriginalItem) => previousTransformedItem.Value = newOriginalItem. - /// Should a new transform be applied when a refresh event is received. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload does not provide an error handler (factory exceptions propagate as OnError). The transformOnRefresh parameter controls Refresh behavior. public static IObservable> TransformWithInlineUpdate(this IObservable> source, Func transformFactory, Action updateAction, bool transformOnRefresh) where TDestination : class where TSource : notnull @@ -5826,22 +6171,8 @@ public static IObservable> TransformWithInlineUpd return new TransformWithInlineUpdate(source, transformFactory, updateAction, transformOnRefresh: transformOnRefresh).Run(); } - /// - /// Projects each update item to a new form using the specified transform function and when an update is received, allows the preservation of the previous instance. - /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Apply changes to the original. Example (previousTransformedItem, newOriginalItem) => previousTransformedItem.Value = newOriginalItem. - /// The error handler. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// + /// This overload defaults to transformOnRefresh: false but includes an error handler for factory/update action exceptions. public static IObservable> TransformWithInlineUpdate(this IObservable> source, Func transformFactory, Action updateAction, Action> errorHandler) where TDestination : class where TSource : notnull @@ -5856,22 +6187,33 @@ public static IObservable> TransformWithInlineUpd } /// - /// Projects each update item to a new form using the specified transform function and when an update is received, allows the preservation of the previous instance. + /// Projects each item using a transform factory for Add, and mutates the existing transformed + /// item in place (via an update action) for Update, preserving the original object reference. /// - /// The type of the destination. - /// The type of the source. - /// The type of the key. - /// The source. - /// The transform factory. - /// Apply changes to the original. Example (previousTransformedItem, newOriginalItem) => previousTransformedItem.Value = newOriginalItem. - /// The error handler. - /// Should a new transform be applied when a refresh event is received. - /// - /// A transformed update collection. - /// - /// source - /// or - /// transformFactory. + /// The type of the transformed items. Must be a reference type since items are mutated in place. + /// The type of the source items. + /// The type of the key. + /// The source to transform with in-place mutation on updates. + /// A that called on Add (and optionally Refresh) to create a new . + /// A that called on Update. Receives (existingTransformed, newSource). Mutate the existing transformed item to reflect the new source value. Example: (vm, model) => vm.Value = model.Value. + /// A that called when or throws. The faulting item is skipped. + /// When , Refresh changes call on the existing item. + /// An observable changeset of transformed items. + /// + /// + /// This is useful when the destination type is a ViewModel that should maintain its identity across updates. + /// Instead of replacing the entire ViewModel, the update action patches the existing instance. + /// + /// Change reason handling: + /// + /// Input reasonOutput behavior + /// AddCalls , emits Add. + /// UpdateCalls on the EXISTING transformed item (same reference), emits Update. + /// RemoveEmits Remove. + /// RefreshIf is true, calls . Otherwise forwarded as Refresh. + /// + /// + /// , , , or is . public static IObservable> TransformWithInlineUpdate(this IObservable> source, Func transformFactory, Action updateAction, Action> errorHandler, bool transformOnRefresh) where TDestination : class where TSource : notnull @@ -5890,7 +6232,7 @@ public static IObservable> TransformWithInlineUpd /// /// The type of the object. /// The type of the key. - /// The source. + /// The source to convert move events into remove/add pairs. /// the same SortedChangeSets, except all moves are replaced with remove + add. public static IObservable> TreatMovesAsRemoveAdd(this IObservable> source) where TObject : notnull @@ -5919,23 +6261,30 @@ static IEnumerable> ReplaceMoves(IChangeSet } /// - /// - /// Produces a boolean observable indicating whether the latest resulting value from all of the specified observables matches - /// the equality condition. The observable is re-evaluated whenever. - /// - /// - /// i) The cache changes - /// or ii) The inner observable changes. - /// + /// Emits when all items in the cache satisfy a condition based on their per-item observable, + /// and otherwise. Re-evaluates whenever the cache changes or any per-item observable emits. /// /// The type of the object. /// The type of the key. - /// The type of the value. - /// The source. - /// Selector which returns the target observable. - /// The equality condition. - /// An observable which boolean values indicating if true. - /// source. + /// The type of the value emitted by each per-item observable. + /// The source to evaluate a condition across all items in. + /// A factory that produces a condition observable for each item. + /// A that predicate applied to each per-item observable's latest value. + /// An observable of bool that emits whenever the all-items condition changes. + /// , , or is . + /// + /// + /// EventBehavior + /// AddA new per-item subscription is created. The aggregate condition is recalculated. + /// UpdateThe item is replaced in the collection snapshot. Condition recalculated. + /// RemovePer-item subscription disposed. Condition recalculated over remaining items. + /// RefreshNo effect on per-item subscriptions. Condition not recalculated unless the per-item observable emits. + /// OnErrorAn error from any per-item observable terminates the entire stream. Source errors also terminate. + /// OnCompletedCompletes when the source and all per-item observables have completed. + /// + /// Worth noting: Items whose per-item observable has not yet emitted are treated as not satisfying the condition. An empty cache is vacuously . The result uses DistinctUntilChanged, so duplicate bool values are suppressed. + /// + /// public static IObservable TrueForAll(this IObservable> source, Func> observableSelector, Func equalityCondition) where TObject : notnull where TKey : notnull @@ -5954,9 +6303,9 @@ public static IObservable TrueForAll(this IObservab /// The type of the object. /// The type of the key. /// The type of the value. - /// The source. - /// Selector which returns the target observable. - /// The equality condition. + /// The source to evaluate a condition across all items in. + /// A that selector which returns the target observable. + /// The equality condition. /// An observable which boolean values indicating if true. /// source. public static IObservable TrueForAll(this IObservable> source, Func> observableSelector, Func equalityCondition) @@ -5965,50 +6314,40 @@ public static IObservable TrueForAll(this IObservab where TValue : notnull => source.TrueFor(observableSelector, items => items.All(o => o.LatestValue.HasValue && equalityCondition(o.Item, o.LatestValue.Value))); /// - /// Produces a boolean observable indicating whether the resulting value of whether any of the specified observables matches - /// the equality condition. The observable is re-evaluated whenever - /// i) The cache changes. - /// or ii) The inner observable changes. + /// Emits when any item in the cache satisfies a condition based on its per-item observable, + /// and when none do. Re-evaluates whenever the cache changes or any per-item observable emits. /// /// The type of the object. /// The type of the key. - /// The type of the value. - /// The source. - /// The observable selector. - /// The equality condition. - /// An observable which boolean values indicating if true. - /// - /// source - /// or - /// observableSelector - /// or - /// equalityCondition. - /// + /// The type of the value emitted by each per-item observable. + /// The source to evaluate a condition across any item in. + /// A factory that produces a condition observable for each item. + /// A that predicate applied to each item and its per-item observable's latest value. + /// An observable of bool that emits whenever the any-item condition changes. + /// , , or is . + /// + /// + /// EventBehavior + /// AddA new per-item subscription is created. The aggregate condition is recalculated. + /// UpdateThe item is replaced in the collection snapshot. Condition recalculated. + /// RemovePer-item subscription disposed. Condition recalculated over remaining items. + /// RefreshNo effect on per-item subscriptions. Condition not recalculated unless the per-item observable emits. + /// OnErrorAn error from any per-item observable terminates the entire stream. Source errors also terminate. + /// OnCompletedCompletes when the source and all per-item observables have completed. + /// + /// Worth noting: Items whose per-item observable has not yet emitted are treated as not satisfying the condition. An empty cache yields . The result uses DistinctUntilChanged, so duplicate bool values are suppressed. + /// + /// public static IObservable TrueForAny(this IObservable> source, Func> observableSelector, Func equalityCondition) where TObject : notnull where TKey : notnull where TValue : notnull => source.TrueFor(observableSelector, items => items.Any(o => o.LatestValue.HasValue && equalityCondition(o.Item, o.LatestValue.Value))); - /// - /// Produces a boolean observable indicating whether the resulting value of whether any of the specified observables matches - /// the equality condition. The observable is re-evaluated whenever - /// i) The cache changes. - /// or ii) The inner observable changes. - /// - /// The type of the object. - /// The type of the key. - /// The type of the value. - /// The source. - /// The observable selector. - /// The equality condition. - /// An observable which boolean values indicating if true. - /// - /// source - /// or - /// observableSelector - /// or - /// equalityCondition. - /// + /// + /// The source to evaluate a condition across any item in. + /// A factory that produces a condition observable for each item. + /// A that predicate applied to each per-item observable's latest value (without the item). + /// This overload accepts a predicate that takes only the value, not the item. Useful when the condition depends only on the observed value. public static IObservable TrueForAny(this IObservable> source, Func> observableSelector, Func equalityCondition) where TObject : notnull where TKey : notnull @@ -6022,24 +6361,36 @@ public static IObservable TrueForAny(this IObservab } /// - /// Updates the index for an object which implements IIndexAware. + /// Sets the Index property on each item (which must implement ) + /// to reflect its position in the sorted output. Operates on . /// /// The type of the object. /// The type of the key. - /// The source. - /// An observable which emits the sorted change set. + /// The source to update index positions in. + /// An observable that emits the sorted changesets after updating item indices. public static IObservable> UpdateIndex(this IObservable> source) where TObject : IIndexAware where TKey : notnull => source.Do(changes => changes.SortedItems.Select((update, index) => new { update, index }).ForEach(u => u.update.Value.Index = u.index)); /// - /// Returns an observable of any updates which match the specified key, proceeded with the initial cache state. + /// Filters the source changeset stream to a single key, emitting each for that key. + /// Changes for all other keys are ignored. /// /// The type of the object. /// The type of the key. - /// The source. - /// The key. - /// An observable which emits the change. + /// The source to watch a single key in. + /// The key to observe. + /// An observable of for the specified key only. + /// + /// + /// Emits Add, Update, Remove, and Refresh changes as they occur for the target key. + /// No initial emission occurs if the key is not yet present in the cache. This operator does not + /// produce changesets; it produces individual change notifications. For Optional-based watching, + /// use . + /// + /// + /// + /// public static IObservable> Watch(this IObservable> source, TKey key) where TObject : notnull where TKey : notnull @@ -6050,14 +6401,33 @@ public static IObservable> Watch(this IObse } /// - /// Watches updates for a single value matching the specified key. + /// Filters the source changeset stream to a single key, emitting the current value each time it changes. + /// Even emits the value on removal (the removed item's value). /// /// The type of the object. /// The type of the key. - /// The source. - /// The key. - /// An observable which emits the object value. - /// source. + /// The source to watch a single key in. + /// The key to observe. + /// An observable of the item's value whenever it changes for the specified key. + /// + /// + /// Unlike , + /// this does not emit on removal. It emits the removed item's value instead. + /// If you need to distinguish presence from absence, use ToObservableOptional. + /// + /// + /// EventBehavior + /// AddEmits the added item's value. + /// UpdateEmits the new value. + /// RemoveEmits the removed item's value (not None; use if you need removal detection). + /// RefreshEmits the current value. + /// OnErrorForwarded to the downstream observer. + /// OnCompletedForwarded to the downstream observer. + /// + /// Worth noting: No emission occurs if the key is not present at subscription time. Changes to other keys are ignored entirely. + /// + /// + /// public static IObservable WatchValue(this IObservableCache source, TKey key) where TObject : notnull where TKey : notnull @@ -6067,15 +6437,10 @@ public static IObservable WatchValue(this IObservableCac return source.Watch(key).Select(u => u.Current); } - /// - /// Watches updates for a single value matching the specified key. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// The key. - /// An observable which emits the object value. - /// source. + /// + /// The source to watch a single key in. + /// The key to observe. + /// This overload extends IObservable<> instead of . public static IObservable WatchValue(this IObservable> source, TKey key) where TObject : notnull where TKey : notnull @@ -6086,13 +6451,35 @@ public static IObservable WatchValue(this IObservable - /// Watches each item in the collection and notifies when any of them has changed. + /// Emits an item whenever any of its properties change via . + /// Subscribes to PropertyChanged on each cache item using MergeMany. /// - /// The type of the object. + /// The type of the object (must implement ). /// The type of the key. - /// The source. - /// specify properties to Monitor, or omit to monitor all property changes. - /// An observable which emits the object which has had a property changed. + /// The source to observe property changes on items in. + /// The specific property names to monitor. If empty, all property changes trigger emissions. + /// An observable that emits the item itself each time a monitored property changes. + /// + /// + /// Subscriptions are managed per item: created on Add, replaced on Update, disposed on Remove. + /// Errors from individual property subscriptions are silently ignored. The output is not a changeset + /// stream; it is a plain IObservable<TObject?>. If the same item changes multiple properties + /// rapidly, each change emits the item separately (no deduplication). + /// + /// + /// EventBehavior + /// AddSubscribes to PropertyChanged on the new item. + /// UpdateDisposes the old item's subscription and subscribes to the new item. + /// RemoveDisposes the item's PropertyChanged subscription. + /// RefreshNo effect on subscriptions. + /// OnErrorErrors from individual property subscriptions are silently ignored. Source errors terminate the stream. + /// OnCompletedCompletes when the source changeset stream completes. + /// + /// + /// + /// + /// + /// public static IObservable WhenAnyPropertyChanged(this IObservable> source, params string[] propertiesToMonitor) where TObject : INotifyPropertyChanged where TKey : notnull @@ -6103,15 +6490,33 @@ public static IObservable WatchValue(this IObservable - /// Watches each item in the collection and notifies when any of them has changed. + /// Emits a (item + property value) whenever the specified property + /// changes on any item in the cache. Subscribes via using MergeMany. /// - /// The type of the object. + /// The type of the object (must implement ). /// The type of the key. - /// The type of the value. - /// The source. - /// The property accessor. - /// If true the resulting observable includes the initial value. - /// An observable which emits a property when it has changed. + /// The type of the monitored property. + /// The source to observe a specific property on items in. + /// A that expression selecting the property to monitor. + /// When (the default), the current property value is emitted immediately for each item upon subscription. + /// An observable of containing both the item and its property value. + /// + /// + /// Per-item subscriptions are created on Add, replaced on Update, disposed on Remove. Errors from individual + /// property subscriptions are silently ignored. The output is not a changeset stream. If you only need + /// the value (not the owning item), use instead. + /// + /// + /// EventBehavior + /// AddSubscribes to the specified property on the new item. If notifyOnInitialValue is true, the current value is emitted immediately. + /// UpdateDisposes the old item's property subscription and subscribes to the new item. + /// RemoveDisposes the item's property subscription. No further emissions for this item. + /// RefreshNo effect on subscriptions. The existing property subscription continues. + /// OnErrorPer-item property subscription errors are silently ignored. Source errors terminate the stream. + /// OnCompletedCompletes when the source changeset stream completes. + /// + /// + /// public static IObservable> WhenPropertyChanged(this IObservable> source, Expression> propertyAccessor, bool notifyOnInitialValue = true) where TObject : INotifyPropertyChanged where TKey : notnull @@ -6123,15 +6528,36 @@ public static IObservable> WhenPropertyChanged - /// Watches each item in the collection and notifies when any of them has changed. + /// Emits the property value whenever the specified property changes on any item in the cache. + /// Like but emits only the value, discarding the owning item. /// - /// The type of the object. + /// The type of the object (must implement ). /// The type of the key. - /// The type of the value. - /// The source. - /// The property accessor. - /// If true the resulting observable includes the initial value. - /// An observable which emits a value when it has changed. + /// The type of the monitored property. + /// The source to observe a specific property value on items in. + /// A that expression selecting the property to monitor. + /// When (the default), the current property value is emitted immediately for each item upon subscription. + /// An observable of property values. The owning item is not included; use if you need it. + /// + /// + /// Per-item subscriptions are created on Add, replaced on Update, disposed on Remove. Errors from individual + /// property subscriptions are silently ignored. If you need to correlate a value back to its source item, + /// use which returns a pair. + /// + /// + /// EventBehavior + /// AddSubscribes to the specified property. If notifyOnInitialValue is true, the current value is emitted immediately. + /// UpdateDisposes the old subscription, subscribes to the new item's property. + /// RemoveDisposes the property subscription. + /// RefreshNo effect on subscriptions. + /// OnErrorPer-item errors silently ignored. Source errors terminate the stream. + /// OnCompletedCompletes when the source completes. + /// + /// + /// + /// + /// + /// public static IObservable WhenValueChanged(this IObservable> source, Expression> propertyAccessor, bool notifyOnInitialValue = true) where TObject : INotifyPropertyChanged where TKey : notnull @@ -6147,11 +6573,14 @@ public static IObservable> WhenPropertyChanged /// The type of the object. /// The type of the key. - /// The source. - /// The reasons. + /// The source to filter by change reason. + /// The values to filter by. /// An observable which emits a change set with items matching the reasons. /// reasons. /// Must select at least on reason. + /// + /// Worth noting: Filtering out Remove changes will cause memory leaks in downstream caches, since items are never cleaned up. + /// public static IObservable> WhereReasonsAre(this IObservable> source, params ChangeReason[] reasons) where TObject : notnull where TKey : notnull @@ -6174,11 +6603,14 @@ public static IObservable> WhereReasonsAre /// The type of the object. /// The type of the key. - /// The source. - /// The reasons. + /// The source to filter by excluding change reasons. + /// The values to filter by. /// An observable which emits a change set with items not matching the reasons. /// reasons. /// Must select at least on reason. + /// + /// Worth noting: Filtering out Remove changes will cause memory leaks in downstream caches, since items are never cleaned up. + /// public static IObservable> WhereReasonsAreNot(this IObservable> source, params ChangeReason[] reasons) where TObject : notnull where TKey : notnull @@ -6196,19 +6628,35 @@ public static IObservable> WhereReasonsAreNot - /// Apply a logical Xor operator between the collections. - /// Items which are only in one of the sources are included in the result. + /// Combines multiple changeset streams using logical XOR (symmetric difference). + /// An item appears downstream only if it exists in exactly one source. /// /// The type of the object. /// The type of the key. - /// The source. - /// The others. - /// An observable which emits a change set. - /// - /// source - /// or - /// others. - /// + /// The source to combine. + /// The additional streams to combine with. + /// A changeset stream containing items present in exactly one source. + /// + /// + /// Items are tracked via reference counting. An item appears downstream only when exactly one + /// source holds it. Adding the same key from a second source removes it from the result; + /// removing from that second source restores it. + /// + /// + /// EventBehavior + /// AddIf the key is now held by exactly one source, an Add is emitted. If adding causes the count to reach 2+, a Remove is emitted (the item is no longer exclusive). + /// UpdateIf the item is currently downstream (count is 1), an Update is emitted. + /// RemoveReference count decremented. If the count drops to exactly 1, an Add is emitted (the item is now exclusive to one source). If it drops to 0, a Remove is emitted. + /// RefreshIf the item is downstream, a Refresh is forwarded. + /// OnErrorAn error from any source terminates the combined output. + /// OnCompletedThe output completes when all sources have completed. + /// + /// + /// or is . + /// + /// + /// + /// public static IObservable> Xor(this IObservable> source, params IObservable>[] others) where TObject : notnull where TKey : notnull @@ -6223,19 +6671,9 @@ public static IObservable> Xor(this IOb return source.Combine(CombineOperator.Xor, others); } - /// - /// Apply a logical Xor operator between the collections. - /// Items which are only in one of the sources are included in the result. - /// - /// The type of the object. - /// The type of the key. - /// The source. - /// An observable which emits a change set. - /// - /// source - /// or - /// others. - /// + /// + /// The of streams to combine. + /// This overload accepts a pre-built collection of sources instead of a params array. public static IObservable> Xor(this ICollection>> sources) where TObject : notnull where TKey : notnull @@ -6251,7 +6689,7 @@ public static IObservable> Xor(this ICo /// /// The type of the object. /// The type of the key. - /// The source. + /// The of streams to combine. /// An observable which emits a change set. public static IObservable> Xor(this IObservableList>> sources) where TObject : notnull @@ -6268,7 +6706,7 @@ public static IObservable> Xor(this IOb /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits a change set. public static IObservable> Xor(this IObservableList> sources) where TObject : notnull @@ -6285,7 +6723,7 @@ public static IObservable> Xor(this IOb /// /// The type of the object. /// The type of the key. - /// The source. + /// The of changeset streams to combine. /// An observable which emits a change set. public static IObservable> Xor(this IObservableList> sources) where TObject : notnull