gopkg

README

gopkg

This repository contains many frequently used small packages, it is designed to have reasonable trade-off between generic, performance and API friendliness. It helps to make life easier!

Status

The master branch (v2) requires Go 1.18+, it uses the generics feature available in Go 1.18+. For version compatibility policy, please refer to the following docs.

The v1 branch contains the legacy code. there shall be no further changes to the v1 APIs.

Code layout

Packages under exp directory are considered experimental and unreliable, the API may change arbitrarily, or even disappear some day without any notice. They do not follow the Go 1 compatibility promise. When a package is tested enough, and the API is considered stable, it may be promoted as "stable" and moved under the top directory.

Packages under the top directory are considered stable, they follow the Go 1 compatibility promise and the Semantic Versioning spec. Packages under the top directory may depend on exp packages but must keep reasonable API compatibility and versioning.

Packages

1. collection/heapx contains a ready-to-use heap implementation based on container/heap, and a generic priority queue based on heap data structure.

2. collection/set provides generic set data structures.

3. confr provides a simple yet powerful configuration loader.

4. easy contains many handy utilities as a complementary to the standard library.

5. easy/ezdbg provides easy to use utilities which helps to do quick logging in development.

6. easy/ezhttp contains some utilities to work with HTTP requests.

7. easy/ezmap contains some utilities to manipulate map data structure.

8. easy/yamlx extends the YAML unmarshaler with extra features, such as "reading environment variables" and "file including", "reference using gjson JSON path expression", "reference using named variables", "function calling", etc.

9. encrypt/crypto contains some encryption utilities.

10. exp/kvutil contains experimental utilities to work with key-value cache.

11. infra/acache contains an async cache which can be used to fetch and update the latest data periodically and supports expiring a key if it's unused for a period.

12. infra/errcode provides error code registry to manage error codes and messages. Standardized error codes greatly helps in large scale microservices.

13. infra/logid provides log ID generators to help service observability, such as tracing, metrics, etc.

14. perf/bbp provides efficient byte buffer pools with anti-memory-waste protection.

15. perf/gopool is a fork of github.com/bytedance/gopkg/util/gopool with opinionated changes. It's a high-performance goroutine pool which aims to reuse goroutines and limit the number of goroutines.

16. perf/json provides a drop-in replacement of encoding/json and extended features. By default, it uses jsoniter in underlying, which has better performance than encoding/json. The underlying implementation is change-able and change-able on-the-fly. amd64 users may switch to bytedance/sonic implementation for best performance in the cost of a little less maturity. Check README.md for detailed introduction.

17. perf/lru is a high performance implementation of the LRU cache, it features pre-allocation, item expiration, friendly and type-safe APIs for commonly used key types. It also provides a sharded version for heavy lock contention use-case.

18. unsafe/forceexport force exports private types and functions of other packages. As you might expect, this package is unsafe and fragile and shouldn't be used in production, it is mainly for testing purpose.

19. unsafe/reflectx contains many utilities to work with reflection, providing convenient APIs or better performance.

20. utils/ptr provides small functions to work with pointer types, such as copying value as pointer, converting integer to string pointer, or dereference pointer which may be nil, etc. It helps to reduce duplicate code and makes code clearer and simpler.

21. utils/retry implements frequently used strategies and options to do retry when error occurs, with various hooks and circuit breaker to protect system overload.

22. utils/sqlutil provides utilities to work with relational database ORM libraries, it keeps simple and can work with database/sql and many ORM libraries.

23. utils/structtag contains some handy utilities to work with struct tags.

24. utils/strutil provides utilities to work with string data as supplement to the standard libraries strings and unicode/utf8.

25. utils/timeutil provides utilities to process time related things.

26. utils/vdutil helps to do data validation.

27. zlog provides opinionated high-level logging facilities based on go.uber.org/zap.

See GoDoc for detailed online docs.

Also note that the following packages, which were originally located in this repository, have been moved to standalone repositories:

1. base62 is a compact and high performance implementation of base62 algorithm for Golang. It has been moved to https://github.com/jxskiss/base62.

2. mcli is a minimal but very powerful and magic cli library for Go. It has been moved to https://github.com/jxskiss/mcli.