{"id":16768232,"url":"https://github.com/markphelps/optional","last_synced_at":"2025-10-05T15:07:50.063Z","repository":{"id":37926939,"uuid":"98122773","full_name":"markphelps/optional","owner":"markphelps","description":"Optional is a library of optional Go types","archived":false,"fork":false,"pushed_at":"2023-07-08T17:42:28.000Z","size":284,"stargazers_count":218,"open_issues_count":6,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-30T19:07:03.061Z","etag":null,"topics":["go","go-generate","golang","optional"],"latest_commit_sha":null,"homepage":"https://godoc.org/github.com/markphelps/optional","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/markphelps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2017-07-23T20:13:32.000Z","updated_at":"2025-03-14T03:29:19.000Z","dependencies_parsed_at":"2024-06-18T14:07:29.805Z","dependency_job_id":"0f8c22b5-7975-485b-82fc-7d57e9f33b6c","html_url":"https://github.com/markphelps/optional","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markphelps%2Foptional","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markphelps%2Foptional/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markphelps%2Foptional/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markphelps%2Foptional/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markphelps","download_url":"https://codeload.github.com/markphelps/optional/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543595,"owners_count":20955865,"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":["go","go-generate","golang","optional"],"created_at":"2024-10-13T06:11:04.309Z","updated_at":"2025-10-05T15:07:45.019Z","avatar_url":"https://github.com/markphelps.png","language":"Go","readme":"# Optional\n\n[![CI](https://github.com/markphelps/optional/actions/workflows/go.yml/badge.svg)](https://github.com/markphelps/optional/actions/workflows/go.yml)\n[![Release](https://img.shields.io/github/release/markphelps/optional.svg?style=flat-square)](https://github.com/markphelps/optional/releases/latest)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)\n[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/markphelps/optional)\n[![Go Report Card](https://goreportcard.com/badge/github.com/markphelps/optional?style=flat-square)](https://goreportcard.com/report/github.com/markphelps/optional)\n[![SayThanks.io](https://img.shields.io/badge/SayThanks.io-%E2%98%BC-1EAEDB.svg?style=flat-square)](https://saythanks.io/to/markphelps)\n\nOptional is a library that provides option types for the primitive Go types.\n\nIt can also be used as a tool to generate option type wrappers around your own types.\n\n## Motivation\n\nIn Go, variables declared without an explicit initial value are given their zero value. Most of the time this is what you want, but sometimes you want to be able to tell if a variable was set or if it's just a zero value. That's where [option types](https://en.wikipedia.org/wiki/Option_type) come in handy.\n\n## Inspiration\n\n- Java [Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html)\n- [https://github.com/leighmcculloch/go-optional](https://github.com/leighmcculloch/go-optional)\n- [https://github.com/golang/go/issues/7054](https://github.com/golang/go/issues/7054)\n\n## Tool\n\n### Install\n\n`go get -u github.com/markphelps/optional/cmd/optional`\n\n### Usage\n\nTypically this process would be run using go generate, like this:\n\n```go\nimport _ \"github.com/markphelps/optional\n\n//go:generate optional -type=Foo\ntype Foo struct {\n  ...\n}\n```\n\n🗒️ **Note**: the blank import is necessary to prevent `go mod tidy` from removing this library as a dependency if you are only using it to generate your own types.\n\nrunning this command:\n\n```bash\noptional -type=Foo\n```\n\nin the same directory will create the file optional_foo.go\ncontaining a definition of:\n\n```go\ntype OptionalFoo struct {\n  ...\n}\n```\n\nThe default type is OptionalT or optionalT (depending on if the type is exported)\nand output file is optional_t.go. This can be overridden with the -output flag.\n\n## Library\n\n- [bool](bool.go)\n- [byte](byte.go)\n- [complex128](complex128.go)\n- [complex64](complex64.go)\n- [float32](float32.go)\n- [float64](float64.go)\n- [int](int.go)\n- [int16](int16.go)\n- [int32](int32.go)\n- [int64](int64.go)\n- [int8](int8.go)\n- [rune](rune.go)\n- [string](string.go)\n- [uint](uint.go)\n- [uint16](uint16.go)\n- [uint32](uint32.go)\n- [uint64](uint64.go)\n- [uint8](uint8.go)\n- [uintptr](uintptr.go)\n- [error](error.go)\n\n### Usage\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/markphelps/optional\"\n)\n\nfunc main() {\n    s := optional.NewString(\"foo\")\n\n    value, err := s.Get()\n    if err != nil {\n        // handle error!\n    } else {\n        fmt.Println(value)\n    }\n\n    t := optional.String{}\n    fmt.Println(t.OrElse(\"bar\"))\n}\n```\n\nSee [example_test.go](example_test.go) and the [documentation](http://godoc.org/github.com/markphelps/optional) for more usage.\n\n## Marshalling/Unmarshalling JSON\n\n**Note:** v0.6.0 introduces a potential breaking change to anyone depending on marshalling non-present values to their zero values instead of null. See: [#9](https://github.com/markphelps/optional/pull/9) for more context.\n\n**Note:** v0.8.0 removes JSON support from `complex64` and `complex128` types per [#13](https://github.com/markphelps/optional/issues/13)\n\nOption types marshal to/from JSON as you would expect:\n\n### Marshalling\n\n```go\npackage main\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n)\n\nfunc main() {\n    var value = struct {\n        Field optional.String `json:\"field,omitempty\"`\n    }{\n        Field: optional.NewString(\"bar\"),\n    }\n\n    out, _ := json.Marshal(value)\n\n    fmt.Println(string(out))\n    // outputs: {\"field\":\"bar\"}\n}\n```\n\n### Unmarshalling\n\n```go\npackage main\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n)\n\nfunc main() {\n    var value = \u0026struct {\n        Field optional.String `json:\"field,omitempty\"`\n    }{}\n\n    _ = json.Unmarshal([]byte(`{\"field\":\"bar\"}`), value)\n\n    value.Field.If(func(s string) {\n        fmt.Println(s)\n    })\n    // outputs: bar\n}\n```\n\nSee [example_test.go](example_test.go) for more examples.\n\n## Test Coverage\n\nAs you can see test coverage is a bit lacking for the library. This is simply because testing generated code is not super easy. I'm currently working on improving test coverage for the generated types, but in the meantime checkout [string_test.go](string_test.go) and [int_test.go](int_test.go) for examples.\n\nAlso checkout:\n\n- [example_test.go](example_test.go) for example usage.\n- [cmd/optional/golden_test.go](cmd/optional/golden_test.go) for [golden file](https://medium.com/soon-london/testing-with-golden-files-in-go-7fccc71c43d3) based testing of the generator itself.\n\n### Golden Files\n\nIf changing the API you may need to update the [golden files](https://medium.com/soon-london/testing-with-golden-files-in-go-7fccc71c43d3) for your tests to pass by running:\n\n`go test ./cmd/optional/... -update`.\n\n## Contributing\n\n1. [Fork it](https://github.com/markphelps/optional/fork)\n1. Create your feature branch (`git checkout -b my-new-feature`)\n1. Commit your changes (`git commit -am 'feat: Add some feature'`)\n1. Push to the branch (`git push origin my-new-feature`)\n1. Create a new Pull Request\n\n### Conventional Commits\n\nOptional uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. This allows us to automatically generate changelogs and releases.\n\nTo help with this, we use [pre-commit](https://pre-commit.com/) to automatically lint commit messages. To install pre-commit, run:\n\n`pip install pre-commit` or `brew install pre-commit` (if you're on a Mac)\n\nThen run `pre-commit install` to install the git hook.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkphelps%2Foptional","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkphelps%2Foptional","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkphelps%2Foptional/lists"}