Skip to content

Commit cea0775

Browse files
bfarmer67bfarmer67
committed
Documentation
1 parent 3f2d4b4 commit cea0775

File tree

4 files changed

+160
-217
lines changed

4 files changed

+160
-217
lines changed

‎README.md

+82-140
Original file line numberDiff line numberDiff line change
@@ -1,191 +1,133 @@
1-
# Hyperbee.Pipeline
1+
# Hyperbee Pipeline
22

3-
The `Hyperbee.Pipeline` library is a sophisticated tool for constructing asynchronous fluent pipelines in .NET. A pipeline, in this context, refers to a sequence of data processing elements arranged in series, where the output of one element serves as the input for the subsequent element.
3+
`Hyperbee.Pipeline` allows you to construct asynchronous fluent pipelines in .NET. A pipeline, in this context, refers to a
4+
sequence of data processing elements arranged in series, where the output of one element serves as the input for the subsequent
5+
element.
46

5-
A distinguishing feature of the `Hyperbee.Pipeline` library, setting it apart from other pipeline implementations, is its inherent support for **middleware** and **dependency injection**. Middleware introduces a higher degree of flexibility and control over the data flow, enabling developers to manipulate data as it traverses through the pipeline. This can be leveraged to implement a variety of functionalities such as eventing, caching, logging, and more, thereby enhancing the customizability of the code.
7+
Hyperbee pipelines are composable, reusable, and easy to test. They are designed to be used in a variety of scenarios, such
8+
as data processing, message handling, and workflow automation.
69

7-
Furthermore, the support for dependency injection facilitates efficient management of dependencies within the pipeline. This leads to code that is more maintainable and testable, thereby improving the overall quality of the software.
10+
Some key features are:
811

9-
10-
## Features
1112
* Middleware
12-
* Pipelines come with the ability to enhance processing with custom middleware.
13-
* Hook
14-
* the `Hook` and `HookAsync` method allows you to add a hook that is called for every statement in the pipeline.
15-
* Wrap
16-
* The `Wrap` and `WrapAsync` method allows you to wrap a part of the pipeline.
17-
* Dependency Injection
18-
* Sometimes Pipelines and Pipeline middleware need access to specific container services.
19-
* **Advanced features**
20-
* The `PipelineFactory` library provides a variety of helper methods that allow you to customize the behavior of your pipelines.
21-
* Reduce
22-
* The `Reduce` and `ReduceAsync` methods allow you to reduce a sequence of elements to a single value.
23-
* WaitAll
24-
* The `WaitAll` method allows you to wait for all pipelines to complete before continuing.
25-
* PipeIf
26-
* The `PipeIf` method allows you to conditionally add a step to the pipeline.
27-
* ForEach and ForEachAsync
28-
*The `ForEach` and `ForEachAsync` methods allow you to apply a pipeline to each element in a sequence.
29-
* Call and CallAsync
30-
* The `Call` and `CallAsync` methods allow you to add a procedure to the pipeline.
31-
* Chaining Child Pipelines
32-
* The `PipelineFactory` library allows you to chain pipelines together.
33-
34-
35-
## Example
36-
37-
```csharp
38-
// Takes a string and returns a number
39-
var question = PipelineFactory
40-
.Start<string>()
41-
.PipeIf((ctx, arg) => arg == "Adams", builder => builder
42-
.Pipe((ctx, arg) => 42)
43-
.Cancel()
44-
)
45-
.Pipe((ctx, arg) => 0)
46-
.Build();
47-
48-
var answer1 = await question(new PipelineContext(), "Adams");
49-
Assert.AreEqual(42, answer1);
50-
51-
var answer2 = await question(new PipelineContext(), "Smith");
52-
Assert.AreEqual(0, answer2);
53-
```
13+
* Hooks
14+
* Wraps
15+
* Conditional flows
16+
* Loops
17+
* Parallel processing
18+
* Dependency injection
19+
* Early returns and cancellation
20+
* Child pipelines
5421

22+
## Why Use Pipelines
5523

56-
## Example Hook
24+
Pipelines provide a structured approach to managing complex processes, promoting [SOLID](https://en.wikipedia.org/wiki/SOLID)
25+
principles, including Inversion of Control (IoC) and Separation of Concerns (SoC). They enable composability, making it easier
26+
to build, test, and maintain your code. By extending the benefits of middleware and request-response pipelines throughout your
27+
application, you achieve greater modularity, scalability, and flexibility. This is especially critical in domains such as
28+
healthcare, compliance auditing, identity and roles, and high-security environments where clear boundaries and responsibilities
29+
are essential. Hyperbee.Pipeline ensures that the advantages of pipelines and middleware are not abandoned at the controller
30+
implementation, addressing a common gap in many frameworks. By using a functional approach, Hyperbee.Pipeline ensures that your
31+
pipelines are not only robust and maintainable but also highly adaptable to changing requirements.
5732

58-
The `Hook` and `HookAsync` methods allow you to add a hook that is called for every statement in the pipeline. This hook takes the current context, the current argument, and a delegate to the next part of the pipeline. It can manipulate the argument before and after calling the next part of the pipeline.
5933

60-
Here's an example of how to use `HookAsync`:
34+
## Getting Started
6135

62-
```csharp
63-
var command = PipelineFactory
64-
.Start<string>()
65-
.HookAsync( async ( ctx, arg, next ) => await next( ctx, arg + "{" ) + "}" )
66-
.Pipe( ( ctx, arg ) => arg + "1" )
67-
.Pipe( ( ctx, arg ) => arg + "2" )
68-
.Build();
36+
To get started with Hyperbee.Json, refer to the [documentation](https://stillpoint-software.github.io/hyperbee.pipeline) for
37+
detailed instructions and examples.
6938

70-
var result = await command( new PipelineContext() );
39+
Install via NuGet:
7140

72-
Assert.AreEqual( "{1}{2}", result );
41+
```bash
42+
dotnet add package Hyperbee.Pipeline
7343
```
7444

75-
## Example Wrap
45+
## Building and Executing Pipelines
7646

77-
```csharp
78-
var command = PipelineFactory
79-
.Start<string>()
80-
.Pipe( ( ctx, arg ) => arg + "1" )
81-
.Pipe( ( ctx, arg ) => arg + "2" )
82-
.WrapAsync( async ( ctx, arg, next ) => await next( ctx, arg + "{" ) + "}" )
83-
.Pipe( ( ctx, arg ) => arg + "3" )
84-
.Build();
47+
Pipelines are built using `PipelineFactory`. Once built, a pipeline is just an async function that takes a `PipelineContext` and
48+
an optional input value as parameters, and returns a result.
8549

86-
var result = await command( new PipelineContext() );
50+
```csharp
51+
var command = PipelineFactory
52+
.Start<string>()
53+
.Pipe( ( ctx, arg ) => $"hello {arg}" )
54+
.Build();
8755

88-
Assert.AreEqual( "{12}3", result );
56+
var result = await command( new PipelineContext(), "pipeline" );
8957

58+
Assert.AreEqual( "hello pipeline", result );
9059
```
9160

92-
## Example ForEach
61+
## Dependency Injection
9362

94-
```csharp
95-
var count = 0;
63+
Sometimes Pipelines and Pipeline middleware need access to specific container services. This can be
64+
accomplished by registering services with the `PipelineContextFactory`. This can be done through
65+
DI configuration, or manually through the `PipelineContextFactoryProvider` if you are not using DI.
9666

97-
var command = PipelineFactory
98-
.Start<string>()
99-
.Pipe( ( ctx, arg ) => arg.Split( ' ' ) )
100-
.ForEach<string>( builder => builder
101-
.Pipe( ( ctx, arg ) => count += 10 )
102-
)
103-
.Pipe( ( ctx, arg ) => count += 5 )
104-
.Build();
67+
Pipelines manage dependencies with a specialized container. This allows the implementor to control
68+
the services that are exposed through the pipeline. If you want to expose all application
69+
services then you can call `AddPipeline` and pass `includeAllServices: true`.
10570

106-
await command( new PipelineContext(), "e f" );
71+
Register pipelines with DI and provide Pipeline dependencies using the application container.
10772

108-
Assert.AreEqual( count, 25 );
73+
```csharp
74+
services.AddPipeline( includeAllServices: true );
10975
```
11076

111-
## Example Call
77+
Register Pipelines with DI and provide Pipeline dependencies using a specialized container.
11278

11379
```csharp
114-
var callResult = string.Empty;
115-
116-
var command = PipelineFactory
117-
.Start<string>()
118-
.Pipe( ( ctx, arg ) => arg + "1" )
119-
.Pipe( ( ctx, arg ) => arg + "2" )
120-
.Call( builder => builder
121-
.Call( ( ctx, arg ) => callResult = arg + "3" )
122-
.Pipe( ( ctx, arg ) => arg + "9" )
123-
)
124-
.Pipe( ( ctx, arg ) => arg + "4" )
125-
.Build();
80+
services.AddPipeline( (factoryServices, rootProvider) =>
81+
{
82+
factoryServices.AddTransient<IThing>()
83+
factoryServices.ProxyService<IPrincipalProvider>( rootProvider ); // pull from root container
84+
} );
85+
```
12686

127-
var result = await command( new PipelineContext() );
87+
## Pipeline of Pipelines
12888

129-
Assert.AreEqual( "124", result );
130-
Assert.AreEqual( "123", callResult );
131-
```
89+
The `PipelineFactory` library allows you to use pipelines together. Since pipelines are just functions, they can be used
90+
as input to other pipelines. This allows you to create complex data processing flows by reusing and chaining together
91+
multiple pipelines.
13292

133-
## Example Chaining Child Pipelines
93+
Here's an example of how to use pipelines together:
13494

13595
```csharp
136-
var command2 = PipelineFactory
96+
var pipeline2 = PipelineFactory
13797
.Start<string>()
13898
.Pipe( ( ctx, arg ) => $"{arg} again!" )
13999
.Build();
140100

141-
var command1 = PipelineFactory
101+
var pipeline1 = PipelineFactory
142102
.Start<string>()
143103
.Pipe( ( ctx, arg ) => $"hello {arg}" )
144-
.PipeAsync( command2 )
104+
.PipeAsync( pipeline2 )
145105
.Build();
146106

147-
var result = await command1( new PipelineContext(), "pipeline" );
107+
var result = await pipeline1( new PipelineContext(), "you" );
148108

149-
Assert.AreEqual( "hello pipeline again!", result );
109+
Assert.AreEqual( "hello you again!", result );
150110
```
151111

152-
## Additional Documentation
153-
Classes for building composable async pipelines supporting:
154-
155-
* [Middleware](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/blob/main/docs/middleware.md)
156-
* [Conditional flow](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/blob/main/docs/execution.md)
157-
* [Dependency Injection](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/blob/main/docs/dependencyInjection.md)
158-
* Value projections
159-
* Early returns
160-
* Child pipelines
161-
162-
163-
# Build Requirements
164-
165-
* To build and run this project, **.NET 8 SDK** is required.
166-
* Ensure your development tools are compatible with .NET 8.
167-
168-
## Building the Project
169-
170-
* With .NET 8 SDK installed, you can build the project using the standard `dotnet build` command.
171-
172-
## Running Tests
173-
174-
* Run tests using the `dotnet test` command as usual.
112+
## Conditional Flow and Advanced Features
175113

176-
# Status
114+
The `PipelineFactory` library provides a variety of builders that allow you to customize the behavior of your pipelines.
115+
These methods provide powerful functionality for manipulating data as it passes through the pipeline.
177116

178-
| Branch | Action |
179-
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
180-
| `develop` | [![Build status](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/actions/workflows/publish.yml/badge.svg?branch=develop)](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/actions/workflows/publish.yml) |
181-
| `main` | [![Build status](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/actions/workflows/publish.yml/badge.svg)](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/actions/workflows/publish.yml) |
117+
- Functions
118+
- Procedures
119+
- Conditional Flow
120+
- Iterators
121+
- Reduce
122+
- Parallel execution
182123

124+
## Credits
183125

126+
Hyperbee.Pipeline is built upon the great work of several open-source projects. Special thanks to:
184127

185-
# Benchmarks
186-
See [Benchmarks](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/test/Hyperbee.Pipeline.Benchmark/benchmark/results/Hyperbee.Pipeline.Benchmark.PipelineBenchmarks-report-github.md)
128+
- [Just The Docs](https://github.com/just-the-docs/just-the-docs) for the documentation theme.
187129

188-
# Help
189-
See our list of items [Todo](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/blob/main/docs/todo.md)
130+
## Contributing
190131

191-
[![Hyperbee.Pipeline](https://github.com/Stillpoint-Software/Hyperbee.Pipeline/blob/main/assets/hyperbee.svg?raw=true)](https://github.com/Stillpoint-Software/Hyperbee.Pipeline)
132+
We welcome contributions! Please see our [Contributing Guide](https://github.com/Stillpoint-Software/.github/blob/main/.github/CONTRIBUTING.md)
133+
for more details.

0 commit comments

Comments
 (0)