{"id":46371949,"url":"https://github.com/mus-format/mus-go","last_synced_at":"2026-04-12T16:23:34.171Z","repository":{"id":157669551,"uuid":"632925238","full_name":"mus-format/mus-go","owner":"mus-format","description":"MUS format serializer for Go","archived":false,"fork":false,"pushed_at":"2026-02-25T16:29:33.000Z","size":275,"stargazers_count":120,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-25T19:54:26.521Z","etag":null,"topics":["go","golang","graph","linked-list","mus","serialization","serializer","validation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mus-format.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"ymzncnk"}},"created_at":"2023-04-26T12:13:30.000Z","updated_at":"2026-02-25T16:29:58.000Z","dependencies_parsed_at":"2024-05-06T23:24:56.614Z","dependency_job_id":"aeee35f1-e18b-4475-9a1d-093c64e28edb","html_url":"https://github.com/mus-format/mus-go","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/mus-format/mus-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mus-format%2Fmus-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mus-format%2Fmus-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mus-format%2Fmus-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mus-format%2Fmus-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mus-format","download_url":"https://codeload.github.com/mus-format/mus-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mus-format%2Fmus-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30109201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["go","golang","graph","linked-list","mus","serialization","serializer","validation"],"created_at":"2026-03-05T04:09:09.199Z","updated_at":"2026-04-12T16:23:34.155Z","avatar_url":"https://github.com/mus-format.png","language":"Go","funding_links":["https://ko-fi.com/ymzncnk"],"categories":["Serialization"],"sub_categories":["HTTP Clients"],"readme":"# mus: A High-Performance, Flexible Binary Serialization Library for Go\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/mus-format/mus-go.svg)](https://pkg.go.dev/github.com/mus-format/mus-go)\n[![GoReportCard](https://goreportcard.com/badge/mus-format/mus-go)](https://goreportcard.com/report/github.com/mus-format/mus-go)\n[![codecov](https://codecov.io/gh/mus-format/mus-go/graph/badge.svg?token=WLLZ1MMQDX)](https://codecov.io/gh/mus-format/mus-go)\n\n**mus** is a powerful and versatile Go library for efficient binary\nserialization.\n\nWhile `mus` was built as a serializer for the [MUS format](https://medium.com/@ymz-ncnk/mus-serialization-format-20f833df12d5),\nits minimalist architecture and broad set of serialization primitives also make\nit well-suited for implementing other binary formats. Here you can find an\n[example](https://github.com/mus-format/examples-go/tree/main/protobuf)\nwhere it is used to encode data in Protobuf format.\n\nA streaming version is also available: [mus-stream](https://github.com/mus-format/mus-stream-go).\n\n## Why mus?\n\n### Core Performance \u0026 Reliability\n\n- Top-tier performance (see [benchmarks](#benchmarks)).\n- Space-efficient data serialization.\n- Robust and reliable.\n- Cross-architecture compatible (32/64-bit systems).\n\n### Advanced Capabilities\n\n- Supports data versioning and interface serialization (oneof feature) using the [typed](#typed-data-type-metadata-support) package.\n- Comprehensive pointer support.\n- Can encode cyclic graphs and linked lists.\n- Offers zero-allocation deserialization.\n\n### Additional Features\n\n- Validation and field skipping during unmarshalling.\n- Supports private fields.\n- Out-of-order deserialization.\n\n## mus in Action: cmd-stream\n\nWant to see it in action? Check out [cmd-stream](https://github.com/cmd-stream/cmd-stream-go)!\nThis library, based on the Command Pattern, enables efficient execution of\nuser-defined Commands on a server. The `cmd-stream/MUS` is about 3 times faster\nthan `gRPC/Protobuf`.\n\n## Code Generation (Recommended)\n\nImplementing `mus` serializers manually can be tedious and error-prone. There\nare two ways to automate this:\n\n- [mus-gen](https://github.com/mus-format/mus-gen-go) — a traditional code \n  generator. Simply provide a type and call `Generate()`.\n- [mus-skill](https://github.com/mus-format/mus-skill-go) — an AI agent skill to\n  produce serialization code.\n\n## Quick Start\n\nHere's an example of how to use `mus` to serialize a number.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"github.com/mus-format/mus-go/varint\"\n)\n\nfunc main() {\n  var (\n    num  = 100\n    size = varint.Int.Size(num)\n    bs   = make([]byte, size)\n  )\n  \n  // Marshal\n  varint.Int.Marshal(num, bs)\n  \n  // Unmarshal\n  val, n, err := varint.Int.Unmarshal(bs)\n  if err != nil {\n    panic(err)\n  }\n  \n  fmt.Printf(\"Unmarshalled %d (%d bytes used)\\n\", val, n)\n}\n```\n\n## Contents\n\n- [mus: A High-Performance, Flexible Binary Serialization Library for Go](#mus-a-high-performance-flexible-binary-serialization-library-for-go)\n  - [Why mus?](#why-mus)\n    - [Core Performance \\\u0026 Reliability](#core-performance--reliability)\n    - [Advanced Capabilities](#advanced-capabilities)\n    - [Additional Features](#additional-features)\n  - [mus in Action: cmd-stream](#mus-in-action-cmd-stream)\n  - [Code Generation (Recommended)](#code-generation-recommended)\n  - [Quick Start](#quick-start)\n  - [Contents](#contents)\n  - [How To](#how-to)\n  - [Packages](#packages)\n    - [varint](#varint)\n    - [raw](#raw)\n    - [ord (ordinary)](#ord-ordinary)\n    - [unsafe](#unsafe)\n    - [pm (pointer mapping)](#pm-pointer-mapping)\n    - [typed (data type metadata support)](#typed-data-type-metadata-support)\n  - [Structs Support](#structs-support)\n  - [More Features](#more-features)\n  - [Testing](#testing)\n    - [Fuzz Testing](#fuzz-testing)\n  - [Benchmarks](#benchmarks)\n  - [Contributing \u0026 Security](#contributing--security)\n  - [Version Compatibility](#version-compatibility)\n\n## How To\n\nTo make a type serializable with `mus`, you need to implement the\n[mus.Serializer](./mus.go) interface:\n\n```go\nimport \"github.com/mus-format/mus-go\"\n\n// YourTypeMUS is a MUS serializer for YourType.\nvar YourTypeMUS = yourTypeMUS{}\n\n// yourTypeMUS implements the mus.Serializer interface.\ntype yourTypeMUS struct{}\n\nfunc (s yourTypeMUS) Marshal(v YourType, bs []byte) (n int)              {...}\nfunc (s yourTypeMUS) Unmarshal(bs []byte) (v YourType, n int, err error) {...}\nfunc (s yourTypeMUS) Size(v YourType) (size int)                         {...}\nfunc (s yourTypeMUS) Skip(bs []byte) (n int, err error)                  {...}\n```\n\nThen, you can use it as follows:\n\n```go\nvar (\n  value YourType = ...\n  size = YourTypeMUS.Size(value) // The number of bytes required to serialize \n  // the value.\n  bs = make([]byte, size)\n)\n\nn := YourTypeMUS.Marshal(value, bs) // Returns the number of used bytes.\nvalue, n, err := YourTypeMUS.Unmarshal(bs) // Returns the value, the number of \n// used bytes and any error encountered.\n\n// Instead of unmarshalling the value can be skipped:\nn, err := YourTypeMUS.Skip(bs)\n```\n\n## Packages\n\n`mus` offers several encoding options, each in a separate package.\n\n| Package                                          | Use Case                                 | Key Strength                  | Trade-off                            |\n| :----------------------------------------------- | :--------------------------------------- | :---------------------------- | :----------------------------------- |\n| **[`varint`](#varint)**                          | Numbers                                  | Space efficient               | Slight CPU cost for encoding         |\n| **[`raw`](#raw)**                                | Numbers, Time                            | Fast encoding                 | Higher space usage for small numbers |\n| **[`ord`](#ord-ordinary)**                       | Pointers, Strings, Slices, Maps          | Variable-length types support | Standard allocations                 |\n| **[`unsafe`](#unsafe)**                          | High-perf Numbers, Time, Strings, Arrays | Zero-allocation               | Uses unsafe type conversions         |\n| **[`pm`](#pm-pointer-mapping)**                  | Pointers, Cyclic Graphs, Linked Lists    | Preserves pointer equality    | Slightly more complex than `ord`     |\n| **[`typed`](#typed-data-type-metadata-support)** | Interface/Versioning                     | Typed serialization           | Requires DTM definition              |\n\n### varint\n\nThis package provides Varint serializers for all `uint` (e.g., `uint64`,\n`uint32`, ...), `int`, `float`, and `byte` data types. It also includes the \n`PositiveInt` serializer (Varint without ZigZag) for efficiently encoding \npositive `int` values (negative values are supported as well, though with \nreduced performance).\n\n### raw\n\nThis package contains Raw serializers for `byte`, `uint`, `int`, `float`, and\n`time.Time` data types.\n\nMore details about Varint and Raw encodings can be found in the\n[MUS format specification](https://github.com/mus-format/specification).\nIf in doubt, use Varint.\n\nFor `time.Time`, there are several serializers:\n\n- `TimeUnix` – encodes a value as a Unix timestamp in seconds.\n- `TimeUnixMilli` – encodes a value as a Unix timestamp in milliseconds.\n- `TimeUnixMicro` – encodes a value as a Unix timestamp in microseconds.\n- `TimeUnixNano` – encodes a value as a Unix timestamp in nanoseconds.\n\nTo ensure the deserialized `time.Time` value is in UTC, either set your TZ\nenvironment variable to UTC (e.g., `os.Setenv(\"TZ\", \"\")`) or use one of the\ncorresponding UTC serializers (e.g., `TimeUnixUTC`, `TimeUnixMilliUTC`).\n\n### ord (ordinary)\n\nContains serializers/constructors for `bool`, `string`, `byte slice`,\n`slice`, `map`, and `pointer` types.\n\nVariable-length data types (such as `string`, `slice`, and `map`) are\nencoded as `length + data`, with customizable binary representations for both\nparts. By default, the length is encoded using `varint.PositiveInt`, which \nlimits the length to the maximum value of the `int` type on your system. Such \nencoding works well across different architectures. For example, an attempt to \nunmarshal a string that is too long on a 32-bit system will result in an \n`ErrOverflow`.\n\nFor `slice` and `map` types, only constructors are available ([examples](https://github.com/mus-format/examples-go/tree/main/types)).\n\n### unsafe\n\nThe `unsafe` package provides maximum performance by using unsafe type \nconversions. This primarily affects the `string` type, where modifying the \nunderlying byte slice after unmarshalling will also change the string's contents \n([example](https://github.com/mus-format/examples-go/tree/main/unsafe)).\n\nProvides serializers for the following data types: `byte`, `bool`, `string`,\n`array`, `byte slice`, `time.Time` and all `uint`, `int`, `float`.\n\n### pm (pointer mapping)\n\nLet's consider two pointers initialized with the same value:\n\n```go\nvar (\n  str = \"hello world\"\n  ptr = \u0026str\n\n  ptr1 *string = ptr\n  ptr2 *string = ptr\n)\n```\n\nThe `pm` package preserves pointer equality after unmarshalling, ensuring that\n`ptr1 == ptr2`, while the `ord` package does not. This capability enables the \nserialization of data structures like cyclic graphs or linked lists ([examples](https://github.com/mus-format/examples-go/tree/main/pm)).\n\n### typed (data type metadata support)\n\nThe `typed` package provides [DTM](https://medium.com/p/21d7be309e8d) \nsupport for the `mus` serializer. It wraps a type serializer and a DTM \nvalue, enabling [typed data serialization](https://ymz-ncnk.medium.com/mus-serialization-format-20f833df12d5)\nto provide data versioning, the oneof feature, and [other capabilities](https://github.com/mus-format/examples-go/tree/main/typed).\n\n## Structs Support\n\n`mus` doesn’t support structs out of the box, which means you’ll need to \nimplement the `mus.Serializer` interface yourself. Simply deconstruct the struct\ninto its fields and choose the desired encoding for each ([example](https://github.com/mus-format/examples-go/tree/main/types/struct)).\nThis approach provides greater flexibility and keeps `mus` simple, making it \neasy to implement in other programming languages.\n\n## More Features\n\n- **Validation**: Validate data during unmarshalling with a custom function:\n  `func(v Type) error` ([examples](https://github.com/mus-format/examples-go/tree/main/validation)).\n- **Out-of-Order Deserialization**: Decode fields partially or non-sequentially \n  for greater efficiency ([example](https://github.com/mus-format/examples-go/tree/main/out_of_order)).\n- **Zero-Allocation**: Use the `unsafe` package to achieve zero-allocation \n  deserialization.\n  \n## Testing\n\nTo run all `mus` tests, use the following command:\n\n```bash\ngo test ./...\n```\n\n### Fuzz Testing\n\n`mus` also includes fuzz tests. To run them, you can use the `fuzz.sh` script:\n\n```bash\n./fuzz.sh 10s\n```\n\nOr you can run a specific fuzz test using the `go test` command:\n\n```bash\ngo test -v -fuzz=\"^FuzzByte$\" ./varint -fuzztime 10s\n```\n\n## Benchmarks\n\n| NAME     | NS/OP   | B/SIZE | B/OP   | ALLOCS/OP |\n| -------- | ------- | ------ | ------ | --------- |\n| mus      | 102.90  | 58.00  | 48.00  | 1         |\n| protobuf | 531.70  | 69.00  | 271.00 | 4         |\n| json     | 2779.00 | 150.00 | 600.00 | 9         |\n\nThe data above is sourced from the [ymz-ncnk/go-serialization-benchmarks](https://github.com/ymz-ncnk/go-serialization-benchmarks) repository.\n\nWhy a separate benchmark suite? The [standard go-serialization-benchmarks](https://github.com/alecthomas/go_serialization_benchmarks) \nsometimes produce inconsistent results across multiple runs. New \n[benchmarks](https://github.com/ymz-ncnk/go-serialization-benchmarks) were \ncreated to provide more consistent and reproducible measurements for \naccurate comparison.\n\n## Contributing \u0026 Security\n\nWe welcome contributions of all kinds! Please see [CONTRIBUTING.md](CONTRIBUTING.md) \nfor details on how to get involved.\n\nIf you find a security vulnerability, please refer to our \n[Security Policy](SECURITY.md) for instructions on how to report it privately.\n\n## Version Compatibility\n\nFor a complete list of compatible module versions, see [VERSIONS.md](VERSIONS.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmus-format%2Fmus-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmus-format%2Fmus-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmus-format%2Fmus-go/lists"}