{"id":16122108,"url":"https://github.com/foxcapades/lib-java-opt","last_synced_at":"2025-04-06T11:41:35.422Z","repository":{"id":57732076,"uuid":"397624573","full_name":"Foxcapades/lib-java-opt","owner":"Foxcapades","description":"Extensible alternative to Java's built-in option type.","archived":false,"fork":false,"pushed_at":"2021-08-19T02:20:42.000Z","size":234,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-12T17:19:28.116Z","etag":null,"topics":["java","lib","library","option","optional","options"],"latest_commit_sha":null,"homepage":"","language":"Java","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/Foxcapades.png","metadata":{"files":{"readme":"readme.adoc","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}},"created_at":"2021-08-18T14:12:13.000Z","updated_at":"2021-08-19T02:20:45.000Z","dependencies_parsed_at":"2022-08-25T14:10:18.128Z","dependency_job_id":null,"html_url":"https://github.com/Foxcapades/lib-java-opt","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-java-opt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-java-opt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-java-opt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-java-opt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Foxcapades","download_url":"https://codeload.github.com/Foxcapades/lib-java-opt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478234,"owners_count":20945262,"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":["java","lib","library","option","optional","options"],"created_at":"2024-10-09T21:09:24.068Z","updated_at":"2025-04-06T11:41:35.398Z","avatar_url":"https://github.com/Foxcapades.png","language":"Java","readme":"= Extensible Java Options\n:dep-version: 1.1.0\n\nimage:https://img.shields.io/badge/Java-16-ff69b4[]\nimage:https://img.shields.io/badge/license-MIT-brightgreen[]\nimage:https://img.shields.io/badge/docs-javadoc-blue[link=\"https://foxcapades.github.io/lib-java-opt/foxcapades.lib.opt/module-summary.html\"]\nimage:https://img.shields.io/maven-central/v/io.foxcapades.lib/opt[link=\"https://search.maven.org/artifact/io.foxcapades.lib/opt/{dep-version}/jar\"]\n\nProvides an alternative, extensible alternative to Java's built-in `Optional`\ntype.\n\nAdditionally, this library adds a \"3 state\" option type for wrapping values that\ncould be present, absent, or `null`.  (The built-in Java option does not support\nwrapping `null`).\n\n== Features\n\nThe root of this library is the `Option\u003cT\u003e` interface which is subclassed by the\ninterfaces `NullableOption\u003cT\u003e` and `NonNullOption\u003cT\u003e`.\n\n=== `Option\u003cT\u003e`\n\n`Option` is the base interface for the library and includes most if not all the\nfeatures of the built-in `Optional` type.\n\n=== `NonNullOption\u003cT\u003e`\n\n`NonNullOption` extends the `Option` interface and is a more of a direct mirror\nof the built-in `Optional`.  Implementations of this interface do not allow\nwrapping `null` and translate `null` to \"empty\".\n\n=== `NullableOption\u003cT\u003e`\n\nThe `NullableOption\u003cT\u003e` extends the `Option` interface and provides additional\nfunctionality for dealing with `null` values.\n\n== Usage\n\nThe primary entry point for this library is the included `Opt` factory which is\nused to construct the different `Option` types.  This factory includes a\nstandard configuration, but may be overridden with an alternate implementation.\n\n.Creating a `NullableOption`\n[source, java]\n----\n// Empty nullable option\nvar opt1 = Opt.nullable();\n\n// Nullable option wrapping null\nvar opt2 = Opt.nullable(null);\n\n// Nullable option wrapping a non-null value\nvar opt3 = Opt.nullable(\"hello\");\n----\n\n.Creating a `NonNullOption`\n[source, java]\n----\n// Empty option\nvar opt1 = Opt.nonNull();\n\n// Empty option\nvar opt2 = Opt.nonNullOfNullable(null);\n\n// Non-empty option\nvar opt3 = Opt.nonNull(1234);\n\n// Non-empty option\nvar opt4 = Opt.nonNullOfNullable(\"goodbye\");\n\n// Throws NullPointerException\nvar opt5 = Opt.nonNull(null);\n----\n\n=== Dependency Config\n\n.Maven\n[source, xml, subs=\"+attributes\"]\n----\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.foxcapades.lib\u003c/groupId\u003e\n  \u003cartifactId\u003eopt\u003c/artifactId\u003e\n  \u003cversion\u003e{dep-version}\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n.Gradle Groovy\n[source, groovy, subs=\"+attributes\"]\n----\nimplementation 'io.foxcapades.lib:opt:{dep-version}'\n----\n\n.Gradle Kotlin\n[source, kotlin, subs=\"+attributes\"]\n----\nimplementation(\"io.foxcapades.lib:opt:{dep-version}\")\n----\n\n=== Factory Building Custom Implementations\n\nUsing custom implementations of option types may be used with the option factory\n`Opt` by extending the `Opt` class and setting it as the default/singleton\ninstance.\n\n.Overriding to provide a custom null option type.\n[source, java]\n----\npublic class MyOpt extends Opt {\n  @Override\n  public \u003cT\u003e NullableOption\u003cT\u003e newNullable() {\n    return new MyOption\u003c\u003e();\n  }\n}\n\n...\n\nOpt.setStandardInstance(new MyOpt());\n\nassert Opt.nullable() instanceof MyOpt;\n----\n\n== Reasoning\n\nIn practice, especially when dealing with external APIs, I have personally found\nmyself frustrated with the `Optional` type's lack of features, inability to wrap\n`null`, and the fact that the type is `final` so desired features could not even\nbe added.\n\n== Why would you want to wrap `null`?\n\nIdeally, you wouldn't.  However, many APIs differentiate between a property\nbeing absent, vs being present and null, vs being present and not-null.  One\npopular example of such an API would be JSON patch.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxcapades%2Flib-java-opt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoxcapades%2Flib-java-opt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxcapades%2Flib-java-opt/lists"}