generic

README

GoExts Generic Utilities

A modern, robust, and type-safe collection of generic utilities for Go, designed to solve common problems with elegant, high-performance APIs. This library aims to be the foundational toolkit for modern Go development.

Status: Stable - This project is production-ready and follows semantic versioning.

Features

• 🚀 Type-Safe: Built with Go 1.18+ generics for type safety
• ⚡ High Performance: Optimized for performance with zero or minimal allocations
• 🧩 Modular: Independent packages that can be used separately
• 🛠 Well-Tested: Comprehensive test coverage
• 📚 Well-Documented: Complete API documentation and examples

Quick Start

Installation

go get github.com/goexts/generic@latest

Basic Usage

package main

import (
	"fmt"
	"github.com/goexts/generic/maps"
	"github.com/goexts/generic/slices"
)

func main() {
	// Working with slices
	nums := []int{1, 2, 3, 4, 5}
	doubled := slices.Map(nums, func(x int) int { return x * 2 })
	filtered := slices.Filter(doubled, func(x int) bool { return x > 5 })
	
	fmt.Println("Original:", nums)      // [1 2 3 4 5]
	fmt.Println("Doubled:", doubled)    // [2 4 6 8 10]
	fmt.Println("Filtered:", filtered)  // [6 8 10]

	// Working with maps
	m := map[string]int{"a": 1, "b": 2, "c": 3}
	keys := maps.Keys(m)  // [a b c] (order not guaranteed)
	values := maps.Values(m)  // [1 2 3] (order not guaranteed)
	
	fmt.Println("Keys:", keys)      // [a b c]
	fmt.Println("Values:", values)  // [1 2 3]
}

Documentation

For complete documentation, please visit:

• API Documentation
• Examples
• Contributing Guide

Core Packages

This project provides a rich set of independent, generic packages:

• cast: Provides safe, generic type-casting functions.
• cmp: Generic comparison functions for sorting and ordering complex types.
• cond: Functions for conditional (ternary-like) operations.
• configure: A powerful, production-grade implementation of the Functional Options Pattern, with advanced support for compilation workflows.
• maps: A suite of generic functions for common map operations (e.g., Keys, Values, Clone).
• must: Panic-on-error wrappers (must.Must) for cleaner code in contexts where an error is considered a fatal condition (e.g., during initialization).
• promise: A generic, JavaScript-like Promise implementation for managing asynchronous operations.
• ptr: Helper functions (ptr.To) for creating pointers from literal values.
• res: A generic, Rust-inspired Result[T, E] type for expressive, explicit error handling.
• set: A generic Set data structure implementation with common set operations.
• slices: A comprehensive suite of generic functions for common slice operations, with specialized sub-packages for bytes and runes.
• strings: Generic utilities for string manipulation and conversion.

Installation

go get github.com/goexts/generic

Featured Package: configure

To showcase the design philosophy of this library, here is a quick look at the configure package. It provides a best-in-class toolset for object creation, enabling a clean separation of concerns between building a configuration object and compiling a final product.

The following example demonstrates how to create a fully configured *http.Client from a dedicated ClientConfig object:

package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/goexts/generic/configure"
)

// 1. Define your configuration object and its options.
type ClientConfig struct {
	Timeout   time.Duration
	Transport http.RoundTripper
}

type Option = configure.Option[ClientConfig]

func WithTimeout(d time.Duration) Option {
	return func(c *ClientConfig) { c.Timeout = d }
}

func WithTransport(rt http.RoundTripper) Option {
	return func(c *ClientConfig) { c.Transport = rt }
}

// 2. Define your factory function (the "compiler").
func NewHttpClient(c *ClientConfig) (*http.Client, error) {
	return &http.Client{
		Timeout:   c.Timeout,
		Transport: c.Transport,
	}, nil
}

func main() {
	// 3. Use the Builder to collect options, then use Compile to create the final product.
	configBuilder := configure.NewBuilder[ClientConfig]().
		Add(WithTimeout(20 * time.Second)).
		Add(WithTransport(http.DefaultTransport))

	httpClient, err := configure.Compile(configBuilder, NewHttpClient)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Successfully created http.Client with timeout: %s\n", httpClient.Timeout)
}

Contributing

We welcome all contributions! Here's how you can help:

1. Report bugs by opening an issue
2. Suggest new features or improvements
3. Submit pull requests

Please read our Contributing Guide and Code of Conduct for details on the process for submitting pull requests and how we work together.

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/generic.git
3. Run tests: go test ./...
4. Make your changes and submit a pull request

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Chat: Gitter (coming soon)

Related Projects

• GoExts - Collection of Go extensions and utilities
• Go Standard Library - The Go standard library that this project extends

Stargazers over time

License

This project is licensed under the MIT License. See the LICENSE file for details.