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 v1 branch contains the legacy code. there shall be no further changes to the v1 APIs.

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.

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 try to 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. bbp provides efficient byte buffer pools with anti-memory-waste protection.

2. confr provides a simple but powerful configuration loader.

3. easy contains many handy utilities as a complementary to the standard library, it really makes life easier.

4. encrypt contains some encryption utilities.

5. errcode provides a registry to manage error codes and messages.

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

7. fastrand exported a set of pseudo-random generator methods wrapped around the fastrand function from the Go runtime. There is a generator per-M (physical thread), thus it doesn't need to do synchronization when generate random sequence, which makes it very scalable.

8. 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.

9. gemap contains some utilities to manipulate map data structure.

10. json provides a drop-in replacement of encoding/json and extended features. When compiled with tag unsafejson, it uses the goccy/go-json in underlying, which has much better performance then encoding/json and many other third-party libraries. Check json/README.md for detailed introduction.

11. 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.

12. monkey provides a method to do testing using the monkey-patch pattern.

13. 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.

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

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

16. rthash exposes the various hash functions in runtime package.

17. set provides generic set data structures.

18. singleflight 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. To be easy to use, it also re-exports Group and Result as alias names from package "golang.org/x/sync/singleflight".

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

20. structtag contains some handy utilities to work with struct tags.

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

22. syncx contains some synchronization primitives as an addition to the standard library, for better performance or alternative APIs.

23. zlog provides a common logger interface which is implemented by many logging libraries, and some opinionated logging facilities wrapped around zap.

See https://pkg.go.dev/github.com/jxskiss/gopkg 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 cli library for Go. It has been moved to https://github.com/jxskiss/mcli.

3. timingwheel is an experimental implementation of the timing wheel algorithm. It has been moved to https://github.com/jxskiss/timingwheel.

4. extjson is a powerful parser for extended JSON data, such as trailing comma, comments, and many more extended features, it helps in many scenes (e.g. data driven testing by JSON files).

   The code which is originally located in package json, has been moved to its own repository at https://github.com/jxskiss/extjson.

5. ezdbg provides easy to use utilities which helps to do quick development. The code is originally located in package easy, but has been moved to its own repository at http://github.com/jxskiss/ezdbg.