\n\n**Gress** is a library that extends the standard [`IProgress`](https://learn.microsoft.com/dotnet/api/system.iprogress-1) interface with a set of utilities for collecting, transforming, filtering, and multiplexing progress updates in your code.\n\n## Terms of use[[?]](https://github.com/Tyrrrz/.github/blob/prime/docs/why-so-political.md)\n\nBy using this project or its source code, for any purpose and in any shape or form, you grant your **implicit agreement** to all the following statements:\n\n- You **condemn Russia and its military aggression against Ukraine**\n- You **recognize that Russia is an occupant that unlawfully invaded a sovereign state**\n- You **support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas**\n- You **reject false narratives perpetuated by Russian state propaganda**\n\nTo learn more about the war and how you can help, [click here](https://tyrrrz.me/ukraine). Glory to Ukraine! πΊπ¦\n\n## Install\n\n- π¦ [NuGet](https://nuget.org/packages/Gress): `dotnet add package Gress`\n\n## Screenshots\n\n\n\n## Usage\n\n### Percentage type\n\nTo make progress updates more explicit, **Gress** provides a universal progress unit β the `Percentage` type.\nUnlike the primitive numeric types that are commonly paired with `IProgress`, this type can be used to unambiguously represent progress as a ratio of completed work to the total amount of work encapsulated by a given operation.\n\nAn instance of `Percentage` can be created from either a value or a fraction:\n\n```csharp\nusing Gress;\n\n// Mapped from value\nvar fiftyPercent = Percentage.FromValue(50); // 50%\n\n// Mapped from fractional representation\nvar twentyPercent = Percentage.FromFraction(0.2); // 20%\n```\n\nSimilarly, both value and fraction can be extracted from an initialized `Percentage` by accessing the corresponding properties:\n\n```csharp\nusing Gress;\n\nvar fiftyPercent = Percentage.FromValue(50);\n\nvar asValue = fiftyPercent.Value; // 50.0 (double)\nvar asFraction = fiftyPercent.Fraction; // 0.5 (double)\n```\n\nUsing `Percentage` in your `IProgress` handlers lets you communicate progress updates without making any assumptions about their semantics:\n\n```csharp\nusing Gress;\n\nasync Task PerformWorkAsync(IProgress progrss)\n{\n await Task.Delay(100);\n\n // Half-way done\n progress.Report(Percentage.FromValue(50));\n\n await Task.Delay(100);\n\n // Finished\n progress.Report(Percentage.FromFraction(1));\n}\n\n// ...\n\nvar progress = new Progress(p => Console.WriteLine(p));\nawait PerformWorkAsync(progress);\n\n// Console output:\n// 50,0%\n// 100,0%\n```\n\nWhen interfacing with external methods, however, you may need to provide a specific progress handler required by their signature.\nIn such cases, you can convert an existing percentage-based handler into another type using one of the available extension methods:\n\n```csharp\nusing Gress;\n\nasync Task FooAsync(IProgress progress) { /* ... */ }\nasync Task BarAsync(IProgress progress) { /* ... */ }\n\nvar progress = new Progress(p => /* ... */);\n\nawait FooAsync(progress.ToDoubleBased());\nawait BarAsync(progress.ToInt32Based());\n```\n\nLikewise, you can also perform conversions in the other direction, which can be useful for preserving backwards-compatibility in your own methods:\n\n```csharp\nusing Gress;\n\nasync Task FooAsync(IProgress progress)\n{\n var actualProgress = progress.ToPercentageBased(); // IProgress\n\n // Reports 0.5 on the original progress handler\n actualProgress.Report(Percentage.FromFraction(0.5));\n}\n\nasync Task BarAsync(IProgress progress)\n{\n var actualProgress = progress.ToPercentageBased(); // IProgress\n\n // Reports 50 on the original progress handler\n actualProgress.Report(Percentage.FromFraction(0.5));\n}\n```\n\n> [!NOTE]\n> When converting between percentage-based and double-based handlers, percentages are mapped using their fractional form by default.\n> To override this behavior and map by value instead, use `ToDoubleBased(asFraction: false)` and `ToPercentageBased(asFraction: false)`.\n\n> [!NOTE]\n> For more complex conversion scenarios, consider using the [`WithTransform(...)`](#transformation) method.\n\n### Terminal handlers\n\nEvery progress reporting chain ultimately ends with a terminal handler, which usually relays the information to the user or stores it somewhere else.\nTo simplify some of the most common scenarios, **Gress** comes with two terminal handlers built in.\n\n#### Progress container\n\nThis handler is an object with a single property, whose value is overwritten with every new progress update that gets reported.\nIt also implements the `INotifyPropertyChanged` interface, allowing the property to be bound from XAML-based user interfaces.\n\nHere's a very basic example of how you would use it in a typical Avalonia application:\n\n```csharp\npublic class MainViewModel\n{\n public MainViewModel() =>\n PerformWorkCommand = new AsyncRelayCommand(PerformWorkAsync);\n\n public ProgressContainer Progress { get; } = new();\n\n public IRelayCommand PerformWorkCommand { get; }\n\n public async Task PerformWorkAsync()\n {\n for (var i = 1; i <= 100; i++)\n {\n // Simulate work\n await Task.Delay(200);\n\n // Report progress as a value in the 0..100 range\n Progress.Report(Percentage.FromValue(i));\n }\n }\n}\n```\n\n```xml\n\n \n \n\n \n \n\n```\n\n#### Progress collector\n\nThis handler works by storing all reported progress updates in a collection, whose values can be retrieved later.\nIt's primarily designed for testing purposes.\n\nHere's how you can use it to verify that a method reported its progress correctly:\n\n```csharp\n[Fact]\npublic async Task My_method_reports_progress_correctly()\n{\n // Arrange\n var progress = new ProgressCollector();\n var worker = new Worker();\n\n // Act\n await worker.PerformWorkAsync(progress);\n\n // Assert\n var values = progress.GetValues();\n\n values.Should().NotBeEmpty(); // not empty\n values.Should().OnlyHaveUniqueItems(); // no redundant updates\n}\n```\n\n### Composing handlers\n\nExisting progress handlers can be composed into more complex handlers using some of the extension methods that **Gress** offers.\nThese can be used to easily apply transformations, inject filtering logic, or merge multiple handlers together.\n\n#### Transformation\n\nYou can use `WithTransform(...)` to create a handler that transforms all reported progress updates into a different form:\n\n```csharp\nusing Gress;\n\nenum Status { Started, HalfWay, Completed }\n\nvar progress = new Progress(p => /* ... */);\n\n// Transform into a progress handler that accepts an enum value and maps\n// it into a value of the original type\nvar transformedProgress = progress.WithTransform((Status s) => s switch\n{\n Status.Completed => Percentage.FromValue(100), // 100%\n Status.HalfWay => Percentage.FromValue(50), // 50%\n _ => Percentage.FromValue(0) // 0%\n}); // IProgress\n\n// Effectively reports 50% on the original handler\ntransformedProgress.Report(Status.HalfWay);\n```\n\nA simpler overload of the above method can also be used when transforming between values of the same type:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\nvar transformedProgress = progress.WithTransform(p => 5 * p); // IProgress\n\n// Effectively reports 50% on the original handler\ntransformedProgress.Report(10);\n```\n\n> [!NOTE]\n> Method `WithTransform(...)` bears some resemblance to LINQ's `Select(...)`, however they are not completely equivalent.\n> The main difference is that the flow of data in `IProgress` is inverse to that of `IEnumerable`, which means that the transformations in `WithTransform(...)` are applied in the opposite direction.\n\n#### Filtering\n\nYou can use `WithFilter(...)` to create a handler that drops progress updates that don't satisfy a predicate:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\n// Filter out values below 10%\nvar filteredProgress = progress.WithFilter(p => p.Fraction >= 0.1);\n\nfilteredProgress.Report(Percentage.FromFraction(0.05)); // β\nfilteredProgress.Report(Percentage.FromFraction(0.25)); // β\n```\n\n#### Deduplication\n\nYou can use `WithDeduplication(...)` to create a handler that filters out consecutive progress updates with the same value:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\nvar deduplicatedProgress = progress.WithDeduplication();\n\ndeduplicatedProgress.Report(Percentage.FromFraction(0.1)); // β\ndeduplicatedProgress.Report(Percentage.FromFraction(0.3)); // β\ndeduplicatedProgress.Report(Percentage.FromFraction(0.3)); // β\ndeduplicatedProgress.Report(Percentage.FromFraction(0.3)); // β\ndeduplicatedProgress.Report(Percentage.FromFraction(0.5)); // β\n```\n\n#### Ordering\n\nYou can use `WithOrdering(...)` to create a handler that filters out progress updates that arrive out of order:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\nvar orderedProgress = progress.WithOrdering();\n\norderedProgress.Report(Percentage.FromFraction(0.1)); // β\norderedProgress.Report(Percentage.FromFraction(0.3)); // β\norderedProgress.Report(Percentage.FromFraction(0.2)); // β\norderedProgress.Report(Percentage.FromFraction(0.5)); // β\norderedProgress.Report(Percentage.FromFraction(0.4)); // β\n```\n\n#### Merging\n\nYou can use `Merge(...)` to combine multiple progress handlers into one:\n\n```csharp\nusing Gress;\n\nvar progress1 = new Progress(p => /* ... */);\nvar progress2 = new Progress(p => /* ... */);\n\nvar mergedProgress = progress1.Merge(progress2); // IProgress\n\n// Reports 50% on both progress handlers\nmergedProgress.Report(Percentage.FromFraction(0.5));\n```\n\nThis method can also be called on collections:\n\n```csharp\nusing Gress;\n\nvar progresses = new[]\n{\n new Progress(p => /* ... */),\n new Progress(p => /* ... */),\n new Progress(p => /* ... */),\n new Progress(p => /* ... */)\n};\n\nvar mergedProgress = progresses.Merge(); // IProgress\n\n// Reports 50% on all progress handlers\nmergedProgress.Report(Percentage.FromFraction(0.5));\n```\n\n### Multiplexing\n\nMultiplexing allows a single handler to aggregate progress updates from multiple input sources.\nThis is useful when you want to encapsulate several progress-reporting operations in a single higher-order operation.\n\nTo do this, create a muxer for the target progress handler and then use it to assign an input for each operation:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\nvar muxer = progress.CreateMuxer();\nvar subProgress1 = muxer.CreateInput(); // IProgress\nvar subProgress2 = muxer.CreateInput(); // IProgress\nvar subProgress3 = muxer.CreateInput(); // IProgress\n```\n\nWhen a progress update is reported on any of these inputs, all the updates up to that point are aggregated into one and routed to the target handler.\nThe sample below illustrates this process in detail:\n\n```csharp\n// ...\n\nsubProgress1.Report(Percentage.FromFraction(0.5));\n\n// Input 1 -> 50%\n// Input 2 -> 0%\n// Input 3 -> 0%\n// Total -> ~17%\n\nsubProgress1.Report(Percentage.FromFraction(1));\nsubProgress2.Report(Percentage.FromFraction(0.75));\n\n// Input 1 -> 100%\n// Input 2 -> 75%\n// Input 3 -> 0%\n// Total -> ~58%\n\nsubProgress2.Report(Percentage.FromFraction(1));\nsubProgress3.Report(Percentage.FromFraction(0.9));\n\n// Input 1 -> 100%\n// Input 2 -> 100%\n// Input 3 -> 90%\n// Total -> ~97%\n\nsubProgress3.Report(Percentage.FromFraction(1));\n\n// Input 1 -> 100%\n// Input 2 -> 100%\n// Input 3 -> 100%\n// Total -> 100%\n```\n\nAdditionally, since muxer inputs are progress handlers themselves, they can be multiplexed further as well.\nDoing this allows you to create hierarchical progress reporting chains:\n\n```csharp\nusing Gress;\n\nasync Task PerformWorkAsync(IProgress progress)\n{\n for (var i = 1; i <= 100; i++)\n {\n await Task.Delay(200);\n progress.Report(Percentage.FromValue(i));\n }\n}\n\nasync Task FooAsync(IProgress progress)\n{\n var muxer = progress.CreateMuxer();\n var subProgress1 = muxer.CreateInput();\n var subProgress2 = muxer.CreateInput();\n\n await Task.WhenAll(\n PerformWorkAsync(subProgress1),\n PerformWorkAsync(subProgress2)\n );\n}\n\nasync Task BarAsync(IProgress progress)\n{\n var muxer = progress.CreateMuxer();\n var subProgress1 = muxer.CreateInput();\n var subProgress2 = muxer.CreateInput();\n var subProgress3 = muxer.CreateInput();\n\n await Task.WhenAll(\n FooAsync(subProgress1),\n FooAsync(subProgress2),\n FooAsync(subProgress3)\n );\n}\n```\n\n> [!NOTE]\n> Muxing is only available on percentage-based handlers because it relies on their ability to represent progress as a relative fraction.\n> If required, you can convert certain other handlers into percentage-based handlers using the `ToPercentageBased()` extension method.\n\n#### Custom weights\n\nA muxer input may be assigned a custom weight modifier, which determines its priority in relation to others.\nProgress reported on an input with higher weight influences the aggregated progress to a greater degree and vice versa.\n\nYou can specify the input weight by passing it to the `CreateInput(...)` method:\n\n```csharp\nusing Gress;\n\nvar progress = new Progress(p => /* ... */);\n\nvar muxer = progress.CreateMuxer();\nvar subProgress1 = muxer.CreateInput(1);\nvar subProgress2 = muxer.CreateInput(4);\n\n// Weight split:\n// Input 1 -> 20% of total\n// Input 2 -> 80% of total\n\nsubProgress1.Report(Percentage.FromFraction(0.9));\nsubProgress2.Report(Percentage.FromFraction(0.3));\n\n// Input 1 -> 90% (less important)\n// Input 2 -> 30% (more important)\n// Total -> 42% (would've been 60% without weights)\n```\n\n#### Auto-reset muxer\n\nIn some cases, you may need to report progress on an infinite workflow where new operations are started and completed in a continuous fashion.\nThis can be achieved by using an auto-reset muxer.\n\nInputs to an auto-reset muxer implement the `ICompletableProgress` interface and are capable of reporting completion after all of the underlying work is finished.\nOnce all connected inputs report completion, they are disconnected from the muxer and the latter is reset back to the initial state.\n\nTo create an auto-reset muxer, call `WithAutoReset()` on an existing instance:\n\n```csharp\nusing Gress;\nusing Gress.Completable;\n\nvar progress = new Progress(p => /* ... */);\n\nvar muxer = progress.CreateMuxer().WithAutoReset();\nvar subProgress1 = muxer.CreateInput(); // ICompletableProgress\nvar subProgress2 = muxer.CreateInput(); // ICompletableProgress\n\nsubProgress1.Report(Percentage.FromFraction(0.3));\nsubProgress2.Report(Percentage.FromFraction(0.9));\n\n// Input 1 -> 30%\n// Input 2 -> 90%\n// Total -> 60%\n\nsubProgress1.Report(Percentage.FromFraction(1));\nsubProgress1.ReportCompletion();\n\n// Input 1 -> 100% (completed)\n// Input 2 -> 90%\n// Total -> 95%\n\nsubProgress2.Report(Percentage.FromFraction(1));\nsubProgress2.ReportCompletion();\n\n// All inputs disconnected\n// Total -> 0%\n\nvar subProgress3 = muxer.CreateInput();\nsubProgress3.Report(Percentage.FromFraction(0.5));\n\n// Input 3 -> 50%\n// Total -> 50%\n```\n\n> [!NOTE]\n> You can wrap an instance of `ICompletableProgress` in a disposable container by calling `ToDisposable()`.\n> This allows you to place the handler in a `using (...)` block, which ensures that the completion is always reported at the end.\n\n### Integration extensions\n\n**Gress** also provides extensions for several built-in .NET types that integrate `IProgress` into their existing APIs.\nFor example, you can use the below `Stream.CopyToAsync(...)` overload to copy data between two streams while tracking the operation's progress:\n\n```csharp\nusing Gress;\nusing Gress.Integrations;\n\nawait using var source = File.OpenRead(\"input.bin\");\nawait using var destination = File.Create(\"output.bin\");\n\nawait source.CopyToAsync(\n destination,\n new Progress(p => Console.WriteLine($\"Copied: {p}\"))\n);\n\n// Console output:\n// Copied: 37,5%\n// Copied: 62,5%\n// Copied: 87,5%\n// Copied: 100,0%\n```\n"
},
{
"path": "global.json",
"content": "{\n \"sdk\": {\n \"version\": \"10.0.100\",\n \"rollForward\": \"latestFeature\"\n }\n}"
}
]
![\"Icon\"](\"favicon.png\")
\n