{"id":13642721,"url":"https://github.com/DataDog/zstd","last_synced_at":"2025-04-20T20:32:29.183Z","repository":{"id":9529685,"uuid":"60188025","full_name":"DataDog/zstd","owner":"DataDog","description":"Zstd wrapper for Go","archived":false,"fork":false,"pushed_at":"2025-03-28T19:59:39.000Z","size":2376,"stargazers_count":763,"open_issues_count":12,"forks_count":98,"subscribers_count":637,"default_branch":"1.x","last_synced_at":"2025-04-13T10:50:11.642Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-06-01T15:16:13.000Z","updated_at":"2025-04-04T02:08:35.000Z","dependencies_parsed_at":"2024-06-06T12:00:26.378Z","dependency_job_id":"0c12c975-a8c2-4f02-a3dd-1a5188690e39","html_url":"https://github.com/DataDog/zstd","commit_stats":{"total_commits":142,"total_committers":25,"mean_commits":5.68,"dds":0.4577464788732394,"last_synced_commit":"5f14d6af117fa84b37f99d4cde775e6039be6d3b"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fzstd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fzstd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fzstd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fzstd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/zstd/tar.gz/refs/heads/1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249958919,"owners_count":21351736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:01:35.446Z","updated_at":"2025-04-20T20:32:29.172Z","avatar_url":"https://github.com/DataDog.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# Zstd Go Wrapper\n\n[![CircleCI](https://circleci.com/gh/DataDog/zstd/tree/1.x.svg?style=svg)](https://circleci.com/gh/DataDog/zstd/tree/1.x)\n[![GoDoc](https://godoc.org/github.com/DataDog/zstd?status.svg)](https://godoc.org/github.com/DataDog/zstd)\n\n\n[C Zstd Homepage](https://github.com/facebook/zstd)\n\nThe current headers and C files are from *v1.5.7* (Commit\n[f8745da](https://github.com/facebook/zstd/releases/tag/v1.5.7)).\n\n## Usage\n\nThere are two main APIs:\n\n* simple Compress/Decompress\n* streaming API (io.Reader/io.Writer)\n\nThe compress/decompress APIs mirror that of lz4, while the streaming API was\ndesigned to be a drop-in replacement for zlib.\n\n### Building against an external libzstd\n\nBy default, zstd source code is vendored in this repository and the binding will be built with\nthe vendored source code bundled.\n\nIf you want to build this binding against an external static or shared libzstd library, you can\nuse the `external_libzstd` build tag. This will look for the libzstd pkg-config file and extract\nbuild and linking parameters from that pkg-config file.\n\nNote that it requires at least libzstd 1.4.0.\n\n```bash\ngo build -tags external_libzstd\n```\n\n### Simple `Compress/Decompress`\n\n\n```go\n// Compress compresses the byte array given in src and writes it to dst.\n// If you already have a buffer allocated, you can pass it to prevent allocation\n// If not, you can pass nil as dst.\n// If the buffer is too small, it will be reallocated, resized, and returned by the function\n// If dst is nil, this will allocate the worst case size (CompressBound(src))\nCompress(dst, src []byte) ([]byte, error)\n```\n\n```go\n// CompressLevel is the same as Compress but you can pass another compression level\nCompressLevel(dst, src []byte, level int) ([]byte, error)\n```\n\n```go\n// Decompress will decompress your payload into dst.\n// If you already have a buffer allocated, you can pass it to prevent allocation\n// If not, you can pass nil as dst (allocates a 4*src size as default).\n// If the buffer is too small, it will retry 3 times by doubling the dst size\n// After max retries, it will switch to the slower stream API to be sure to be able\n// to decompress. Currently switches if compression ratio \u003e 4*2**3=32.\nDecompress(dst, src []byte) ([]byte, error)\n```\n\n### Stream API\n\n```go\n// NewWriter creates a new object that can optionally be initialized with\n// a precomputed dictionary. If dict is nil, compress without a dictionary.\n// The dictionary array should not be changed during the use of this object.\n// You MUST CALL Close() to write the last bytes of a zstd stream and free C objects.\nNewWriter(w io.Writer) *Writer\nNewWriterLevel(w io.Writer, level int) *Writer\nNewWriterLevelDict(w io.Writer, level int, dict []byte) *Writer\n\n// Write compresses the input data and write it to the underlying writer\n(w *Writer) Write(p []byte) (int, error)\n\n// Flush writes any unwritten data to the underlying writer\n(w *Writer) Flush() error\n\n// Close flushes the buffer and frees C zstd objects\n(w *Writer) Close() error\n```\n\n```go\n// NewReader returns a new io.ReadCloser that will decompress data from the\n// underlying reader.  If a dictionary is provided to NewReaderDict, it must\n// not be modified until Close is called.  It is the caller's responsibility\n// to call Close, which frees up C objects.\nNewReader(r io.Reader) io.ReadCloser\nNewReaderDict(r io.Reader, dict []byte) io.ReadCloser\n```\n\n### Benchmarks (benchmarked with v0.5.0)\n\nThe author of Zstd also wrote lz4. Zstd is intended to occupy a speed/ratio\nlevel similar to what zlib currently provides.  In our tests, the can always\nbe made to be better than zlib by chosing an appropriate level while still\nkeeping compression and decompression time faster than zlib.\n\nYou can run the benchmarks against your own payloads by using the Go benchmarks tool.\nJust export your payload filepath as the `PAYLOAD` environment variable and run the benchmarks:\n\n```go\ngo test -bench .\n```\n\nCompression of a 7Mb pdf zstd (this wrapper) vs [czlib](https://github.com/DataDog/czlib):\n```\nBenchmarkCompression               5     221056624 ns/op      67.34 MB/s\nBenchmarkDecompression           100      18370416 ns/op     810.32 MB/s\n\nBenchmarkFzlibCompress             2     610156603 ns/op      24.40 MB/s\nBenchmarkFzlibDecompress          20      81195246 ns/op     183.33 MB/s\n```\n\nRatio is also better by a margin of ~20%.\nCompression speed is always better than zlib on all the payloads we tested;\nHowever, [czlib](https://github.com/DataDog/czlib) has optimisations that make it\nfaster at decompressiong small payloads:\n\n```\nTesting with size: 11... czlib: 8.97 MB/s, zstd: 3.26 MB/s\nTesting with size: 27... czlib: 23.3 MB/s, zstd: 8.22 MB/s\nTesting with size: 62... czlib: 31.6 MB/s, zstd: 19.49 MB/s\nTesting with size: 141... czlib: 74.54 MB/s, zstd: 42.55 MB/s\nTesting with size: 323... czlib: 155.14 MB/s, zstd: 99.39 MB/s\nTesting with size: 739... czlib: 235.9 MB/s, zstd: 216.45 MB/s\nTesting with size: 1689... czlib: 116.45 MB/s, zstd: 345.64 MB/s\nTesting with size: 3858... czlib: 176.39 MB/s, zstd: 617.56 MB/s\nTesting with size: 8811... czlib: 254.11 MB/s, zstd: 824.34 MB/s\nTesting with size: 20121... czlib: 197.43 MB/s, zstd: 1339.11 MB/s\nTesting with size: 45951... czlib: 201.62 MB/s, zstd: 1951.57 MB/s\n```\n\nzstd starts to shine with payloads \u003e 1KB\n\n### Stability - Current state: STABLE\n\nThe C library seems to be pretty stable and according to the author has been tested and fuzzed.\n\nFor the Go wrapper, the test cover most usual cases and we have succesfully tested it on all staging and prod data.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDataDog%2Fzstd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDataDog%2Fzstd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDataDog%2Fzstd/lists"}