Initial commit for OSS release

Author: steve-gray

.gitignore

@@ -0,0 +1,12 @@
+# OS Cruft
+.DS_Store
+thumbs.db
+
+coverage.*
+*.log
+
+# Profiling stuff
+*.tmp
+*.test
+*.pdf
+*.out

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ZeroFlucs Labs Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,226 @@
+# zeroflucs generics
+
+[![GoDoc](https://godoc.org/github.com/zeroflucs-given/generics?status.svg)](https://godoc.org/github.com/zeroflucs-given/generics)
+
+![GitHub issues](https://img.shields.io/github/issues/zeroflucs-given/generics)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/y/zeroflucs-given/charybdis)
+
+---
+
+### Overview
+The `generics` package is a series of helpers for writing generic Go code that provides a series of functions that don't exist
+in the mainline package set.
+
+## About ZeroFlucs 
+[ZeroFlucs](https://zeroflucs.io) is a B2B provider of pricing technology for Sportsbooks/wagering service providers globally. We
+use Open-Source software through our platform stack. This, along with other projects is made available through our _zeroflucs-given_ 
+Github profile on MIT licensing. To learn more you can visit:
+
+- [The ZeroFlucs Website](https://zeroflucs.io) - For information about our products and services.
+- [The ZeroFlucs Team Blog](https://blog.zeroflucs.io/) - For more content and posts from the ZeroFlucs team.
+- [ZeroFlucs-Given](https://github.com/zeroflucs-given/) - For more OSS contributions.
+
+## Why Does this Exist?
+
+
+When writing Go code for Go 1.17 or below, we've all written more than our fair share of methods to check "does this slice contain a thing", or "give me the first item matching a predicate". This package contains a roll-up of helpers and methods, as well as generic collection types that enable a lot of this boilerplate code to be removed.
+
+Key attributes:
+ 
+  - Context support for filters/mappers (Optional)
+  - Does not mutate input during operation.
+
+All code is covered 100% by tests for expected behaviour. Where filters or mappers are used
+methods are provided with and without context support.
+
+# Slice Queries
+
+```
+package generics_test
+
+import (
+	"fmt"
+
+	"github.com/zeroflucs-given/generics/query"
+)
+
+func main() {
+	inputs := []int{
+		1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+	}
+	query := query.Slice(inputs)
+
+	result := query.
+		Skip(5).
+		TakeUntil(func(index int, v int) bool {
+			return v >= 15
+		}).
+		Filter(func(index int, v int) bool {
+			return v%2 == 0 // Evens only
+		}).
+		Reverse().
+        ToSlice() // Back to a clean slice type
+
+	fmt.Println(result) // [14, 12, 10, 8, 6]
+}
+```
+
+__But what about Contexts?__
+
+Don't worry, we've got you. Use `.WithContext(ctx)` on the query chain and the entire subtree is now context aware. Any materialization functions that emit an actual value will now return an extra `error` argument. Operations are lazy, and will skip over the remainder of any query chain once the first error has occured.
+
+```
+package generics_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/zeroflucs-given/generics/query"
+)
+
+func main() {
+	inputs := []int{
+		1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+	}
+	query := query.Slice(inputs)
+	ctx := context.Todo()
+
+	result, err := query.
+		WithContext(ctx).
+		Skip(5).
+		TakeUntil(func(ctx context.Context, index int, v int) (bool, error) {
+			return v >= 15, nil
+		}).
+		Filter(func(ctx context.Context, index int, v int) (bool, error)  {
+			return v%2 == 0, nil // Evens only
+		}).
+		Reverse().
+        ToSlice() // Back to a clean slice type
+
+	fmt.Println(result) // [14, 12, 10, 8, 6]
+	fmt.Println(err) // nil
+}
+```
+
+When dealing with slice operations, the following design rules apply:
+
+- Operations that return a single value will return the type default if no item matches (i.e. 0 for numeric types, empty string or nil for objects)
+- Operations that accept multiple filters combine these filters into a logical AND by default.
+- If no filters are applied, every item is assumed to pass.
+- Context aware operations only exist where it makes sense (i.e. Take first 5 doesn't need a context, whereas take with filtering does)
+
+## Operation Detail
+### All / AllContext
+Returns true if all items in the slice match the filter. Will return true for an empty
+slice as no items fail the predicate.
+
+### Any / AnyContext
+Returns true if any item in the slice passes.
+
+### Concatenate
+Joins N slices of items together in the given order. Allocates a new slice.
+
+### Contains
+Returns true if the slice contains the specified value T, false otherwise. Uses standard equality operator to compare types.
+
+### Count / CountContext
+Returns the count of items matching the input filters.
+
+### DefaultIfEmpty 
+Given a slice, if the slice is empty or nil will create a slice of a single default item.
+
+### Filter / FilterContext
+Creates a filtered set of the values in the slice, using a filter function.
+
+### First / FirstWithContext
+Returns the first item of the slice that matches the filters. If no value matches, returns
+the type default.
+
+### Group / GroupWithContext
+Uses a mapper function to assign input values to buckets.
+
+### Last / LastWithContext
+Returns the last item of the slice that matches the filter.
+
+### Map / MapWithContext
+Runs the specified mapper over each element of the input slice, creating an output slice of
+a different type.
+
+### Reverse
+Creates a reverse-sorted version of the input slice.
+
+### Skip
+Skip the first N elements of the slice.
+
+### SkipUntil / SkipUntilWithContext
+Skip items from the front of the slice until the predicate returns true.
+
+### SkipWhile / SkipWhileWithContext
+Skips items from the front of the slice until the predicate returns false.
+
+### Take
+Take the next N elements of the slice.
+
+### TakeUntil / TakeUntil
+Take items from the slice until the filter function returns true.
+
+### TakeWhile / TakeWhileWithContext
+Take items from the slice until the filter function returns false.
+
+### ToMap / ToMapWithContext
+Converts a slice of values to Go map, using mappers for the key and values respectively.
+
+
+## Slice Aggregations
+---------------
+### Min
+Returns the minimum value from the input slice. Returns 0 if no values.
+
+### Max
+Returns the maximum value from the input slice. Returns 0 if no values.
+
+### Sum
+Returns the total sum of the values. Note that when handling large values, you may overflow your input type.
+
+# Map Operations
+The following map operation helpers exist in the `generics` package:
+
+## KeyValuesToMap 
+Assembles a map from a slice of key-value pairs.
+
+## Keys
+Returns a slice of the key members of the map.
+
+## ToKeyValues
+Converts a map into a slice of key-value pairs. As per Go handling of maps, the order of
+output here is not in a guaranteed order.
+
+## Values
+Return a slice of the value members of the map.
+
+# Error Checking
+## Must
+Returns the first value in a pair of (T, error) if there is no error. Otherwise will panic.
+
+# Filter Building
+The `filtering` sub-package contains various constructs used to filter values.
+
+### True / TrueWithContext
+A constant value filter that always returns true. Useful for testing.
+
+### False / FalseWithContext
+A constant value filter that always returns false. Useful for testing.
+
+### And(...filters) / AndWithContext
+Creates a composite AND filter for multiple conditions. An empty set of filters is a true.
+
+### Or(...filters) / OrWithContext
+Creates a composite OR filter for multiple conditions. An empty set of filters is a false. 
+
+### Not(filter) / NotWithContext
+Creates a NOT/inverted version of the specified filter to allow for negative checking.
+
+### Wrap
+Takes a non-context aware filter, but makes it compatible with code that expects contexts.

aggregates.go

@@ -0,0 +1,48 @@
+package generics
+
+// Min gets the minumum of numeric values. If the slice is empty then
+// a value of 0 is returned.
+func Min[T Numeric](items []T) T {
+	var result T
+	if len(items) == 0 {
+		return result
+	} else {
+		result = items[0]
+	}
+
+	for _, v := range items {
+		if v < result {
+			result = v
+		}
+	}
+
+	return result
+}
+
+// Max gets the maximum of numeric values. If the slice is empty then
+// a value of 0 is returned.
+func Max[T Numeric](items []T) T {
+	var result T
+	if len(items) == 0 {
+		return result
+	} else {
+		result = items[0]
+	}
+
+	for _, v := range items {
+		if v > result {
+			result = v
+		}
+	}
+
+	return result
+}
+
+// Sum numeric values
+func Sum[T Numeric](items []T) T {
+	var result T
+	for _, v := range items {
+		result += v
+	}
+	return result
+}

aggregates_test.go

@@ -0,0 +1,68 @@
+package generics_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/zeroflucs-given/generics"
+)
+
+func TestMin(t *testing.T) {
+	// Arrange
+	input := []int{10, 14, 28, 5}
+	target := 5
+
+	// Act
+	result := generics.Min(input)
+
+	// Assert
+	require.Equal(t, result, target, "Should have the correct value")
+}
+
+func TestMinEmpty(t *testing.T) {
+	// Arrange
+	input := []int{}
+	target := 0
+
+	// Act
+	result := generics.Min(input)
+
+	// Assert
+	require.Equal(t, result, target, "Should have the correct value")
+}
+
+func TestMax(t *testing.T) {
+	// Arrange
+	input := []int{10, 14, 28, 5}
+	target := 28
+
+	// Act
+	result := generics.Max(input)
+
+	// Assert
+	require.Equal(t, result, target, "Should have the correct value")
+}
+
+func TestMaxEmpty(t *testing.T) {
+	// Arrange
+	input := []int{}
+	target := 0
+
+	// Act
+	result := generics.Max(input)
+
+	// Assert
+	require.Equal(t, result, target, "Should have the correct value")
+}
+
+func TestSum(t *testing.T) {
+	// Arrange
+	input := []int{10, 14, 28}
+	target := 52
+
+	// Act
+	result := generics.Sum(input)
+
+	// Assert
+	require.Equal(t, result, target, "Should have the correct value")
+}