{"id":16304762,"url":"https://github.com/moznion/go-json-ice","last_synced_at":"2025-03-20T21:31:22.307Z","repository":{"id":41883660,"uuid":"266592960","full_name":"moznion/go-json-ice","owner":"moznion","description":"A simple code generator of JSON marshaler for go and tinygo.","archived":false,"fork":false,"pushed_at":"2024-10-04T21:27:34.000Z","size":128,"stargazers_count":9,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-17T23:54:58.191Z","etag":null,"topics":["json","tinygo"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moznion.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":"2020-05-24T17:40:16.000Z","updated_at":"2024-04-24T07:16:53.000Z","dependencies_parsed_at":"2022-08-11T20:01:17.340Z","dependency_job_id":"6edc037e-714a-4ae1-8739-cd35afe6ed5f","html_url":"https://github.com/moznion/go-json-ice","commit_stats":{"total_commits":69,"total_committers":3,"mean_commits":23.0,"dds":"0.24637681159420288","last_synced_commit":"962fb11320b6502f9bfa8f8169747f46acbc76a1"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2Fgo-json-ice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2Fgo-json-ice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2Fgo-json-ice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2Fgo-json-ice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moznion","download_url":"https://codeload.github.com/moznion/go-json-ice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244084321,"owners_count":20395516,"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":["json","tinygo"],"created_at":"2024-10-10T21:04:44.503Z","updated_at":"2025-03-20T21:31:21.950Z","avatar_url":"https://github.com/moznion.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-json-ice\n\nA simple code generator of JSON marshaler for go and tinygo.\n\nGenerated marshaler has fewer runtime dependencies (i.e. it __doesn't__ depend on `encoding/json` and reflection) and it's fast.\n\n## Motivation\n\n### for \"restricted\" tinygo environment\n\n[tinygo](https://github.com/tinygo-org/tinygo) doesn't support `encoding/json` package because reflection support is not enough: https://tinygo.org/lang-support/stdlib/#encoding-json\n\nThis library aims to marshal a struct to JSON on tinygo environment. And it also supposes to run this library in restricted environment; for example, wasm sandbox runtime.\n\nSo this library has the following features:\n\n- don't depend on `encoding/json` package\n- don't depend on `js` package\n  - i.e. don't depend on browser wasm runtime\n\nThis library has only one dependency for now, `strconv`.\n\n### Better performance\n\n`encoding/json` uses runtime reflection to marshal and unmarshal, but this library doesn't depend on it. Basically, code generation a marshaller statically by without reflection makes the performance be better.\n\n## Synopsis\n\n`go generate` with the following struct that uses `json-ice`,\n\n```go\n//go:generate json-ice --type=AwesomeStruct\ntype AwesomeStruct struct {\n\tFoo string `json:\"foo\"`\n\tBar string `json:\"bar,omitempty\"`\n}\n```\n\nthen it generates marshaler code as `MarshalAwesomeStructAsJSON(s *AwesomeStruct) ([]byte, error)`; you can use that like the following:\n\n```go\nmarshaled, err := MarshalAwesomeStructAsJSON(\u0026AwesomeStruct{\n\tFoo: \"buz\",\n\tBar: \"\",\n})\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Printf(\"%s\\n\", marshaled) // =\u003e {\"foo\":\"buz\"}\n```\n\n## Usage of the generator command\n\n```\njson-ice:\n  -cap-size int\n        [optional] a cap-size of a byte slice buffer for marshaling; by default, it calculates this value automatically\n  -output string\n        [optional] output file name (default \"srcdir/\u003ctype\u003e_gen.go\")\n  -toplevel-array\n        [optional] generate a marshaler for toplevel-array with given type by \"--type\" (e.g. \"[]string\")\n  -toplevel-map\n        [optional] generate a marshaler for toplevel-array with given type by \"--type\" (e.g. \"[]string\")\n  -type string\n        [mandatory] a type name\n  -version\n        show version information\n```\n\n## How to install\n\n```\n$ go get -u github.com/moznion/go-json-ice/cmd/json-ice\n```\n\nalso you can get the pre-built binaries on [Releases](https://github.com/moznion/go-json-ice/releases).\n\n## How it works\n\nParses given struct and generates a marshaler according to the parsed result; it means resolve fields statically without runtime reflection.\n\n## Performance\n\nIt calculates a cap-size of a byte slice buffer for marshaling automatically, but you can specify it by yourself.\n\nIf you need more throughput, it is a good idea to specify it as a bigger cap-size, on the other hand, if you would like to save the amount of memory, you can put it as a smaller (e.g. `1`) cap-size.\n\n### Benchmark\n\n```\n=== auto capsize ===\ngoos: darwin\ngoarch: amd64\npkg: github.com/moznion/go-json-ice/benchmark\nBenchmarkMarshal_EncodingJSON-12         1179334              1010 ns/op             320 B/op          1 allocs/op\nBenchmarkMarshal_JSONIce-12              2014201               629 ns/op             384 B/op          1 allocs/op\nPASS\nok      github.com/moznion/go-json-ice/benchmark        4.099s\n=== minimum capsize =\u003e 1 ===\ngoos: darwin\ngoarch: amd64\npkg: github.com/moznion/go-json-ice/benchmark\nBenchmarkMarshal_EncodingJSON-12         1136454              1003 ns/op             320 B/op          1 allocs/op\nBenchmarkMarshal_JSONIce-12              1421254               846 ns/op            1009 B/op          7 allocs/op\nPASS\nok      github.com/moznion/go-json-ice/benchmark        4.287s\n```\n\n`auto capsize` benchmarks it the default situation, and `minimum capsize` benchmarks it with the minimum cap-size (i.e. in worst performance case: `1`).\n\n`make bench` command benchmarks the performance.\n\n## FAQ\n\n### Does this library support JSON unmarshaling?\n\nNo, this only supports marshaling. If you are looking for a way to marshal JSON with tinygo, please consider using [buger/jsonparser](https://github.com/buger/jsonparser).\n\n### How to marshal non-primitive types\n\nFor example,\n\n```go\ntype Foo struct {\n\tHoge string `json:\"hoge\"`\n}\n\n//go:generate json-ice --type=Bar\ntype Bar struct {\n\tFoo *Foo `json:\"foo\"`\n}\n```\n\nIn this case, a marshaler for `Bar` tries to marshal `Foo` by `Foo.MarshalJSON() ([]byte, error)`. It means it expects the target type implements `json.Marshaler` when it tries to marshal a non-primitive type.\n\nThe easiest way to marshal the struct like the above is the follwoing:\n\n```go\n//go:generate json-ice --type=Foo\ntype Foo struct {\n\tHoge string `json:\"hoge\"`\n}\n\n//go:generate json-ice --type=Bar\ntype Bar struct {\n\tFoo *Foo `json:\"foo\"`\n}\n\nfunc (f *Foo) MarshalJSON() ([]byte, error) {\n\treturn MarshalFooAsJSON(f)\n}\n```\n\n### How to marshal toplevel array and map JSON\n\nIt is necessary to generate marshaler code by like the following instructions:\n\n- `//go:generate json-ice --type=[]string --toplevel-array`\n  - then, it generates a marshaler for toplevel array `[]string` as `MarshalStringArrayAsJSON(st []string) ([]byte, error)`\n- `//go:generate json-ice --type=map[string]string --toplevel-map`\n  - then, it generates a marshaler for toplevel map `map[string]string` as `MarshalStringToStringMapAsJSON(mt map[string]string) ([]byte, error)`\n\n## Restrictions / Known issues\n\n- it cannot marshal `interface{}` values\n  - because it doesn't use reflection so it cannot resolve the actual type dynamically\n  - in other words, the target type has to be resolvable as statically\n- it cannot marshal `named type` and `type alias` types automatically\n  - if you would like to marshal such them, please implement `json.Marshaler` on the type as like as the above FAQ answer.\n\n## How to build binaries\n\nBinaries are built and uploaded by [goreleaser](https://goreleaser.com/). Please refer to the configuration file: [.goreleaser.yml](./.goreleaser.yml)\n\n## Author\n\nmoznion (\u003cmoznion@gmail.com\u003e)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoznion%2Fgo-json-ice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoznion%2Fgo-json-ice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoznion%2Fgo-json-ice/lists"}