{"id":20187000,"url":"https://github.com/micronull/optional","last_synced_at":"2026-05-12T17:32:46.438Z","repository":{"id":262644630,"uuid":"887909264","full_name":"micronull/optional","owner":"micronull","description":"The optional package in Go provides a generic type that can represent values which may or may not be set,  including the concept of null. This allows handling scenarios where a value might be missing or explicitly set to null in JSON.","archived":false,"fork":false,"pushed_at":"2024-12-10T18:31:03.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-13T18:19:34.383Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/micronull.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-11-13T13:48:16.000Z","updated_at":"2024-12-10T18:31:06.000Z","dependencies_parsed_at":"2024-11-13T14:48:12.781Z","dependency_job_id":"e665e686-b729-4e19-9ae7-d2cbc96dca58","html_url":"https://github.com/micronull/optional","commit_stats":null,"previous_names":["micronull/optional"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micronull%2Foptional","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micronull%2Foptional/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micronull%2Foptional/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micronull%2Foptional/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micronull","download_url":"https://codeload.github.com/micronull/optional/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241622594,"owners_count":19992502,"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-11-14T03:19:32.051Z","updated_at":"2026-05-12T17:32:46.382Z","avatar_url":"https://github.com/micronull.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Optional Package\n\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/micronull/optional?style=flat-square)\n[![Go Reference](https://pkg.go.dev/badge/github.com/micronull/optional.svg)](https://pkg.go.dev/github.com/micronull/optional)\n[![Go Report Card](https://goreportcard.com/badge/github.com/micronull/optional?cache=v1)](https://goreportcard.com/report/github.com/micronull/optional)\n\nThe `optional` package in Go provides a generic type that can represent values which may or may not be set, \nincluding the concept of null. This allows handling scenarios where a value might be missing or explicitly set to null in JSON. \nThe package is designed to be flexible and efficient, with support for custom marshalling and unmarshalling functions.\n\n## Features\n\n- **Generic Type**: Supports any type `T`.\n- **Null Handling**: Distinguishes between unset values, null values, and non-null values.\n- **Custom Marshalling/Unmarshalling**: Allows changing the JSON marshalling/unmarshalling implementation, such as using a faster library like [json-iterator](https://pkg.go.dev/github.com/json-iterator/go).\n\n## Installation\n\nTo install the `optional` package, use the following command:\n\n```bash\ngo get github.com/micronull/optional\n```\n\n## Usage\n\n### Basic Usage\n\nHere's a simple example demonstrating how to use the `Type` struct and its methods:\n\n```go\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\n\t\"github.com/micronull/optional\"\n)\n\nfunc main() {\n\t// Create a new optional value that is not null\n\toptVal := optional.New[string](\"hello\", false)\n\tfmt.Println(optVal.IsSet())    // Output: true\n\tfmt.Println(optVal.IsSetNull()) // Output: false\n\n\t// Marshal the optional value to JSON\n\tjsonBytes, _ := json.Marshal(optVal)\n\tfmt.Println(string(jsonBytes)) // Output: \"hello\"\n\n\t// Create a new optional value that is explicitly null\n\toptNull := optional.New[string](\"\", true)\n\tfmt.Println(optNull.IsSet())    // Output: false\n\tfmt.Println(optNull.IsSetNull()) // Output: true\n\n\t// Marshal the null optional value to JSON\n\tjsonBytes, _ = json.Marshal(optNull)\n\tfmt.Println(string(jsonBytes)) // Output: null\n\n\t// Unmarshal JSON into an optional value\n\tvar opt optional.Type[string]\n\t\n\tfmt.Println(opt.IsSet()) // Output: false\n\tfmt.Println(opt.IsSetNull()) // Output: false\n\t\n\tjson.Unmarshal([]byte(`\"world\"`), \u0026opt)\n\tfmt.Println(opt.V) // Output: world\n\tfmt.Println(opt.IsSet()) // Output: true\n\tfmt.Println(opt.IsSetNull()) // Output: false\n\n\tjson.Unmarshal([]byte(`null`), \u0026opt)\n\tfmt.Println(opt.IsSet()) // Output: true\n\tfmt.Println(opt.IsSetNull()) // Output: true\n}\n```\n\n### Custom Marshalling/Unmarshalling\n\nYou can replace the default JSON marshalling and unmarshalling functions with your own implementations, such as using [json-iterator](https://pkg.go.dev/github.com/json-iterator/go):\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\tjsoniter \"github.com/json-iterator/go\"\n\n\t\"github.com/micronull/optional\"\n)\n\nfunc init() {\n\t// Replace the default marshaller with json-iterator's marshaller\n\toptional.ChangeMarshal(jsoniter.Marshal)\n\t// Replace the default unmarshaller with json-iterator's unmarshaller\n\toptional.ChangeUnmarshal(jsoniter.Unmarshal)\n}\n\nfunc main() {\n\toptVal := optional.New[string](\"hello\", false)\n\n\tjsonBytes, _ := jsoniter.Marshal(optVal)\n\tfmt.Println(string(jsonBytes)) // Output: \"hello\"\n}\n```\n\n## Contributing\n\nContributions are welcome! If you have any suggestions or find a bug, please open an issue on the [GitHub repository](https://github.com/micronull/optional).\n\n## License\n\nThis package is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicronull%2Foptional","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicronull%2Foptional","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicronull%2Foptional/lists"}