Better readme and more practical examples (#40)

.github/workflows/check.yaml

@@ -34,7 +34,7 @@ jobs:
           go-version: '1.23.x'
 
       - name: Run coverage
-        run: go test -coverprofile=coverage.out -covermode=atomic $(go list ./... | grep -v internal/th)
+        run: go test -coverprofile=coverage.out -covermode=atomic $(go list ./... | grep -v internal/th | grep -v mockapi)
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v4.0.1

doc.go

@@ -1,7 +1,7 @@
-// Package rill is a collection of easy-to-use functions for concurrency, streaming, batching and pipeline construction.
-// It abstracts away the complexities of concurrency, removes boilerplate, and provides a structured way to handle errors.
-// Rill is modular and can be easily integrated into existing projects: it requires no setup and allows using only the necessary functions.
-// At the same time, rill's functions can be composed into complex, concurrent, and reusable pipelines when needed.
+// Package rill provides composable channel-based concurrency primitives for Go that simplify parallel processing,
+// batching, and stream handling. It offers building blocks for constructing concurrent pipelines from
+// reusable parts while maintaining precise control over concurrency levels. The package reduces boilerplate,
+// abstracts away goroutine orchestration, features centralized error handling, and has zero external dependencies.
 //
 // # Streams and Try Containers
 //
@@ -17,7 +17,7 @@
 // They do not block and return the output stream immediately. All the processing is done in the background by the goroutine pools they spawn.
 // These functions forward all errors from the input stream to the output stream.
 // Any errors returned by the user-provided functions are also sent to the output stream.
-// When such function reaches the end of the input stream, it closes the output stream, stops processing and cleans up resources.
+// When such a function reaches the end of the input stream, it closes the output stream, stops processing and cleans up resources.
 //
 // Such functions are designed to be composed together to build complex processing pipelines:
 //
@@ -55,7 +55,7 @@
 //
 // # Unordered functions
 //
-// Functions such as [Map], [Filter] and [FlatMap] write items to the output stream as soon as they become available.
+// Functions such as [Map], [Filter], and [FlatMap] write items to the output stream as soon as they become available.
 // Due to the concurrent nature of these functions, the order of items in the output stream may not match the order of items in the input stream.
 // These functions prioritize performance and concurrency over maintaining the original order.
 //
@@ -75,5 +75,5 @@
 // This allows the pipeline to terminate after the first error is encountered and return it to the caller.
 //
 // In cases where more complex error handling logic is required, the [Catch] function can be used.
-// It allows to catch and handle errors at any point in the pipeline, providing the flexibility to handle not only the first error, but any of them.
+// It can catch and handle errors at any point in the pipeline, providing the flexibility to handle not only the first error, but any of them.
 package rill

example123_test.go

@@ -4,27 +4,65 @@ package rill_test
 
 import (
 	"fmt"
-	"iter"
+	"slices"
 
 	"github.com/destel/rill"
 )
 
-func ExampleToSeq2() {
-	nums := rill.FromSeq2(genPositive(40))
-	squares := rill.Map(nums, 4, func(x int) (int, error) {
-		return x * x, nil
+func ExampleFromSeq() {
+	// Start with an iterator that yields numbers from 1 to 10
+	numbersSeq := slices.Values([]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10})
+
+	// Convert the iterator into a stream
+	numbers := rill.FromSeq(numbersSeq, nil)
+
+	// Transform each number
+	// Concurrency = 3
+	results := rill.Map(numbers, 3, func(x int) (int, error) {
+		return doSomethingWithNumber(x), nil
 	})
-	for val, err := range rill.ToSeq2(squares) {
-		fmt.Println(val, err)
-	}
+
+	printStream(results)
 }
 
-func genPositive(to int) iter.Seq2[int, error] {
-	return func(yield func(i int, err error) bool) {
-		for i := 1; i <= to; i++ {
+func ExampleFromSeq2() {
+	// Create an iter.Seq2 iterator that yields numbers from 1 to 10
+	numberSeq := func(yield func(int, error) bool) {
+		for i := 1; i <= 10; i++ {
 			if !yield(i, nil) {
 				return
 			}
 		}
 	}
+
+	// Convert the iterator into a stream
+	numbers := rill.FromSeq2(numberSeq)
+
+	// Transform each number
+	// Concurrency = 3
+	results := rill.Map(numbers, 3, func(x int) (int, error) {
+		return doSomethingWithNumber(x), nil
+	})
+
+	printStream(results)
+}
+
+func ExampleToSeq2() {
+	// Convert a slice of numbers into a stream
+	numbers := rill.FromSlice([]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, nil)
+
+	// Transform each number
+	// Concurrency = 3
+	results := rill.Map(numbers, 3, func(x int) (int, error) {
+		return doSomethingWithNumber(x), nil
+	})
+
+	// Convert the stream into an iterator and use for-range to print the results
+	for val, err := range rill.ToSeq2(results) {
+		if err != nil {
+			fmt.Println("Error:", err)
+			break // cleanup is done regardless of early exit
+		}
+		fmt.Printf("%+v\n", val)
+	}
 }