{"id":24071002,"url":"https://github.com/markrosemaker/ordmap","last_synced_at":"2025-10-28T11:45:30.276Z","repository":{"id":270127906,"uuid":"909407209","full_name":"MarkRosemaker/ordmap","owner":"MarkRosemaker","description":"Provides a generic ordered map implementation, primarily designed for JSON v2 marshalling and unmarshalling. Includes helper functions to easily define your own custom ordered maps with minimal boilerplate code.","archived":false,"fork":false,"pushed_at":"2025-01-14T20:56:14.000Z","size":671,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-14T21:44:24.610Z","etag":null,"topics":[],"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/MarkRosemaker.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}},"created_at":"2024-12-28T16:01:14.000Z","updated_at":"2025-01-14T20:56:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"d66fc08a-0713-43e3-a228-556ec3fe0de8","html_url":"https://github.com/MarkRosemaker/ordmap","commit_stats":null,"previous_names":["markrosemaker/ordmap"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkRosemaker%2Fordmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkRosemaker%2Fordmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkRosemaker%2Fordmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkRosemaker%2Fordmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarkRosemaker","download_url":"https://codeload.github.com/MarkRosemaker/ordmap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240935616,"owners_count":19881169,"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":"2025-01-09T16:24:12.454Z","updated_at":"2025-10-28T11:45:30.187Z","avatar_url":"https://github.com/MarkRosemaker.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ordered Map\n[![Go Reference](https://pkg.go.dev/badge/github.com/MarkRosemaker/ordmap.svg)](https://pkg.go.dev/github.com/MarkRosemaker/ordmap)\n[![Go Report Card](https://goreportcard.com/badge/github.com/MarkRosemaker/ordmap)](https://goreportcard.com/report/github.com/MarkRosemaker/ordmap)\n![Code Coverage](https://img.shields.io/badge/coverage-98.5%25-brightgreen)\n[![License: **MIT**](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"ordmap logo: a gopher holding a map, surrounded by keys\" src=logo.jpg width=300\u003e\n\u003c/p\u003e\n\n`ordmap` is a Go package that provides a generic ordered map implementation, primarily designed for JSON v2 marshalling and unmarshalling using the [go-json-experiment](https://github.com/go-json-experiment/json) library.\n\nAn ordered map maintains the order of keys based on insertion, allowing you to iterate over the map in the order in which entries were added. This can be particularly useful for applications where the order of elements is important, such as in JSON serialization or when maintaining the sequence of operations.\n\n## Features\n\n- **Seamless JSON v2 Integration:** Directly integrates with the [JSON v2](https://github.com/go-json-experiment/json) library for efficient and order-preserving marshalling and unmarshalling.\n- **Custom Ordered Maps:** Provides robust helper functions to easily define your own custom ordered maps with minimal boilerplate code.\n- **Pre-Defined Ordered Map Alias:** Simplifies usage by offering a pre-defined ordered map type that can be conveniently aliased for specific key and value types.\n- **Efficient Ordered Operations:** Ensures efficient insertion, retrieval, and iteration while maintaining the order of elements, making it ideal for use cases where order matters.\n- **Ordered Iteration:** Leverages the `ByIndex` method to iterate over the map in an ordered manner based on the insertion sequence.\n\n## Installation\n\nTo install the library, use the following command:\n\n```shell\ngo get github.com/MarkRosemaker/ordmap\n```\n\n## Usage\n\n### Custom Ordered Map\n\nTo create your own custom ordered map, you can utilize helper functions to define its methods:\n\n```go\npackage main\n\nimport (\n\t\"iter\"\n\n\t\"github.com/MarkRosemaker/ordmap\"\n\t\"github.com/go-json-experiment/json\"\n\t\"github.com/go-json-experiment/json/jsontext\"\n)\n\ntype MyOrderedMap map[string]*ValueWithIndex\n\ntype ValueWithIndex struct {\n\tFoo string `json:\"foo\"`\n\tBar int    `json:\"bar\"`\n\n\tidx int // to order a map of this type\n}\n\nfunc getIndex(v *ValueWithIndex) int                    { return v.idx }\nfunc setIndex(v *ValueWithIndex, i int) *ValueWithIndex { v.idx = i; return v }\n\n// ByIndex returns a sequence of key-value pairs ordered by index.\nfunc (om MyOrderedMap) ByIndex() iter.Seq2[string, *ValueWithIndex] {\n\treturn ordmap.ByIndex(om, getIndex)\n}\n\n// Sort sorts the map by key and sets the indices accordingly.\nfunc (om MyOrderedMap) Sort() {\n\tordmap.Sort(om, setIndex)\n}\n\n// Set sets a value in the map, adding it at the end of the order.\nfunc (om *MyOrderedMap) Set(key string, v *ValueWithIndex) {\n\tordmap.Set(om, key, v, getIndex, setIndex)\n}\n\n// MarshalJSONTo marshals the key-value pairs in order.\nfunc (om *MyOrderedMap) MarshalJSONTo(enc *jsontext.Encoder, opts json.Options) error {\n\treturn ordmap.MarshalJSONTo(om, enc, opts)\n}\n\n// UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.\nfunc (om *MyOrderedMap) UnmarshalJSONFrom(dec *jsontext.Decoder, opts json.Options) error {\n\treturn ordmap.UnmarshalJSONFrom(om, dec, opts, setIndex)\n}\n```\n\nIf you prefer the map values to be non-pointer types, you can adjust the implementation as follows:\n\n```go\ntype MyOrderedMap map[string]ValueWithIndex\n\nfunc getIndex(v ValueWithIndex) int                   { return v.idx }\nfunc setIndex(v ValueWithIndex, i int) ValueWithIndex { v.idx = i; return v }\n\nfunc (om MyOrderedMap) ByIndex() iter.Seq2[string, ValueWithIndex] {\n\treturn ordmap.ByIndex(om, getIndex)\n}\n\nfunc (om *MyOrderedMap) Set(key string, v ValueWithIndex) {\n\tordmap.Set(om, key, v, getIndex, setIndex)\n}\n```\n\n### Using The Pre-Defined Ordered Map\n\nFor simplicity, an ordered map type is already defined for you. You only need to specify the key and value types:\n\n```go\npackage main\n\nimport (\n\t\"github.com/MarkRosemaker/ordmap\"\n)\n\ntype MyOrderedMap = ordmap.OrderedMap[string, *MyValue]\n\ntype MyValue struct {\n\tFoo string `json:\"foo\"`\n\tBar int    `json:\"bar\"`\n}\n```\n\n## Contributing\n\nIf you have any contributions to make, please submit a pull request or open an issue on the [GitHub repository](https://github.com/MarkRosemaker/ordmap).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkrosemaker%2Fordmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkrosemaker%2Fordmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkrosemaker%2Fordmap/lists"}